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 | |
f37e7e3d 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 | ||
f37e7e3d DH |
16 | Copyright @copyright{} 1991-2006 Silicon Graphics, Inc. This document is |
17 | 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 | ||
f37e7e3d | 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 | ||
f37e7e3d | 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 | ||
f37e7e3d | 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} | |
f37e7e3d | 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 | |
f37e7e3d | 48 | operation. @var{op} determines how @var{value} is used. |
8925f36f AW |
49 | |
50 | @end table | |
51 | ||
f37e7e3d 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 |
f37e7e3d | 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 | |
f37e7e3d 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}, | |
f37e7e3d DH |
64 | @code{GL_ACCUM_BLUE_BITS}, and @code{GL_ACCUM_ALPHA_BITS}. Regardless of |
65 | the number of bits per component, the range of values stored by each | |
66 | component is @r{[-1,1]}. The accumulation buffer pixels are mapped | |
8925f36f AW |
67 | one-to-one with frame buffer pixels. |
68 | ||
f37e7e3d | 69 | @code{glAccum} operates on the accumulation buffer. The first argument, |
8925f36f | 70 | @var{op}, is a symbolic constant that selects an accumulation buffer |
f37e7e3d 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 | |
f37e7e3d DH |
78 | alpha components of each pixel. If a @code{glAccum} operation results in |
79 | a value outside the range @r{[-1,1]}, the contents of an accumulation | |
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 | |
f37e7e3d | 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 |
f37e7e3d | 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 | |
f37e7e3d | 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 | |
f37e7e3d | 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} | |
f37e7e3d DH |
142 | Specifies which texture unit to make active. The number of texture units |
143 | is implementation dependent, but must be at least two. @var{texture} | |
144 | must be one of @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to | |
145 | the larger of (@code{GL_MAX_TEXTURE_COORDS} - 1) and | |
146 | (@code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS} - 1). The initial value is | |
8925f36f AW |
147 | @code{GL_TEXTURE0}. |
148 | ||
149 | @end table | |
150 | ||
8925f36f | 151 | @code{glActiveTexture} selects which texture unit subsequent texture |
f37e7e3d | 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} | |
f37e7e3d | 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 | |
f37e7e3d | 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 | |
f37e7e3d DH |
177 | to. This value is clamped to the range @r{[0,1]}, where 0 represents the |
178 | lowest possible alpha value and 1 the highest possible value. The | |
8925f36f AW |
179 | initial reference value is 0. |
180 | ||
181 | @end table | |
182 | ||
8925f36f AW |
183 | The alpha test discards fragments depending on the outcome of a |
184 | comparison between an incoming fragment's alpha value and a constant | |
f37e7e3d 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 @code{glEnable} | |
188 | 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 | |
f37e7e3d 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 |
f37e7e3d DH |
194 | depth buffer tests. If the value fails the comparison, no change is made |
195 | to the frame buffer at that pixel location. The comparison functions are | |
196 | as follows: | |
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 | |
f37e7e3d | 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 |
f37e7e3d | 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 | |
f37e7e3d | 263 | @var{n} textures named by the elements of @var{textures}. If all the |
8925f36f | 264 | named textures are resident, @code{glAreTexturesResident} returns |
f37e7e3d | 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} | |
f37e7e3d | 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 | |
f37e7e3d | 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 | |
f37e7e3d | 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 | |
f37e7e3d | 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 | |
f37e7e3d | 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 | |
f37e7e3d | 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 | |
f37e7e3d | 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 |
f37e7e3d 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 | |
f37e7e3d | 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 | |
f37e7e3d | 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 | |
f37e7e3d | 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 |
f37e7e3d 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 | |
f37e7e3d | 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 |
f37e7e3d DH |
397 | query object. If a query object with name @var{id} does not yet exist it |
398 | is created. | |
8925f36f AW |
399 | |
400 | When @code{glBeginQuery} is executed, the query object's samples-passed | |
f37e7e3d DH |
401 | counter is reset to 0. Subsequent rendering will increment the counter |
402 | once for every sample that passes the depth test. When @code{glEndQuery} | |
403 | is executed, the samples-passed counter is assigned to the query | |
404 | object's result value. This value can be queried by calling | |
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 | |
f37e7e3d | 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 | |
f37e7e3d | 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 |
f37e7e3d DH |
450 | primitive or a group of like primitives. @code{glBegin} accepts a single |
451 | argument that specifies in which of ten ways the vertices are | |
452 | interpreted. Taking @r{@var{n}} as an integer count starting at one, and | |
453 | @r{@var{N}} as the total number of vertices specified, the | |
8925f36f AW |
454 | interpretations are as follows: |
455 | ||
456 | @table @asis | |
457 | @item @code{GL_POINTS} | |
f37e7e3d 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} | |
f37e7e3d 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 | |
f37e7e3d | 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 | |
f37e7e3d 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} | |
f37e7e3d | 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 |
f37e7e3d | 480 | @r{@var{n}}. @r{@var{N}/3} triangles are drawn. |
8925f36f AW |
481 | |
482 | @item @code{GL_TRIANGLE_STRIP} | |
f37e7e3d 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 |
f37e7e3d 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} | |
f37e7e3d 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 |
f37e7e3d | 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} | |
f37e7e3d 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} |
f37e7e3d 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} | |
f37e7e3d | 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 | |
f37e7e3d | 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}, | |
f37e7e3d | 522 | @code{glArrayElement}, @code{glMaterial}, and @code{glEdgeFlag}. Also, |
8925f36f | 523 | it is acceptable to use @code{glCallList} or @code{glCallLists} to |
f37e7e3d | 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 | |
f37e7e3d 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 |
f37e7e3d | 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, | |
f37e7e3d | 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 | |
f37e7e3d DH |
593 | a generic vertex attribute index. The name of the user-defined attribute |
594 | variable is passed as a null terminated string in @var{name}. The | |
595 | generic vertex attribute index to be bound to this variable is specified | |
596 | by @var{index}. When @var{program} is made part of current state, values | |
597 | provided via the generic vertex attribute @var{index} will modify the | |
598 | value of the user-defined attribute variable specified by @var{name}. | |
8925f36f AW |
599 | |
600 | If @var{name} refers to a matrix attribute variable, @var{index} refers | |
f37e7e3d | 601 | to the first column of the matrix. Other matrix columns are then |
8925f36f AW |
602 | automatically bound to locations @var{index+1} for a matrix of type |
603 | mat2; @var{index+1} and @var{index+2} for a matrix of type mat3; and | |
604 | @var{index+1}, @var{index+2}, and @var{index+3} for a matrix of type | |
605 | mat4. | |
606 | ||
607 | This command makes it possible for vertex shaders to use descriptive | |
608 | names for attribute variables rather than generic variables that are | |
f37e7e3d | 609 | numbered from 0 to @code{GL_MAX_VERTEX_ATTRIBS} -1. The values sent to |
8925f36f AW |
610 | each generic attribute index are part of current state, just like |
611 | standard vertex attributes such as color, normal, and vertex position. | |
612 | If a different program object is made current by calling | |
613 | @code{glUseProgram}, the generic vertex attributes are tracked in such a | |
614 | way that the same values will be observed by attributes in the new | |
615 | program object that are also bound to @var{index}. | |
616 | ||
617 | Attribute variable name-to-generic attribute index bindings for a | |
618 | program object can be explicitly assigned at any time by calling | |
f37e7e3d DH |
619 | @code{glBindAttribLocation}. Attribute bindings do not go into effect |
620 | until @code{glLinkProgram} is called. After a program object has been | |
8925f36f AW |
621 | linked successfully, the index values for generic attributes remain |
622 | fixed (and their values can be queried) until the next link command | |
623 | occurs. | |
624 | ||
625 | Applications are not allowed to bind any of the standard OpenGL vertex | |
626 | attributes using this command, as they are bound automatically when | |
f37e7e3d | 627 | needed. Any attribute binding that occurs after the program object has |
8925f36f AW |
628 | been linked will not take effect until the next time the program object |
629 | is linked. | |
630 | ||
8925f36f AW |
631 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
632 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
633 | ||
634 | @code{GL_INVALID_OPERATION} is generated if @var{name} starts with the | |
635 | reserved prefix "gl_". | |
636 | ||
637 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
638 | generated by OpenGL. | |
639 | ||
640 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
641 | program object. | |
642 | ||
643 | @code{GL_INVALID_OPERATION} is generated if @code{glBindAttribLocation} | |
644 | is executed between the execution of @code{glBegin} and the | |
645 | corresponding execution of @code{glEnd}. | |
646 | ||
bb894c9d | 647 | @end deftypefun |
8925f36f | 648 | |
bb894c9d | 649 | @deftypefun void glBindBuffer target buffer |
3c9b6116 AW |
650 | Bind a named buffer object. |
651 | ||
8925f36f AW |
652 | @table @asis |
653 | @item @var{target} | |
f37e7e3d | 654 | Specifies the target to which the buffer object is bound. The symbolic |
8925f36f AW |
655 | constant must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
656 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
657 | ||
658 | @item @var{buffer} | |
659 | Specifies the name of a buffer object. | |
660 | ||
661 | @end table | |
662 | ||
8925f36f AW |
663 | @code{glBindBuffer} lets you create or use a named buffer object. |
664 | Calling @code{glBindBuffer} with @var{target} set to | |
665 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
666 | @code{GL_PIXEL_PACK_BUFFER} or @code{GL_PIXEL_UNPACK_BUFFER} and | |
667 | @var{buffer} set to the name of the new buffer object binds the buffer | |
f37e7e3d | 668 | object name to the target. When a buffer object is bound to a target, |
8925f36f AW |
669 | the previous binding for that target is automatically broken. |
670 | ||
f37e7e3d | 671 | Buffer object names are unsigned integers. The value zero is reserved, |
8925f36f AW |
672 | but there is no default buffer object for each buffer object target. |
673 | Instead, @var{buffer} set to zero effectively unbinds any buffer object | |
674 | previously bound, and restores client memory usage for that buffer | |
f37e7e3d | 675 | object target. Buffer object names and the corresponding buffer object |
8925f36f AW |
676 | contents are local to the shared display-list space (see |
677 | @code{glXCreateContext}) of the current GL rendering context; two | |
678 | rendering contexts share buffer object names only if they also share | |
679 | display lists. | |
680 | ||
681 | You may use @code{glGenBuffers} to generate a set of new buffer object | |
682 | names. | |
683 | ||
684 | The state of a buffer object immediately after it is first bound is an | |
685 | unmapped zero-sized memory buffer with @code{GL_READ_WRITE} access and | |
686 | @code{GL_STATIC_DRAW} usage. | |
687 | ||
688 | While a non-zero buffer object name is bound, GL operations on the | |
689 | target to which it is bound affect the bound buffer object, and queries | |
690 | of the target to which it is bound return state from the bound buffer | |
f37e7e3d DH |
691 | object. While buffer object name zero is bound, as in the initial state, |
692 | attempts to modify or query state on the target to which it is bound | |
693 | generates an @code{GL_INVALID_OPERATION} error. | |
8925f36f AW |
694 | |
695 | When vertex array pointer state is changed, for example by a call to | |
696 | @code{glNormalPointer}, the current buffer object binding | |
697 | (@code{GL_ARRAY_BUFFER_BINDING}) is copied into the corresponding client | |
698 | state for the vertex array type being changed, for example | |
f37e7e3d DH |
699 | @code{GL_NORMAL_ARRAY_BUFFER_BINDING}. While a non-zero buffer object is |
700 | bound to the @code{GL_ARRAY_BUFFER} target, the vertex array pointer | |
8925f36f AW |
701 | parameter that is traditionally interpreted as a pointer to client-side |
702 | memory is instead interpreted as an offset within the buffer object | |
703 | measured in basic machine units. | |
704 | ||
705 | While a non-zero buffer object is bound to the | |
706 | @code{GL_ELEMENT_ARRAY_BUFFER} target, the indices parameter of | |
707 | @code{glDrawElements}, @code{glDrawRangeElements}, or | |
708 | @code{glMultiDrawElements} that is traditionally interpreted as a | |
709 | pointer to client-side memory is instead interpreted as an offset within | |
710 | the buffer object measured in basic machine units. | |
711 | ||
712 | While a non-zero buffer object is bound to the | |
713 | @code{GL_PIXEL_PACK_BUFFER} target, the following commands are affected: | |
714 | @code{glGetCompressedTexImage}, @code{glGetConvolutionFilter}, | |
715 | @code{glGetHistogram}, @code{glGetMinmax}, @code{glGetPixelMap}, | |
716 | @code{glGetPolygonStipple}, @code{glGetSeparableFilter}, | |
f37e7e3d | 717 | @code{glGetTexImage}, and @code{glReadPixels}. The pointer parameter |
8925f36f AW |
718 | that is traditionally interpreted as a pointer to client-side memory |
719 | where the pixels are to be packed is instead interpreted as an offset | |
720 | within the buffer object measured in basic machine units. | |
721 | ||
722 | While a non-zero buffer object is bound to the | |
723 | @code{GL_PIXEL_UNPACK_BUFFER} target, the following commands are | |
724 | affected: @code{glBitmap}, @code{glColorSubTable}, @code{glColorTable}, | |
725 | @code{glCompressedTexImage1D}, @code{glCompressedTexImage2D}, | |
726 | @code{glCompressedTexImage3D}, @code{glCompressedTexSubImage1D}, | |
727 | @code{glCompressedTexSubImage2D}, @code{glCompressedTexSubImage3D}, | |
728 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, | |
729 | @code{glDrawPixels}, @code{glPixelMap}, @code{glPolygonStipple}, | |
730 | @code{glSeparableFilter2D}, @code{glTexImage1D}, @code{glTexImage2D}, | |
731 | @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, and | |
f37e7e3d | 732 | @code{glTexSubImage3D}. The pointer parameter that is traditionally |
8925f36f AW |
733 | interpreted as a pointer to client-side memory from which the pixels are |
734 | to be unpacked is instead interpreted as an offset within the buffer | |
735 | object measured in basic machine units. | |
736 | ||
737 | A buffer object binding created with @code{glBindBuffer} remains active | |
738 | until a different buffer object name is bound to the same target, or | |
739 | until the bound buffer object is deleted with @code{glDeleteBuffers}. | |
740 | ||
741 | Once created, a named buffer object may be re-bound to any target as | |
f37e7e3d | 742 | often as needed. However, the GL implementation may make choices about |
8925f36f AW |
743 | how to optimize the storage of a buffer object based on its initial |
744 | binding target. | |
745 | ||
8925f36f AW |
746 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
747 | allowable values. | |
748 | ||
749 | @code{GL_INVALID_OPERATION} is generated if @code{glBindBuffer} is | |
750 | executed between the execution of @code{glBegin} and the corresponding | |
751 | execution of @code{glEnd}. | |
752 | ||
bb894c9d | 753 | @end deftypefun |
8925f36f | 754 | |
bb894c9d | 755 | @deftypefun void glBindTexture target texture |
3c9b6116 AW |
756 | Bind a named texture to a texturing target. |
757 | ||
8925f36f AW |
758 | @table @asis |
759 | @item @var{target} | |
f37e7e3d | 760 | Specifies the target to which the texture is bound. Must be either |
8925f36f AW |
761 | @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or |
762 | @code{GL_TEXTURE_CUBE_MAP}. | |
763 | ||
764 | @item @var{texture} | |
765 | Specifies the name of a texture. | |
766 | ||
767 | @end table | |
768 | ||
f37e7e3d | 769 | @code{glBindTexture} lets you create or use a named texture. Calling |
8925f36f AW |
770 | @code{glBindTexture} with @var{target} set to @code{GL_TEXTURE_1D}, |
771 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D} or @code{GL_TEXTURE_CUBE_MAP} | |
772 | and @var{texture} set to the name of the new texture binds the texture | |
f37e7e3d | 773 | name to the target. When a texture is bound to a target, the previous |
8925f36f AW |
774 | binding for that target is automatically broken. |
775 | ||
f37e7e3d DH |
776 | Texture names are unsigned integers. The value zero is reserved to |
777 | represent the default texture for each texture target. Texture names and | |
778 | the corresponding texture contents are local to the shared display-list | |
779 | space (see @code{glXCreateContext}) of the current GL rendering context; | |
780 | two rendering contexts share texture names only if they also share | |
781 | display lists. | |
8925f36f AW |
782 | |
783 | You may use @code{glGenTextures} to generate a set of new texture names. | |
784 | ||
785 | When a texture is first bound, it assumes the specified target: A | |
786 | texture first bound to @code{GL_TEXTURE_1D} becomes one-dimensional | |
787 | texture, a texture first bound to @code{GL_TEXTURE_2D} becomes | |
788 | two-dimensional texture, a texture first bound to @code{GL_TEXTURE_3D} | |
789 | becomes three-dimensional texture, and a texture first bound to | |
f37e7e3d DH |
790 | @code{GL_TEXTURE_CUBE_MAP} becomes a cube-mapped texture. The state of a |
791 | one-dimensional texture immediately after it is first bound is | |
8925f36f AW |
792 | equivalent to the state of the default @code{GL_TEXTURE_1D} at GL |
793 | initialization, and similarly for two- and three-dimensional textures | |
794 | and cube-mapped textures. | |
795 | ||
796 | While a texture is bound, GL operations on the target to which it is | |
797 | bound affect the bound texture, and queries of the target to which it is | |
f37e7e3d DH |
798 | bound return state from the bound texture. If texture mapping is active |
799 | on the target to which a texture is bound, the bound texture is used. In | |
8925f36f AW |
800 | effect, the texture targets become aliases for the textures currently |
801 | bound to them, and the texture name zero refers to the default textures | |
802 | that were bound to them at initialization. | |
803 | ||
804 | A texture binding created with @code{glBindTexture} remains active until | |
805 | a different texture is bound to the same target, or until the bound | |
806 | texture is deleted with @code{glDeleteTextures}. | |
807 | ||
808 | Once created, a named texture may be re-bound to its same original | |
f37e7e3d | 809 | target as often as needed. It is usually much faster to use |
8925f36f AW |
810 | @code{glBindTexture} to bind an existing named texture to one of the |
811 | texture targets than it is to reload the texture image using | |
f37e7e3d | 812 | @code{glTexImage1D}, @code{glTexImage2D}, or @code{glTexImage3D}. For |
8925f36f AW |
813 | additional control over performance, use @code{glPrioritizeTextures}. |
814 | ||
815 | @code{glBindTexture} is included in display lists. | |
816 | ||
8925f36f AW |
817 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
818 | allowable values. | |
819 | ||
820 | @code{GL_INVALID_OPERATION} is generated if @var{texture} was previously | |
821 | created with a target that doesn't match that of @var{target}. | |
822 | ||
823 | @code{GL_INVALID_OPERATION} is generated if @code{glBindTexture} is | |
824 | executed between the execution of @code{glBegin} and the corresponding | |
825 | execution of @code{glEnd}. | |
826 | ||
bb894c9d | 827 | @end deftypefun |
8925f36f | 828 | |
bb894c9d | 829 | @deftypefun void glBitmap width height xorig yorig xmove ymove bitmap |
3c9b6116 AW |
830 | Draw a bitmap. |
831 | ||
8925f36f AW |
832 | @table @asis |
833 | @item @var{width} | |
834 | @itemx @var{height} | |
835 | Specify the pixel width and height of the bitmap image. | |
836 | ||
837 | @item @var{xorig} | |
838 | @itemx @var{yorig} | |
f37e7e3d | 839 | Specify the location of the origin in the bitmap image. The origin is |
8925f36f AW |
840 | measured from the lower left corner of the bitmap, with right and up |
841 | being the positive axes. | |
842 | ||
843 | @item @var{xmove} | |
844 | @itemx @var{ymove} | |
845 | Specify the @var{x} and @var{y} offsets to be added to the current | |
846 | raster position after the bitmap is drawn. | |
847 | ||
848 | @item @var{bitmap} | |
849 | Specifies the address of the bitmap image. | |
850 | ||
851 | @end table | |
852 | ||
f37e7e3d | 853 | A bitmap is a binary image. When drawn, the bitmap is positioned |
8925f36f AW |
854 | relative to the current raster position, and frame buffer pixels |
855 | corresponding to 1's in the bitmap are written using the current raster | |
f37e7e3d | 856 | color or index. Frame buffer pixels corresponding to 0's in the bitmap |
8925f36f AW |
857 | are not modified. |
858 | ||
f37e7e3d DH |
859 | @code{glBitmap} takes seven arguments. The first pair specifies the |
860 | width and height of the bitmap image. The second pair specifies the | |
8925f36f | 861 | location of the bitmap origin relative to the lower left corner of the |
f37e7e3d | 862 | bitmap image. The third pair of arguments specifies @var{x} and @var{y} |
8925f36f | 863 | offsets to be added to the current raster position after the bitmap has |
f37e7e3d | 864 | been drawn. The final argument is a pointer to the bitmap image itself. |
8925f36f AW |
865 | |
866 | If a non-zero named buffer object is bound to the | |
867 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
868 | bitmap image is specified, @var{bitmap} is treated as a byte offset into | |
869 | the buffer object's data store. | |
870 | ||
871 | The bitmap image is interpreted like image data for the | |
872 | @code{glDrawPixels} command, with @var{width} and @var{height} | |
873 | corresponding to the width and height arguments of that command, and | |
874 | with @var{type} set to @code{GL_BITMAP} and @var{format} set to | |
f37e7e3d | 875 | @code{GL_COLOR_INDEX}. Modes specified using @code{glPixelStore} affect |
8925f36f AW |
876 | the interpretation of bitmap image data; modes specified using |
877 | @code{glPixelTransfer} do not. | |
878 | ||
879 | If the current raster position is invalid, @code{glBitmap} is ignored. | |
880 | Otherwise, the lower left corner of the bitmap image is positioned at | |
881 | the window coordinates | |
882 | ||
3c9b6116 | 883 | @r{@var{x}_@var{w}=⌊@var{x}_@var{r}-@var{x}_@var{o},⌋} |
8925f36f | 884 | |
3c9b6116 | 885 | @r{@var{y}_@var{w}=⌊@var{y}_@var{r}-@var{y}_@var{o},⌋} |
8925f36f | 886 | |
3c9b6116 | 887 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the raster position and |
f37e7e3d | 888 | @r{(@var{x}_@var{o},@var{y}_@var{o})} is the bitmap origin. Fragments |
3c9b6116 | 889 | are then generated for each pixel corresponding to a 1 (one) in the |
f37e7e3d | 890 | bitmap image. These fragments are generated using the current raster |
3c9b6116 | 891 | @var{z} coordinate, color or color index, and current raster texture |
f37e7e3d DH |
892 | coordinates. They are then treated just as if they had been generated by |
893 | a point, line, or polygon, including texture mapping, fogging, and all | |
894 | per-fragment operations such as alpha and depth testing. | |
8925f36f AW |
895 | |
896 | After the bitmap has been drawn, the @var{x} and @var{y} coordinates of | |
897 | the current raster position are offset by @var{xmove} and @var{ymove}. | |
898 | No change is made to the @var{z} coordinate of the current raster | |
899 | position, or to the current raster color, texture coordinates, or index. | |
900 | ||
8925f36f AW |
901 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is |
902 | negative. | |
903 | ||
904 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
905 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
906 | object's data store is currently mapped. | |
907 | ||
908 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
909 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
910 | would be unpacked from the buffer object such that the memory reads | |
911 | required would exceed the data store size. | |
912 | ||
913 | @code{GL_INVALID_OPERATION} is generated if @code{glBitmap} is executed | |
914 | between the execution of @code{glBegin} and the corresponding execution | |
915 | of @code{glEnd}. | |
916 | ||
bb894c9d | 917 | @end deftypefun |
8925f36f | 918 | |
bb894c9d | 919 | @deftypefun void glBlendColor red green blue alpha |
3c9b6116 AW |
920 | Set the blend color. |
921 | ||
8925f36f AW |
922 | @table @asis |
923 | @item @var{red} | |
924 | @itemx @var{green} | |
925 | @itemx @var{blue} | |
926 | @itemx @var{alpha} | |
927 | specify the components of @code{GL_BLEND_COLOR} | |
928 | ||
929 | @end table | |
930 | ||
8925f36f | 931 | The @code{GL_BLEND_COLOR} may be used to calculate the source and |
f37e7e3d DH |
932 | destination blending factors. The color components are clamped to the |
933 | range @r{[0,1]} before being stored. See @code{glBlendFunc} for a | |
934 | complete description of the blending operations. Initially the | |
8925f36f AW |
935 | @code{GL_BLEND_COLOR} is set to (0, 0, 0, 0). |
936 | ||
8925f36f AW |
937 | @code{GL_INVALID_OPERATION} is generated if @code{glBlendColor} is |
938 | executed between the execution of @code{glBegin} and the corresponding | |
939 | execution of @code{glEnd}. | |
940 | ||
941 | ||
942 | ||
bb894c9d | 943 | @end deftypefun |
8925f36f | 944 | |
bb894c9d | 945 | @deftypefun void glBlendEquationSeparate modeRGB modeAlpha |
3c9b6116 AW |
946 | Set the RGB blend equation and the alpha blend equation separately. |
947 | ||
8925f36f AW |
948 | @table @asis |
949 | @item @var{modeRGB} | |
950 | specifies the RGB blend equation, how the red, green, and blue | |
f37e7e3d DH |
951 | components of the source and destination colors are combined. It must be |
952 | @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, | |
8925f36f AW |
953 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}. |
954 | ||
955 | @item @var{modeAlpha} | |
956 | specifies the alpha blend equation, how the alpha component of the | |
f37e7e3d | 957 | source and destination colors are combined. It must be |
8925f36f AW |
958 | @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, |
959 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}. | |
960 | ||
961 | @end table | |
962 | ||
8925f36f AW |
963 | The blend equations determines how a new pixel (the ''source'' color) is |
964 | combined with a pixel already in the framebuffer (the ''destination'' | |
f37e7e3d | 965 | color). This function specifies one blend equation for the RGB-color |
8925f36f AW |
966 | components and one blend equation for the alpha component. |
967 | ||
968 | The blend equations use the source and destination blend factors | |
969 | specified by either @code{glBlendFunc} or @code{glBlendFuncSeparate}. | |
970 | See @code{glBlendFunc} or @code{glBlendFuncSeparate} for a description | |
971 | of the various blend factors. | |
972 | ||
973 | In the equations that follow, source and destination color components | |
974 | are referred to as | |
3c9b6116 AW |
975 | @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and |
976 | @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}, | |
f37e7e3d DH |
977 | respectively. The result color is referred to as |
978 | @r{(@var{R}_@var{r},@var{G}_@var{r}@var{B}_@var{r}@var{A}_@var{r})}. The | |
3c9b6116 AW |
979 | source and destination blend factors are denoted |
980 | @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and | |
981 | @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}, | |
f37e7e3d DH |
982 | respectively. For these equations all color components are understood to |
983 | have values in the range @r{[0,1]}. | |
8925f36f AW |
984 | |
985 | @table @asis | |
986 | @item @strong{Mode} | |
987 | @strong{RGB Components}, @strong{Alpha Component} | |
988 | ||
989 | @item @code{GL_FUNC_ADD} | |
3c9b6116 AW |
990 | @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B}}, |
991 | @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A}} | |
8925f36f AW |
992 | |
993 | @item @code{GL_FUNC_SUBTRACT} | |
3c9b6116 AW |
994 | @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}-@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}-@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}-@var{B}_@var{d}@var{d}_@var{B}}, |
995 | @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}-@var{A}_@var{d}@var{d}_@var{A}} | |
8925f36f AW |
996 | |
997 | @item @code{GL_FUNC_REVERSE_SUBTRACT} | |
3c9b6116 AW |
998 | @r{@var{Rr}=@var{R}_@var{d}@var{d}_@var{R}-@var{R}_@var{s}@var{s}_@var{R}}@r{@var{Gr}=@var{G}_@var{d}@var{d}_@var{G}-@var{G}_@var{s}@var{s}_@var{G}}@r{@var{Br}=@var{B}_@var{d}@var{d}_@var{B}-@var{B}_@var{s}@var{s}_@var{B}}, |
999 | @r{@var{Ar}=@var{A}_@var{d}@var{d}_@var{A}-@var{A}_@var{s}@var{s}_@var{A}} | |
8925f36f AW |
1000 | |
1001 | @item @code{GL_MIN} | |
3c9b6116 AW |
1002 | @r{@var{Rr}=@var{min}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{min}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{min}(@var{B}_@var{s},@var{B}_@var{d})}, |
1003 | @r{@var{Ar}=@var{min}(@var{A}_@var{s},@var{A}_@var{d})} | |
8925f36f AW |
1004 | |
1005 | @item @code{GL_MAX} | |
3c9b6116 AW |
1006 | @r{@var{Rr}=@var{max}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{max}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{max}(@var{B}_@var{s},@var{B}_@var{d})}, |
1007 | @r{@var{Ar}=@var{max}(@var{A}_@var{s},@var{A}_@var{d})} | |
8925f36f AW |
1008 | |
1009 | @end table | |
1010 | ||
3c9b6116 | 1011 | The results of these equations are clamped to the range @r{[0,1]}. |
8925f36f AW |
1012 | |
1013 | The @code{GL_MIN} and @code{GL_MAX} equations are useful for | |
1014 | applications that analyze image data (image thresholding against a | |
f37e7e3d | 1015 | constant color, for example). The @code{GL_FUNC_ADD} equation is useful |
8925f36f AW |
1016 | for antialiasing and transparency, among other things. |
1017 | ||
1018 | Initially, both the RGB blend equation and the alpha blend equation are | |
1019 | set to @code{GL_FUNC_ADD}. | |
1020 | ||
1021 | ||
1022 | ||
8925f36f AW |
1023 | @code{GL_INVALID_ENUM} is generated if either @var{modeRGB} or |
1024 | @var{modeAlpha} is not one of @code{GL_FUNC_ADD}, | |
1025 | @code{GL_FUNC_SUBTRACT}, @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MAX}, | |
1026 | or @code{GL_MIN}. | |
1027 | ||
1028 | @code{GL_INVALID_OPERATION} is generated if | |
1029 | @code{glBlendEquationSeparate} is executed between the execution of | |
1030 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
1031 | ||
bb894c9d | 1032 | @end deftypefun |
8925f36f | 1033 | |
bb894c9d | 1034 | @deftypefun void glBlendEquation mode |
3c9b6116 AW |
1035 | Specify the equation used for both the RGB blend equation and the Alpha |
1036 | blend equation. | |
1037 | ||
8925f36f AW |
1038 | @table @asis |
1039 | @item @var{mode} | |
f37e7e3d | 1040 | specifies how source and destination colors are combined. It must be |
8925f36f AW |
1041 | @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, |
1042 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}. | |
1043 | ||
1044 | @end table | |
1045 | ||
8925f36f AW |
1046 | The blend equations determine how a new pixel (the ''source'' color) is |
1047 | combined with a pixel already in the framebuffer (the ''destination'' | |
f37e7e3d | 1048 | color). This function sets both the RGB blend equation and the alpha |
8925f36f AW |
1049 | blend equation to a single equation. |
1050 | ||
1051 | These equations use the source and destination blend factors specified | |
f37e7e3d | 1052 | by either @code{glBlendFunc} or @code{glBlendFuncSeparate}. See |
8925f36f AW |
1053 | @code{glBlendFunc} or @code{glBlendFuncSeparate} for a description of |
1054 | the various blend factors. | |
1055 | ||
1056 | In the equations that follow, source and destination color components | |
1057 | are referred to as | |
3c9b6116 AW |
1058 | @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and |
1059 | @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}, | |
f37e7e3d DH |
1060 | respectively. The result color is referred to as |
1061 | @r{(@var{R}_@var{r},@var{G}_@var{r}@var{B}_@var{r}@var{A}_@var{r})}. The | |
3c9b6116 AW |
1062 | source and destination blend factors are denoted |
1063 | @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and | |
1064 | @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}, | |
f37e7e3d DH |
1065 | respectively. For these equations all color components are understood to |
1066 | have values in the range @r{[0,1]}. | |
8925f36f AW |
1067 | |
1068 | @table @asis | |
1069 | @item @strong{Mode} | |
1070 | @strong{RGB Components}, @strong{Alpha Component} | |
1071 | ||
1072 | @item @code{GL_FUNC_ADD} | |
3c9b6116 AW |
1073 | @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B}}, |
1074 | @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A}} | |
8925f36f AW |
1075 | |
1076 | @item @code{GL_FUNC_SUBTRACT} | |
3c9b6116 AW |
1077 | @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}-@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}-@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}-@var{B}_@var{d}@var{d}_@var{B}}, |
1078 | @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}-@var{A}_@var{d}@var{d}_@var{A}} | |
8925f36f AW |
1079 | |
1080 | @item @code{GL_FUNC_REVERSE_SUBTRACT} | |
3c9b6116 AW |
1081 | @r{@var{Rr}=@var{R}_@var{d}@var{d}_@var{R}-@var{R}_@var{s}@var{s}_@var{R}}@r{@var{Gr}=@var{G}_@var{d}@var{d}_@var{G}-@var{G}_@var{s}@var{s}_@var{G}}@r{@var{Br}=@var{B}_@var{d}@var{d}_@var{B}-@var{B}_@var{s}@var{s}_@var{B}}, |
1082 | @r{@var{Ar}=@var{A}_@var{d}@var{d}_@var{A}-@var{A}_@var{s}@var{s}_@var{A}} | |
8925f36f AW |
1083 | |
1084 | @item @code{GL_MIN} | |
3c9b6116 AW |
1085 | @r{@var{Rr}=@var{min}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{min}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{min}(@var{B}_@var{s},@var{B}_@var{d})}, |
1086 | @r{@var{Ar}=@var{min}(@var{A}_@var{s},@var{A}_@var{d})} | |
8925f36f AW |
1087 | |
1088 | @item @code{GL_MAX} | |
3c9b6116 AW |
1089 | @r{@var{Rr}=@var{max}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{max}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{max}(@var{B}_@var{s},@var{B}_@var{d})}, |
1090 | @r{@var{Ar}=@var{max}(@var{A}_@var{s},@var{A}_@var{d})} | |
8925f36f AW |
1091 | |
1092 | @end table | |
1093 | ||
3c9b6116 | 1094 | The results of these equations are clamped to the range @r{[0,1]}. |
8925f36f AW |
1095 | |
1096 | The @code{GL_MIN} and @code{GL_MAX} equations are useful for | |
1097 | applications that analyze image data (image thresholding against a | |
f37e7e3d | 1098 | constant color, for example). The @code{GL_FUNC_ADD} equation is useful |
8925f36f AW |
1099 | for antialiasing and transparency, among other things. |
1100 | ||
1101 | Initially, both the RGB blend equation and the alpha blend equation are | |
1102 | set to @code{GL_FUNC_ADD}. | |
1103 | ||
1104 | ||
1105 | ||
8925f36f AW |
1106 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of |
1107 | @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, | |
1108 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MAX}, or @code{GL_MIN}. | |
1109 | ||
1110 | @code{GL_INVALID_OPERATION} is generated if @code{glBlendEquation} is | |
1111 | executed between the execution of @code{glBegin} and the corresponding | |
1112 | execution of @code{glEnd}. | |
1113 | ||
bb894c9d | 1114 | @end deftypefun |
8925f36f | 1115 | |
bb894c9d | 1116 | @deftypefun void glBlendFuncSeparate srcRGB dstRGB srcAlpha dstAlpha |
3c9b6116 AW |
1117 | Specify pixel arithmetic for RGB and alpha components separately. |
1118 | ||
8925f36f AW |
1119 | @table @asis |
1120 | @item @var{srcRGB} | |
1121 | Specifies how the red, green, and blue blending factors are computed. | |
1122 | The following symbolic constants are accepted: @code{GL_ZERO}, | |
1123 | @code{GL_ONE}, @code{GL_SRC_COLOR}, @code{GL_ONE_MINUS_SRC_COLOR}, | |
1124 | @code{GL_DST_COLOR}, @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA}, | |
1125 | @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA}, | |
1126 | @code{GL_ONE_MINUS_DST_ALPHA}, @code{GL_CONSTANT_COLOR}, | |
1127 | @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, | |
1128 | @code{GL_ONE_MINUS_CONSTANT_ALPHA}, and @code{GL_SRC_ALPHA_SATURATE}. | |
1129 | The initial value is @code{GL_ONE}. | |
1130 | ||
1131 | @item @var{dstRGB} | |
1132 | Specifies how the red, green, and blue destination blending factors are | |
f37e7e3d DH |
1133 | computed. The following symbolic constants are accepted: @code{GL_ZERO}, |
1134 | @code{GL_ONE}, @code{GL_SRC_COLOR}, @code{GL_ONE_MINUS_SRC_COLOR}, | |
1135 | @code{GL_DST_COLOR}, @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA}, | |
8925f36f | 1136 | @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA}, |
f37e7e3d | 1137 | @code{GL_ONE_MINUS_DST_ALPHA}. @code{GL_CONSTANT_COLOR}, |
8925f36f | 1138 | @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, and |
f37e7e3d | 1139 | @code{GL_ONE_MINUS_CONSTANT_ALPHA}. The initial value is @code{GL_ZERO}. |
8925f36f AW |
1140 | |
1141 | @item @var{srcAlpha} | |
f37e7e3d DH |
1142 | Specified how the alpha source blending factor is computed. The same |
1143 | symbolic constants are accepted as for @var{srcRGB}. The initial value | |
8925f36f AW |
1144 | is @code{GL_ONE}. |
1145 | ||
1146 | @item @var{dstAlpha} | |
f37e7e3d DH |
1147 | Specified how the alpha destination blending factor is computed. The |
1148 | same symbolic constants are accepted as for @var{dstRGB}. The initial | |
8925f36f AW |
1149 | value is @code{GL_ZERO}. |
1150 | ||
1151 | @end table | |
1152 | ||
8925f36f AW |
1153 | In RGBA mode, pixels can be drawn using a function that blends the |
1154 | incoming (source) RGBA values with the RGBA values that are already in | |
f37e7e3d DH |
1155 | the frame buffer (the destination values). Blending is initially |
1156 | disabled. Use @code{glEnable} and @code{glDisable} with argument | |
8925f36f AW |
1157 | @code{GL_BLEND} to enable and disable blending. |
1158 | ||
1159 | @code{glBlendFuncSeparate} defines the operation of blending when it is | |
f37e7e3d DH |
1160 | enabled. @var{srcRGB} specifies which method is used to scale the source |
1161 | RGB-color components. @var{dstRGB} specifies which method is used to | |
1162 | scale the destination RGB-color components. Likewise, @var{srcAlpha} | |
1163 | specifies which method is used to scale the source alpha color | |
1164 | component, and @var{dstAlpha} specifies which method is used to scale | |
1165 | the destination alpha component. The possible methods are described in | |
1166 | the following table. Each method defines four scale factors, one each | |
1167 | for red, green, blue, and alpha. | |
8925f36f AW |
1168 | |
1169 | In the table and in subsequent equations, source and destination color | |
1170 | components are referred to as | |
3c9b6116 | 1171 | @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and |
f37e7e3d | 1172 | @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}. The |
3c9b6116 AW |
1173 | color specified by @code{glBlendColor} is referred to as |
1174 | @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}. | |
8925f36f | 1175 | They are understood to have integer values between 0 and |
3c9b6116 | 1176 | @r{(@var{k}_@var{R},@var{k}_@var{G}@var{k}_@var{B}@var{k}_@var{A})}, |
8925f36f AW |
1177 | where |
1178 | ||
3c9b6116 | 1179 | @r{@var{k}_@var{c}=2^@var{m}_@var{c},-1} |
8925f36f | 1180 | |
3c9b6116 | 1181 | and @r{(@var{m}_@var{R},@var{m}_@var{G}@var{m}_@var{B}@var{m}_@var{A})} |
8925f36f AW |
1182 | is the number of red, green, blue, and alpha bitplanes. |
1183 | ||
1184 | Source and destination scale factors are referred to as | |
3c9b6116 | 1185 | @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and |
f37e7e3d | 1186 | @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}. All |
3c9b6116 | 1187 | scale factors have range @r{[0,1]}. |
8925f36f AW |
1188 | |
1189 | ||
1190 | ||
1191 | @table @asis | |
1192 | @item @strong{Parameter} | |
1193 | @strong{RGB Factor}, @strong{Alpha Factor} | |
1194 | ||
1195 | @item @code{GL_ZERO} | |
3c9b6116 | 1196 | @r{(0,00)}, @r{0} |
8925f36f AW |
1197 | |
1198 | @item @code{GL_ONE} | |
3c9b6116 | 1199 | @r{(1,11)}, @r{1} |
8925f36f AW |
1200 | |
1201 | @item @code{GL_SRC_COLOR} | |
3c9b6116 AW |
1202 | @r{(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B})}, |
1203 | @r{@var{A}_@var{s}/@var{k}_@var{A}} | |
8925f36f AW |
1204 | |
1205 | @item @code{GL_ONE_MINUS_SRC_COLOR} | |
3c9b6116 AW |
1206 | @r{(1,111)-(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B})}, |
1207 | @r{1-@var{A}_@var{s}/@var{k}_@var{A}} | |
8925f36f AW |
1208 | |
1209 | @item @code{GL_DST_COLOR} | |
3c9b6116 AW |
1210 | @r{(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B})}, |
1211 | @r{@var{A}_@var{d}/@var{k}_@var{A}} | |
8925f36f AW |
1212 | |
1213 | @item @code{GL_ONE_MINUS_DST_COLOR} | |
3c9b6116 AW |
1214 | @r{(1,11)-(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B})}, |
1215 | @r{1-@var{A}_@var{d}/@var{k}_@var{A}} | |
8925f36f AW |
1216 | |
1217 | @item @code{GL_SRC_ALPHA} | |
3c9b6116 AW |
1218 | @r{(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})}, |
1219 | @r{@var{A}_@var{s}/@var{k}_@var{A}} | |
8925f36f AW |
1220 | |
1221 | @item @code{GL_ONE_MINUS_SRC_ALPHA} | |
3c9b6116 AW |
1222 | @r{(1,11)-(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})}, |
1223 | @r{1-@var{A}_@var{s}/@var{k}_@var{A}} | |
8925f36f AW |
1224 | |
1225 | @item @code{GL_DST_ALPHA} | |
3c9b6116 AW |
1226 | @r{(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})}, |
1227 | @r{@var{A}_@var{d}/@var{k}_@var{A}} | |
8925f36f AW |
1228 | |
1229 | @item @code{GL_ONE_MINUS_DST_ALPHA} | |
3c9b6116 AW |
1230 | @r{(1,11)-(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})}, |
1231 | @r{1-@var{A}_@var{d}/@var{k}_@var{A}} | |
8925f36f AW |
1232 | |
1233 | @item @code{GL_CONSTANT_COLOR} | |
3c9b6116 AW |
1234 | @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c})}, |
1235 | @r{@var{A}_@var{c}} | |
8925f36f AW |
1236 | |
1237 | @item @code{GL_ONE_MINUS_CONSTANT_COLOR} | |
3c9b6116 AW |
1238 | @r{(1,11)-(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c})}, |
1239 | @r{1-@var{A}_@var{c}} | |
8925f36f AW |
1240 | |
1241 | @item @code{GL_CONSTANT_ALPHA} | |
3c9b6116 AW |
1242 | @r{(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c})}, |
1243 | @r{@var{A}_@var{c}} | |
8925f36f AW |
1244 | |
1245 | @item @code{GL_ONE_MINUS_CONSTANT_ALPHA} | |
3c9b6116 AW |
1246 | @r{(1,11)-(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c})}, |
1247 | @r{1-@var{A}_@var{c}} | |
8925f36f AW |
1248 | |
1249 | @item @code{GL_SRC_ALPHA_SATURATE} | |
3c9b6116 | 1250 | @r{(@var{i},@var{i}@var{i})}, @r{1} |
8925f36f AW |
1251 | |
1252 | @end table | |
1253 | ||
1254 | In the table, | |
1255 | ||
3c9b6116 | 1256 | @r{@var{i}=@var{min}(@var{A}_@var{s},1-@var{A}_@var{d},)} |
8925f36f AW |
1257 | |
1258 | To determine the blended RGBA values of a pixel when drawing in RGBA | |
1259 | mode, the system uses the following equations: | |
1260 | ||
3c9b6116 | 1261 | @r{@var{R}_@var{d}=@var{min}(@var{k}_@var{R},@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R})}@r{@var{G}_@var{d}=@var{min}(@var{k}_@var{G},@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G})}@r{@var{B}_@var{d}=@var{min}(@var{k}_@var{B},@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B})}@r{@var{A}_@var{d}=@var{min}(@var{k}_@var{A},@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A})} |
8925f36f AW |
1262 | |
1263 | Despite the apparent precision of the above equations, blending | |
1264 | arithmetic is not exactly specified, because blending operates with | |
f37e7e3d | 1265 | imprecise integer color values. However, a blend factor that should be |
8925f36f | 1266 | equal to 1 is guaranteed not to modify its multiplicand, and a blend |
f37e7e3d | 1267 | factor equal to 0 reduces its multiplicand to 0. For example, when |
8925f36f | 1268 | @var{srcRGB} is @code{GL_SRC_ALPHA}, @var{dstRGB} is |
3c9b6116 AW |
1269 | @code{GL_ONE_MINUS_SRC_ALPHA}, and @r{@var{A}_@var{s}} is equal to |
1270 | @r{@var{k}_@var{A}}, the equations reduce to simple replacement: | |
8925f36f | 1271 | |
3c9b6116 | 1272 | @r{@var{R}_@var{d}=@var{R}_@var{s}}@r{@var{G}_@var{d}=@var{G}_@var{s}}@r{@var{B}_@var{d}=@var{B}_@var{s}}@r{@var{A}_@var{d}=@var{A}_@var{s}} |
8925f36f AW |
1273 | |
1274 | ||
1275 | ||
8925f36f AW |
1276 | @code{GL_INVALID_ENUM} is generated if either @var{srcRGB} or |
1277 | @var{dstRGB} is not an accepted value. | |
1278 | ||
1279 | @code{GL_INVALID_OPERATION} is generated if @code{glBlendFuncSeparate} | |
1280 | is executed between the execution of @code{glBegin} and the | |
1281 | corresponding execution of @code{glEnd}. | |
1282 | ||
bb894c9d | 1283 | @end deftypefun |
8925f36f | 1284 | |
bb894c9d | 1285 | @deftypefun void glBlendFunc sfactor dfactor |
3c9b6116 AW |
1286 | Specify pixel arithmetic. |
1287 | ||
8925f36f AW |
1288 | @table @asis |
1289 | @item @var{sfactor} | |
1290 | Specifies how the red, green, blue, and alpha source blending factors | |
f37e7e3d | 1291 | are computed. The following symbolic constants are accepted: |
8925f36f AW |
1292 | @code{GL_ZERO}, @code{GL_ONE}, @code{GL_SRC_COLOR}, |
1293 | @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_DST_COLOR}, | |
1294 | @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA}, | |
1295 | @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA}, | |
1296 | @code{GL_ONE_MINUS_DST_ALPHA}, @code{GL_CONSTANT_COLOR}, | |
1297 | @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, | |
1298 | @code{GL_ONE_MINUS_CONSTANT_ALPHA}, and @code{GL_SRC_ALPHA_SATURATE}. | |
1299 | The initial value is @code{GL_ONE}. | |
1300 | ||
1301 | @item @var{dfactor} | |
1302 | Specifies how the red, green, blue, and alpha destination blending | |
f37e7e3d | 1303 | factors are computed. The following symbolic constants are accepted: |
8925f36f AW |
1304 | @code{GL_ZERO}, @code{GL_ONE}, @code{GL_SRC_COLOR}, |
1305 | @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_DST_COLOR}, | |
1306 | @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA}, | |
1307 | @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA}, | |
f37e7e3d | 1308 | @code{GL_ONE_MINUS_DST_ALPHA}. @code{GL_CONSTANT_COLOR}, |
8925f36f | 1309 | @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, and |
f37e7e3d | 1310 | @code{GL_ONE_MINUS_CONSTANT_ALPHA}. The initial value is @code{GL_ZERO}. |
8925f36f AW |
1311 | |
1312 | @end table | |
1313 | ||
8925f36f AW |
1314 | In RGBA mode, pixels can be drawn using a function that blends the |
1315 | incoming (source) RGBA values with the RGBA values that are already in | |
f37e7e3d DH |
1316 | the frame buffer (the destination values). Blending is initially |
1317 | disabled. Use @code{glEnable} and @code{glDisable} with argument | |
8925f36f AW |
1318 | @code{GL_BLEND} to enable and disable blending. |
1319 | ||
1320 | @code{glBlendFunc} defines the operation of blending when it is enabled. | |
1321 | @var{sfactor} specifies which method is used to scale the source color | |
f37e7e3d DH |
1322 | components. @var{dfactor} specifies which method is used to scale the |
1323 | destination color components. The possible methods are described in the | |
1324 | following table. Each method defines four scale factors, one each for | |
1325 | red, green, blue, and alpha. In the table and in subsequent equations, | |
8925f36f | 1326 | source and destination color components are referred to as |
3c9b6116 | 1327 | @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and |
f37e7e3d | 1328 | @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}. The |
3c9b6116 AW |
1329 | color specified by @code{glBlendColor} is referred to as |
1330 | @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}. | |
8925f36f | 1331 | They are understood to have integer values between 0 and |
3c9b6116 | 1332 | @r{(@var{k}_@var{R},@var{k}_@var{G}@var{k}_@var{B}@var{k}_@var{A})}, |
8925f36f AW |
1333 | where |
1334 | ||
3c9b6116 | 1335 | @r{@var{k}_@var{c}=2^@var{m}_@var{c},-1} |
8925f36f | 1336 | |
3c9b6116 | 1337 | and @r{(@var{m}_@var{R},@var{m}_@var{G}@var{m}_@var{B}@var{m}_@var{A})} |
8925f36f AW |
1338 | is the number of red, green, blue, and alpha bitplanes. |
1339 | ||
1340 | Source and destination scale factors are referred to as | |
3c9b6116 | 1341 | @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and |
f37e7e3d | 1342 | @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}. The |
3c9b6116 AW |
1343 | scale factors described in the table, denoted |
1344 | @r{(@var{f}_@var{R},@var{f}_@var{G}@var{f}_@var{B}@var{f}_@var{A})}, | |
f37e7e3d | 1345 | represent either source or destination factors. All scale factors have |
3c9b6116 | 1346 | range @r{[0,1]}. |
8925f36f AW |
1347 | |
1348 | ||
1349 | ||
1350 | @table @asis | |
1351 | @item @strong{Parameter} | |
3c9b6116 | 1352 | @strong{@r{(@var{f}_@var{R},@var{f}_@var{G}@var{f}_@var{B}@var{f}_@var{A})}} |
8925f36f AW |
1353 | |
1354 | @item @code{GL_ZERO} | |
3c9b6116 | 1355 | @r{(0,000)} |
8925f36f AW |
1356 | |
1357 | @item @code{GL_ONE} | |
3c9b6116 | 1358 | @r{(1,111)} |
8925f36f AW |
1359 | |
1360 | @item @code{GL_SRC_COLOR} | |
3c9b6116 | 1361 | @r{(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B}@var{A}_@var{s}/@var{k}_@var{A})} |
8925f36f AW |
1362 | |
1363 | @item @code{GL_ONE_MINUS_SRC_COLOR} | |
3c9b6116 | 1364 | @r{(1,111)-(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B}@var{A}_@var{s}/@var{k}_@var{A})} |
8925f36f AW |
1365 | |
1366 | @item @code{GL_DST_COLOR} | |
3c9b6116 | 1367 | @r{(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B}@var{A}_@var{d}/@var{k}_@var{A})} |
8925f36f AW |
1368 | |
1369 | @item @code{GL_ONE_MINUS_DST_COLOR} | |
3c9b6116 | 1370 | @r{(1,111)-(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B}@var{A}_@var{d}/@var{k}_@var{A})} |
8925f36f AW |
1371 | |
1372 | @item @code{GL_SRC_ALPHA} | |
3c9b6116 | 1373 | @r{(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})} |
8925f36f AW |
1374 | |
1375 | @item @code{GL_ONE_MINUS_SRC_ALPHA} | |
3c9b6116 | 1376 | @r{(1,111)-(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})} |
8925f36f AW |
1377 | |
1378 | @item @code{GL_DST_ALPHA} | |
3c9b6116 | 1379 | @r{(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})} |
8925f36f AW |
1380 | |
1381 | @item @code{GL_ONE_MINUS_DST_ALPHA} | |
3c9b6116 | 1382 | @r{(1,111)-(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})} |
8925f36f AW |
1383 | |
1384 | @item @code{GL_CONSTANT_COLOR} | |
3c9b6116 | 1385 | @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})} |
8925f36f AW |
1386 | |
1387 | @item @code{GL_ONE_MINUS_CONSTANT_COLOR} | |
3c9b6116 | 1388 | @r{(1,111)-(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})} |
8925f36f AW |
1389 | |
1390 | @item @code{GL_CONSTANT_ALPHA} | |
3c9b6116 | 1391 | @r{(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c}@var{A}_@var{c})} |
8925f36f AW |
1392 | |
1393 | @item @code{GL_ONE_MINUS_CONSTANT_ALPHA} | |
3c9b6116 | 1394 | @r{(1,111)-(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c}@var{A}_@var{c})} |
8925f36f AW |
1395 | |
1396 | @item @code{GL_SRC_ALPHA_SATURATE} | |
3c9b6116 | 1397 | @r{(@var{i},@var{i}@var{i}1)} |
8925f36f AW |
1398 | |
1399 | @end table | |
1400 | ||
1401 | In the table, | |
1402 | ||
3c9b6116 | 1403 | @r{@var{i}=@var{min}(@var{A}_@var{s},@var{k}_@var{A}-@var{A}_@var{d})/@var{k}_@var{A}} |
8925f36f AW |
1404 | |
1405 | To determine the blended RGBA values of a pixel when drawing in RGBA | |
1406 | mode, the system uses the following equations: | |
1407 | ||
3c9b6116 | 1408 | @r{@var{R}_@var{d}=@var{min}(@var{k}_@var{R},@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R})}@r{@var{G}_@var{d}=@var{min}(@var{k}_@var{G},@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G})}@r{@var{B}_@var{d}=@var{min}(@var{k}_@var{B},@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B})}@r{@var{A}_@var{d}=@var{min}(@var{k}_@var{A},@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A})} |
8925f36f AW |
1409 | |
1410 | Despite the apparent precision of the above equations, blending | |
1411 | arithmetic is not exactly specified, because blending operates with | |
f37e7e3d | 1412 | imprecise integer color values. However, a blend factor that should be |
8925f36f | 1413 | equal to 1 is guaranteed not to modify its multiplicand, and a blend |
f37e7e3d | 1414 | factor equal to 0 reduces its multiplicand to 0. For example, when |
8925f36f | 1415 | @var{sfactor} is @code{GL_SRC_ALPHA}, @var{dfactor} is |
3c9b6116 AW |
1416 | @code{GL_ONE_MINUS_SRC_ALPHA}, and @r{@var{A}_@var{s}} is equal to |
1417 | @r{@var{k}_@var{A}}, the equations reduce to simple replacement: | |
8925f36f | 1418 | |
3c9b6116 | 1419 | @r{@var{R}_@var{d}=@var{R}_@var{s}}@r{@var{G}_@var{d}=@var{G}_@var{s}}@r{@var{B}_@var{d}=@var{B}_@var{s}}@r{@var{A}_@var{d}=@var{A}_@var{s}} |
8925f36f AW |
1420 | |
1421 | ||
1422 | ||
8925f36f AW |
1423 | @code{GL_INVALID_ENUM} is generated if either @var{sfactor} or |
1424 | @var{dfactor} is not an accepted value. | |
1425 | ||
1426 | @code{GL_INVALID_OPERATION} is generated if @code{glBlendFunc} is | |
1427 | executed between the execution of @code{glBegin} and the corresponding | |
1428 | execution of @code{glEnd}. | |
1429 | ||
bb894c9d | 1430 | @end deftypefun |
8925f36f | 1431 | |
bb894c9d | 1432 | @deftypefun void glBufferData target size data usage |
3c9b6116 AW |
1433 | Creates and initializes a buffer object's data store. |
1434 | ||
8925f36f AW |
1435 | @table @asis |
1436 | @item @var{target} | |
f37e7e3d | 1437 | Specifies the target buffer object. The symbolic constant must be |
8925f36f AW |
1438 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
1439 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
1440 | ||
1441 | @item @var{size} | |
1442 | Specifies the size in bytes of the buffer object's new data store. | |
1443 | ||
1444 | @item @var{data} | |
1445 | Specifies a pointer to data that will be copied into the data store for | |
1446 | initialization, or @code{NULL} if no data is to be copied. | |
1447 | ||
1448 | @item @var{usage} | |
f37e7e3d | 1449 | Specifies the expected usage pattern of the data store. The symbolic |
8925f36f AW |
1450 | constant must be @code{GL_STREAM_DRAW}, @code{GL_STREAM_READ}, |
1451 | @code{GL_STREAM_COPY}, @code{GL_STATIC_DRAW}, @code{GL_STATIC_READ}, | |
1452 | @code{GL_STATIC_COPY}, @code{GL_DYNAMIC_DRAW}, @code{GL_DYNAMIC_READ}, | |
1453 | or @code{GL_DYNAMIC_COPY}. | |
1454 | ||
1455 | @end table | |
1456 | ||
8925f36f | 1457 | @code{glBufferData} creates a new data store for the buffer object |
f37e7e3d DH |
1458 | currently bound to @var{target}. Any pre-existing data store is deleted. |
1459 | The new data store is created with the specified @var{size} in bytes and | |
1460 | @var{usage}. If @var{data} is not @code{NULL}, the data store is | |
1461 | initialized with data from this pointer. In its initial state, the new | |
1462 | data store is not mapped, it has a @code{NULL} mapped pointer, and its | |
1463 | mapped access is @code{GL_READ_WRITE}. | |
8925f36f AW |
1464 | |
1465 | @var{usage} is a hint to the GL implementation as to how a buffer | |
f37e7e3d DH |
1466 | object's data store will be accessed. This enables the GL implementation |
1467 | to make more intelligent decisions that may significantly impact buffer | |
1468 | object performance. It does not, however, constrain the actual usage of | |
1469 | the data store. @var{usage} can be broken down into two parts: first, | |
1470 | the frequency of access (modification and usage), and second, the nature | |
1471 | of that access. The frequency of access may be one of these: | |
8925f36f AW |
1472 | |
1473 | @table @asis | |
1474 | @item STREAM | |
1475 | The data store contents will be modified once and used at most a few | |
1476 | times. | |
1477 | ||
1478 | @item STATIC | |
1479 | The data store contents will be modified once and used many times. | |
1480 | ||
1481 | @item DYNAMIC | |
1482 | The data store contents will be modified repeatedly and used many times. | |
1483 | ||
1484 | @end table | |
1485 | ||
1486 | The nature of access may be one of these: | |
1487 | ||
1488 | @table @asis | |
1489 | @item DRAW | |
1490 | The data store contents are modified by the application, and used as the | |
1491 | source for GL drawing and image specification commands. | |
1492 | ||
1493 | @item READ | |
1494 | The data store contents are modified by reading data from the GL, and | |
1495 | used to return that data when queried by the application. | |
1496 | ||
1497 | @item COPY | |
1498 | The data store contents are modified by reading data from the GL, and | |
1499 | used as the source for GL drawing and image specification commands. | |
1500 | ||
1501 | @end table | |
1502 | ||
8925f36f AW |
1503 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
1504 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
1505 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
1506 | ||
1507 | @code{GL_INVALID_ENUM} is generated if @var{usage} is not | |
1508 | @code{GL_STREAM_DRAW}, @code{GL_STREAM_READ}, @code{GL_STREAM_COPY}, | |
1509 | @code{GL_STATIC_DRAW}, @code{GL_STATIC_READ}, @code{GL_STATIC_COPY}, | |
1510 | @code{GL_DYNAMIC_DRAW}, @code{GL_DYNAMIC_READ}, or | |
1511 | @code{GL_DYNAMIC_COPY}. | |
1512 | ||
1513 | @code{GL_INVALID_VALUE} is generated if @var{size} is negative. | |
1514 | ||
1515 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
1516 | name 0 is bound to @var{target}. | |
1517 | ||
1518 | @code{GL_OUT_OF_MEMORY} is generated if the GL is unable to create a | |
1519 | data store with the specified @var{size}. | |
1520 | ||
1521 | @code{GL_INVALID_OPERATION} is generated if @code{glBufferData} is | |
1522 | executed between the execution of @code{glBegin} and the corresponding | |
1523 | execution of @code{glEnd}. | |
1524 | ||
bb894c9d | 1525 | @end deftypefun |
8925f36f | 1526 | |
bb894c9d | 1527 | @deftypefun void glBufferSubData target offset size data |
3c9b6116 AW |
1528 | Updates a subset of a buffer object's data store. |
1529 | ||
8925f36f AW |
1530 | @table @asis |
1531 | @item @var{target} | |
f37e7e3d | 1532 | Specifies the target buffer object. The symbolic constant must be |
8925f36f AW |
1533 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
1534 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
1535 | ||
1536 | @item @var{offset} | |
1537 | Specifies the offset into the buffer object's data store where data | |
1538 | replacement will begin, measured in bytes. | |
1539 | ||
1540 | @item @var{size} | |
1541 | Specifies the size in bytes of the data store region being replaced. | |
1542 | ||
1543 | @item @var{data} | |
1544 | Specifies a pointer to the new data that will be copied into the data | |
1545 | store. | |
1546 | ||
1547 | @end table | |
1548 | ||
8925f36f | 1549 | @code{glBufferSubData} redefines some or all of the data store for the |
f37e7e3d | 1550 | buffer object currently bound to @var{target}. Data starting at byte |
8925f36f | 1551 | offset @var{offset} and extending for @var{size} bytes is copied to the |
f37e7e3d | 1552 | data store from the memory pointed to by @var{data}. An error is thrown |
8925f36f AW |
1553 | if @var{offset} and @var{size} together define a range beyond the bounds |
1554 | of the buffer object's data store. | |
1555 | ||
8925f36f AW |
1556 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
1557 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
1558 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
1559 | ||
1560 | @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is | |
1561 | negative, or if together they define a region of memory that extends | |
1562 | beyond the buffer object's allocated data store. | |
1563 | ||
1564 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
1565 | name 0 is bound to @var{target}. | |
1566 | ||
1567 | @code{GL_INVALID_OPERATION} is generated if the buffer object being | |
1568 | updated is mapped. | |
1569 | ||
1570 | @code{GL_INVALID_OPERATION} is generated if @code{glBufferSubData} is | |
1571 | executed between the execution of @code{glBegin} and the corresponding | |
1572 | execution of @code{glEnd}. | |
1573 | ||
bb894c9d | 1574 | @end deftypefun |
8925f36f | 1575 | |
bb894c9d | 1576 | @deftypefun void glCallLists n type lists |
3c9b6116 AW |
1577 | Execute a list of display lists. |
1578 | ||
8925f36f AW |
1579 | @table @asis |
1580 | @item @var{n} | |
1581 | Specifies the number of display lists to be executed. | |
1582 | ||
1583 | @item @var{type} | |
f37e7e3d | 1584 | Specifies the type of values in @var{lists}. Symbolic constants |
8925f36f AW |
1585 | @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, |
1586 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
1587 | @code{GL_FLOAT}, @code{GL_2_BYTES}, @code{GL_3_BYTES}, and | |
1588 | @code{GL_4_BYTES} are accepted. | |
1589 | ||
1590 | @item @var{lists} | |
1591 | Specifies the address of an array of name offsets in the display list. | |
1592 | The pointer type is void because the offsets can be bytes, shorts, ints, | |
1593 | or floats, depending on the value of @var{type}. | |
1594 | ||
1595 | @end table | |
1596 | ||
8925f36f | 1597 | @code{glCallLists} causes each display list in the list of names passed |
f37e7e3d | 1598 | as @var{lists} to be executed. As a result, the commands saved in each |
8925f36f | 1599 | display list are executed in order, just as if they were called without |
f37e7e3d | 1600 | using a display list. Names of display lists that have not been defined |
8925f36f AW |
1601 | are ignored. |
1602 | ||
1603 | @code{glCallLists} provides an efficient means for executing more than | |
f37e7e3d DH |
1604 | one display list. @var{type} allows lists with various name formats to |
1605 | be accepted. The formats are as follows: | |
8925f36f AW |
1606 | |
1607 | @table @asis | |
1608 | @item @code{GL_BYTE} | |
1609 | @var{lists} is treated as an array of signed bytes, each in the range | |
3c9b6116 | 1610 | @r{-128} through 127. |
8925f36f AW |
1611 | |
1612 | @item @code{GL_UNSIGNED_BYTE} | |
1613 | @var{lists} is treated as an array of unsigned bytes, each in the range | |
1614 | 0 through 255. | |
1615 | ||
1616 | @item @code{GL_SHORT} | |
1617 | @var{lists} is treated as an array of signed two-byte integers, each in | |
3c9b6116 | 1618 | the range @r{-32768} through 32767. |
8925f36f AW |
1619 | |
1620 | @item @code{GL_UNSIGNED_SHORT} | |
1621 | @var{lists} is treated as an array of unsigned two-byte integers, each | |
1622 | in the range 0 through 65535. | |
1623 | ||
1624 | @item @code{GL_INT} | |
1625 | @var{lists} is treated as an array of signed four-byte integers. | |
1626 | ||
1627 | @item @code{GL_UNSIGNED_INT} | |
1628 | @var{lists} is treated as an array of unsigned four-byte integers. | |
1629 | ||
1630 | @item @code{GL_FLOAT} | |
1631 | @var{lists} is treated as an array of four-byte floating-point values. | |
1632 | ||
1633 | @item @code{GL_2_BYTES} | |
f37e7e3d DH |
1634 | @var{lists} is treated as an array of unsigned bytes. Each pair of bytes |
1635 | specifies a single display-list name. The value of the pair is computed | |
1636 | as 256 times the unsigned value of the first byte plus the unsigned | |
1637 | value of the second byte. | |
8925f36f AW |
1638 | |
1639 | @item @code{GL_3_BYTES} | |
f37e7e3d DH |
1640 | @var{lists} is treated as an array of unsigned bytes. Each triplet of |
1641 | bytes specifies a single display-list name. The value of the triplet is | |
8925f36f AW |
1642 | computed as 65536 times the unsigned value of the first byte, plus 256 |
1643 | times the unsigned value of the second byte, plus the unsigned value of | |
1644 | the third byte. | |
1645 | ||
1646 | @item @code{GL_4_BYTES} | |
f37e7e3d DH |
1647 | @var{lists} is treated as an array of unsigned bytes. Each quadruplet of |
1648 | bytes specifies a single display-list name. The value of the quadruplet | |
1649 | is computed as 16777216 times the unsigned value of the first byte, plus | |
1650 | 65536 times the unsigned value of the second byte, plus 256 times the | |
1651 | unsigned value of the third byte, plus the unsigned value of the fourth | |
1652 | byte. | |
8925f36f AW |
1653 | |
1654 | @end table | |
1655 | ||
f37e7e3d | 1656 | The list of display-list names is not null-terminated. Rather, @var{n} |
8925f36f AW |
1657 | specifies how many names are to be taken from @var{lists}. |
1658 | ||
1659 | An additional level of indirection is made available with the | |
1660 | @code{glListBase} command, which specifies an unsigned offset that is | |
1661 | added to each display-list name specified in @var{lists} before that | |
1662 | display list is executed. | |
1663 | ||
f37e7e3d | 1664 | @code{glCallLists} can appear inside a display list. To avoid the |
8925f36f AW |
1665 | possibility of infinite recursion resulting from display lists calling |
1666 | one another, a limit is placed on the nesting level of display lists | |
f37e7e3d | 1667 | during display-list execution. This limit must be at least 64, and it |
8925f36f AW |
1668 | depends on the implementation. |
1669 | ||
1670 | GL state is not saved and restored across a call to @code{glCallLists}. | |
1671 | Thus, changes made to GL state during the execution of the display lists | |
f37e7e3d | 1672 | remain after execution is completed. Use @code{glPushAttrib}, |
8925f36f AW |
1673 | @code{glPopAttrib}, @code{glPushMatrix}, and @code{glPopMatrix} to |
1674 | preserve GL state across @code{glCallLists} calls. | |
1675 | ||
8925f36f AW |
1676 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
1677 | ||
1678 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of | |
1679 | @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, | |
1680 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
1681 | @code{GL_FLOAT}, @code{GL_2_BYTES}, @code{GL_3_BYTES}, | |
1682 | @code{GL_4_BYTES}. | |
1683 | ||
bb894c9d | 1684 | @end deftypefun |
8925f36f | 1685 | |
bb894c9d | 1686 | @deftypefun void glCallList list |
3c9b6116 AW |
1687 | Execute a display list. |
1688 | ||
8925f36f AW |
1689 | @table @asis |
1690 | @item @var{list} | |
1691 | Specifies the integer name of the display list to be executed. | |
1692 | ||
1693 | @end table | |
1694 | ||
f37e7e3d | 1695 | @code{glCallList} causes the named display list to be executed. The |
8925f36f | 1696 | commands saved in the display list are executed in order, just as if |
f37e7e3d | 1697 | they were called without using a display list. If @var{list} has not |
8925f36f AW |
1698 | been defined as a display list, @code{glCallList} is ignored. |
1699 | ||
f37e7e3d | 1700 | @code{glCallList} can appear inside a display list. To avoid the |
8925f36f AW |
1701 | possibility of infinite recursion resulting from display lists calling |
1702 | one another, a limit is placed on the nesting level of display lists | |
f37e7e3d DH |
1703 | during display-list execution. This limit is at least 64, and it depends |
1704 | on the implementation. | |
8925f36f AW |
1705 | |
1706 | GL state is not saved and restored across a call to @code{glCallList}. | |
1707 | Thus, changes made to GL state during the execution of a display list | |
f37e7e3d | 1708 | remain after execution of the display list is completed. Use |
8925f36f AW |
1709 | @code{glPushAttrib}, @code{glPopAttrib}, @code{glPushMatrix}, and |
1710 | @code{glPopMatrix} to preserve GL state across @code{glCallList} calls. | |
1711 | ||
bb894c9d | 1712 | @end deftypefun |
8925f36f | 1713 | |
bb894c9d | 1714 | @deftypefun void glClearAccum red green blue alpha |
3c9b6116 AW |
1715 | Specify clear values for the accumulation buffer. |
1716 | ||
8925f36f AW |
1717 | @table @asis |
1718 | @item @var{red} | |
1719 | @itemx @var{green} | |
1720 | @itemx @var{blue} | |
1721 | @itemx @var{alpha} | |
1722 | Specify the red, green, blue, and alpha values used when the | |
f37e7e3d | 1723 | accumulation buffer is cleared. The initial values are all 0. |
8925f36f AW |
1724 | |
1725 | @end table | |
1726 | ||
8925f36f AW |
1727 | @code{glClearAccum} specifies the red, green, blue, and alpha values |
1728 | used by @code{glClear} to clear the accumulation buffer. | |
1729 | ||
1730 | Values specified by @code{glClearAccum} are clamped to the range | |
3c9b6116 | 1731 | @r{[-1,1]}. |
8925f36f | 1732 | |
8925f36f AW |
1733 | @code{GL_INVALID_OPERATION} is generated if @code{glClearAccum} is |
1734 | executed between the execution of @code{glBegin} and the corresponding | |
1735 | execution of @code{glEnd}. | |
1736 | ||
bb894c9d | 1737 | @end deftypefun |
8925f36f | 1738 | |
bb894c9d | 1739 | @deftypefun void glClearColor red green blue alpha |
3c9b6116 AW |
1740 | Specify clear values for the color buffers. |
1741 | ||
8925f36f AW |
1742 | @table @asis |
1743 | @item @var{red} | |
1744 | @itemx @var{green} | |
1745 | @itemx @var{blue} | |
1746 | @itemx @var{alpha} | |
1747 | Specify the red, green, blue, and alpha values used when the color | |
f37e7e3d | 1748 | buffers are cleared. The initial values are all 0. |
8925f36f AW |
1749 | |
1750 | @end table | |
1751 | ||
8925f36f | 1752 | @code{glClearColor} specifies the red, green, blue, and alpha values |
f37e7e3d | 1753 | used by @code{glClear} to clear the color buffers. Values specified by |
3c9b6116 | 1754 | @code{glClearColor} are clamped to the range @r{[0,1]}. |
8925f36f | 1755 | |
8925f36f AW |
1756 | @code{GL_INVALID_OPERATION} is generated if @code{glClearColor} is |
1757 | executed between the execution of @code{glBegin} and the corresponding | |
1758 | execution of @code{glEnd}. | |
1759 | ||
bb894c9d | 1760 | @end deftypefun |
8925f36f | 1761 | |
bb894c9d | 1762 | @deftypefun void glClearDepth depth |
3c9b6116 AW |
1763 | Specify the clear value for the depth buffer. |
1764 | ||
8925f36f AW |
1765 | @table @asis |
1766 | @item @var{depth} | |
f37e7e3d | 1767 | Specifies the depth value used when the depth buffer is cleared. The |
8925f36f AW |
1768 | initial value is 1. |
1769 | ||
1770 | @end table | |
1771 | ||
8925f36f | 1772 | @code{glClearDepth} specifies the depth value used by @code{glClear} to |
f37e7e3d | 1773 | clear the depth buffer. Values specified by @code{glClearDepth} are |
3c9b6116 | 1774 | clamped to the range @r{[0,1]}. |
8925f36f | 1775 | |
8925f36f AW |
1776 | @code{GL_INVALID_OPERATION} is generated if @code{glClearDepth} is |
1777 | executed between the execution of @code{glBegin} and the corresponding | |
1778 | execution of @code{glEnd}. | |
1779 | ||
bb894c9d | 1780 | @end deftypefun |
8925f36f | 1781 | |
bb894c9d | 1782 | @deftypefun void glClearIndex c |
3c9b6116 AW |
1783 | Specify the clear value for the color index buffers. |
1784 | ||
8925f36f AW |
1785 | @table @asis |
1786 | @item @var{c} | |
f37e7e3d | 1787 | Specifies the index used when the color index buffers are cleared. The |
8925f36f AW |
1788 | initial value is 0. |
1789 | ||
1790 | @end table | |
1791 | ||
8925f36f | 1792 | @code{glClearIndex} specifies the index used by @code{glClear} to clear |
f37e7e3d | 1793 | the color index buffers. @var{c} is not clamped. Rather, @var{c} is |
8925f36f | 1794 | converted to a fixed-point value with unspecified precision to the right |
f37e7e3d | 1795 | of the binary point. The integer part of this value is then masked with |
3c9b6116 AW |
1796 | @r{2^@var{m}-1}, where @r{@var{m}} is the number of bits in a color |
1797 | index stored in the frame buffer. | |
8925f36f | 1798 | |
8925f36f AW |
1799 | @code{GL_INVALID_OPERATION} is generated if @code{glClearIndex} is |
1800 | executed between the execution of @code{glBegin} and the corresponding | |
1801 | execution of @code{glEnd}. | |
1802 | ||
bb894c9d | 1803 | @end deftypefun |
8925f36f | 1804 | |
bb894c9d | 1805 | @deftypefun void glClearStencil s |
3c9b6116 AW |
1806 | Specify the clear value for the stencil buffer. |
1807 | ||
8925f36f AW |
1808 | @table @asis |
1809 | @item @var{s} | |
f37e7e3d DH |
1810 | Specifies the index used when the stencil buffer is cleared. The initial |
1811 | value is 0. | |
8925f36f AW |
1812 | |
1813 | @end table | |
1814 | ||
8925f36f | 1815 | @code{glClearStencil} specifies the index used by @code{glClear} to |
f37e7e3d | 1816 | clear the stencil buffer. @var{s} is masked with @r{2^@var{m}-1}, where |
3c9b6116 | 1817 | @r{@var{m}} is the number of bits in the stencil buffer. |
8925f36f | 1818 | |
8925f36f AW |
1819 | @code{GL_INVALID_OPERATION} is generated if @code{glClearStencil} is |
1820 | executed between the execution of @code{glBegin} and the corresponding | |
1821 | execution of @code{glEnd}. | |
1822 | ||
bb894c9d | 1823 | @end deftypefun |
8925f36f | 1824 | |
bb894c9d | 1825 | @deftypefun void glClear mask |
3c9b6116 AW |
1826 | Clear buffers to preset values. |
1827 | ||
8925f36f AW |
1828 | @table @asis |
1829 | @item @var{mask} | |
f37e7e3d | 1830 | Bitwise OR of masks that indicate the buffers to be cleared. The four |
8925f36f AW |
1831 | masks are @code{GL_COLOR_BUFFER_BIT}, @code{GL_DEPTH_BUFFER_BIT}, |
1832 | @code{GL_ACCUM_BUFFER_BIT}, and @code{GL_STENCIL_BUFFER_BIT}. | |
1833 | ||
1834 | @end table | |
1835 | ||
8925f36f AW |
1836 | @code{glClear} sets the bitplane area of the window to values previously |
1837 | selected by @code{glClearColor}, @code{glClearIndex}, | |
1838 | @code{glClearDepth}, @code{glClearStencil}, and @code{glClearAccum}. | |
1839 | Multiple color buffers can be cleared simultaneously by selecting more | |
1840 | than one buffer at a time using @code{glDrawBuffer}. | |
1841 | ||
1842 | The pixel ownership test, the scissor test, dithering, and the buffer | |
f37e7e3d DH |
1843 | writemasks affect the operation of @code{glClear}. The scissor box |
1844 | bounds the cleared region. Alpha function, blend function, logical | |
8925f36f AW |
1845 | operation, stenciling, texture mapping, and depth-buffering are ignored |
1846 | by @code{glClear}. | |
1847 | ||
1848 | @code{glClear} takes a single argument that is the bitwise OR of several | |
1849 | values indicating which buffer is to be cleared. | |
1850 | ||
1851 | The values are as follows: | |
1852 | ||
1853 | @table @asis | |
1854 | @item @code{GL_COLOR_BUFFER_BIT} | |
1855 | Indicates the buffers currently enabled for color writing. | |
1856 | ||
1857 | @item @code{GL_DEPTH_BUFFER_BIT} | |
1858 | Indicates the depth buffer. | |
1859 | ||
1860 | @item @code{GL_ACCUM_BUFFER_BIT} | |
1861 | Indicates the accumulation buffer. | |
1862 | ||
1863 | @item @code{GL_STENCIL_BUFFER_BIT} | |
1864 | Indicates the stencil buffer. | |
1865 | ||
1866 | @end table | |
1867 | ||
1868 | The value to which each buffer is cleared depends on the setting of the | |
1869 | clear value for that buffer. | |
1870 | ||
8925f36f AW |
1871 | @code{GL_INVALID_VALUE} is generated if any bit other than the four |
1872 | defined bits is set in @var{mask}. | |
1873 | ||
1874 | @code{GL_INVALID_OPERATION} is generated if @code{glClear} is executed | |
1875 | between the execution of @code{glBegin} and the corresponding execution | |
1876 | of @code{glEnd}. | |
1877 | ||
bb894c9d | 1878 | @end deftypefun |
8925f36f | 1879 | |
bb894c9d | 1880 | @deftypefun void glClientActiveTexture texture |
3c9b6116 AW |
1881 | Select active texture unit. |
1882 | ||
8925f36f AW |
1883 | @table @asis |
1884 | @item @var{texture} | |
f37e7e3d DH |
1885 | Specifies which texture unit to make active. The number of texture units |
1886 | is implementation dependent, but must be at least two. @var{texture} | |
1887 | must be one of @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to | |
1888 | the value of @code{GL_MAX_TEXTURE_COORDS} - 1, which is an | |
1889 | implementation-dependent value. The initial value is @code{GL_TEXTURE0}. | |
8925f36f AW |
1890 | |
1891 | @end table | |
1892 | ||
8925f36f AW |
1893 | @code{glClientActiveTexture} selects the vertex array client state |
1894 | parameters to be modified by @code{glTexCoordPointer}, and enabled or | |
1895 | disabled with @code{glEnableClientState} or @code{glDisableClientState}, | |
1896 | respectively, when called with a parameter of | |
1897 | @code{GL_TEXTURE_COORD_ARRAY}. | |
1898 | ||
8925f36f | 1899 | @code{GL_INVALID_ENUM} is generated if @var{texture} is not one of |
3c9b6116 | 1900 | @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to the value of |
8925f36f AW |
1901 | @code{GL_MAX_TEXTURE_COORDS} - 1. |
1902 | ||
bb894c9d | 1903 | @end deftypefun |
8925f36f | 1904 | |
bb894c9d | 1905 | @deftypefun void glClipPlane plane equation |
3c9b6116 AW |
1906 | Specify a plane against which all geometry is clipped. |
1907 | ||
8925f36f AW |
1908 | @table @asis |
1909 | @item @var{plane} | |
f37e7e3d | 1910 | Specifies which clipping plane is being positioned. Symbolic names of |
8925f36f | 1911 | the form @code{GL_CLIP_PLANE}@var{i}, where @var{i} is an integer |
3c9b6116 | 1912 | between 0 and @code{GL_MAX_CLIP_PLANES}@r{-1}, are accepted. |
8925f36f AW |
1913 | |
1914 | @item @var{equation} | |
1915 | Specifies the address of an array of four double-precision | |
f37e7e3d | 1916 | floating-point values. These values are interpreted as a plane equation. |
8925f36f AW |
1917 | |
1918 | @end table | |
1919 | ||
8925f36f | 1920 | Geometry is always clipped against the boundaries of a six-plane frustum |
f37e7e3d | 1921 | in @var{x}, @var{y}, and @var{z}. @code{glClipPlane} allows the |
8925f36f AW |
1922 | specification of additional planes, not necessarily perpendicular to the |
1923 | @var{x}, @var{y}, or @var{z} axis, against which all geometry is | |
f37e7e3d DH |
1924 | clipped. To determine the maximum number of additional clipping planes, |
1925 | call @code{glGetIntegerv} with argument @code{GL_MAX_CLIP_PLANES}. All | |
1926 | implementations support at least six such clipping planes. Because the | |
8925f36f AW |
1927 | resulting clipping region is the intersection of the defined |
1928 | half-spaces, it is always convex. | |
1929 | ||
1930 | @code{glClipPlane} specifies a half-space using a four-component plane | |
f37e7e3d | 1931 | equation. When @code{glClipPlane} is called, @var{equation} is |
8925f36f | 1932 | transformed by the inverse of the modelview matrix and stored in the |
f37e7e3d DH |
1933 | resulting eye coordinates. Subsequent changes to the modelview matrix |
1934 | have no effect on the stored plane-equation components. If the dot | |
8925f36f AW |
1935 | product of the eye coordinates of a vertex with the stored plane |
1936 | equation components is positive or zero, the vertex is @var{in} with | |
f37e7e3d | 1937 | respect to that clipping plane. Otherwise, it is @var{out}. |
8925f36f AW |
1938 | |
1939 | To enable and disable clipping planes, call @code{glEnable} and | |
1940 | @code{glDisable} with the argument @code{GL_CLIP_PLANE}@var{i}, where | |
1941 | @var{i} is the plane number. | |
1942 | ||
1943 | All clipping planes are initially defined as (0, 0, 0, 0) in eye | |
1944 | coordinates and are disabled. | |
1945 | ||
8925f36f AW |
1946 | @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted |
1947 | value. | |
1948 | ||
1949 | @code{GL_INVALID_OPERATION} is generated if @code{glClipPlane} is | |
1950 | executed between the execution of @code{glBegin} and the corresponding | |
1951 | execution of @code{glEnd}. | |
1952 | ||
bb894c9d | 1953 | @end deftypefun |
8925f36f | 1954 | |
bb894c9d | 1955 | @deftypefun void glColorMask red green blue alpha |
3c9b6116 AW |
1956 | Enable and disable writing of frame buffer color components. |
1957 | ||
8925f36f AW |
1958 | @table @asis |
1959 | @item @var{red} | |
1960 | @itemx @var{green} | |
1961 | @itemx @var{blue} | |
1962 | @itemx @var{alpha} | |
1963 | Specify whether red, green, blue, and alpha can or cannot be written | |
f37e7e3d | 1964 | into the frame buffer. The initial values are all @code{GL_TRUE}, |
8925f36f AW |
1965 | indicating that the color components can be written. |
1966 | ||
1967 | @end table | |
1968 | ||
8925f36f | 1969 | @code{glColorMask} specifies whether the individual color components in |
f37e7e3d | 1970 | the frame buffer can or cannot be written. If @var{red} is |
8925f36f AW |
1971 | @code{GL_FALSE}, for example, no change is made to the red component of |
1972 | any pixel in any of the color buffers, regardless of the drawing | |
1973 | operation attempted. | |
1974 | ||
f37e7e3d | 1975 | Changes to individual bits of components cannot be controlled. Rather, |
8925f36f AW |
1976 | changes are either enabled or disabled for entire color components. |
1977 | ||
8925f36f AW |
1978 | @code{GL_INVALID_OPERATION} is generated if @code{glColorMask} is |
1979 | executed between the execution of @code{glBegin} and the corresponding | |
1980 | execution of @code{glEnd}. | |
1981 | ||
bb894c9d | 1982 | @end deftypefun |
8925f36f | 1983 | |
bb894c9d | 1984 | @deftypefun void glColorMaterial face mode |
3c9b6116 AW |
1985 | Cause a material color to track the current color. |
1986 | ||
8925f36f AW |
1987 | @table @asis |
1988 | @item @var{face} | |
1989 | Specifies whether front, back, or both front and back material | |
f37e7e3d DH |
1990 | parameters should track the current color. Accepted values are |
1991 | @code{GL_FRONT}, @code{GL_BACK}, and @code{GL_FRONT_AND_BACK}. The | |
8925f36f AW |
1992 | initial value is @code{GL_FRONT_AND_BACK}. |
1993 | ||
1994 | @item @var{mode} | |
1995 | Specifies which of several material parameters track the current color. | |
1996 | Accepted values are @code{GL_EMISSION}, @code{GL_AMBIENT}, | |
1997 | @code{GL_DIFFUSE}, @code{GL_SPECULAR}, and | |
f37e7e3d | 1998 | @code{GL_AMBIENT_AND_DIFFUSE}. The initial value is |
8925f36f AW |
1999 | @code{GL_AMBIENT_AND_DIFFUSE}. |
2000 | ||
2001 | @end table | |
2002 | ||
8925f36f | 2003 | @code{glColorMaterial} specifies which material parameters track the |
f37e7e3d | 2004 | current color. When @code{GL_COLOR_MATERIAL} is enabled, the material |
8925f36f AW |
2005 | parameter or parameters specified by @var{mode}, of the material or |
2006 | materials specified by @var{face}, track the current color at all times. | |
2007 | ||
2008 | To enable and disable @code{GL_COLOR_MATERIAL}, call @code{glEnable} and | |
2009 | @code{glDisable} with argument @code{GL_COLOR_MATERIAL}. | |
2010 | @code{GL_COLOR_MATERIAL} is initially disabled. | |
2011 | ||
8925f36f AW |
2012 | @code{GL_INVALID_ENUM} is generated if @var{face} or @var{mode} is not |
2013 | an accepted value. | |
2014 | ||
2015 | @code{GL_INVALID_OPERATION} is generated if @code{glColorMaterial} is | |
2016 | executed between the execution of @code{glBegin} and the corresponding | |
2017 | execution of @code{glEnd}. | |
2018 | ||
bb894c9d | 2019 | @end deftypefun |
8925f36f | 2020 | |
bb894c9d | 2021 | @deftypefun void glColorPointer size type stride pointer |
3c9b6116 AW |
2022 | Define an array of colors. |
2023 | ||
8925f36f AW |
2024 | @table @asis |
2025 | @item @var{size} | |
f37e7e3d | 2026 | Specifies the number of components per color. Must be 3 or 4. The |
8925f36f AW |
2027 | initial value is 4. |
2028 | ||
2029 | @item @var{type} | |
f37e7e3d | 2030 | Specifies the data type of each color component in the array. Symbolic |
8925f36f AW |
2031 | constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, |
2032 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
f37e7e3d DH |
2033 | @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is |
2034 | @code{GL_FLOAT}. | |
8925f36f AW |
2035 | |
2036 | @item @var{stride} | |
f37e7e3d DH |
2037 | Specifies the byte offset between consecutive colors. If @var{stride} is |
2038 | 0, the colors are understood to be tightly packed in the array. The | |
8925f36f AW |
2039 | initial value is 0. |
2040 | ||
2041 | @item @var{pointer} | |
2042 | Specifies a pointer to the first component of the first color element in | |
f37e7e3d | 2043 | the array. The initial value is 0. |
8925f36f AW |
2044 | |
2045 | @end table | |
2046 | ||
8925f36f | 2047 | @code{glColorPointer} specifies the location and data format of an array |
f37e7e3d DH |
2048 | of color components to use when rendering. @var{size} specifies the |
2049 | number of components per color, and must be 3 or 4. @var{type} specifies | |
2050 | the data type of each color component, and @var{stride} specifies the | |
2051 | byte stride from one color to the next, allowing vertices and attributes | |
2052 | to be packed into a single array or stored in separate arrays. | |
2053 | (Single-array storage may be more efficient on some implementations; see | |
2054 | @code{glInterleavedArrays}.) | |
8925f36f AW |
2055 | |
2056 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
2057 | target (see @code{glBindBuffer}) while a color array is specified, | |
2058 | @var{pointer} is treated as a byte offset into the buffer object's data | |
f37e7e3d | 2059 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) |
8925f36f AW |
2060 | is saved as color vertex array client-side state |
2061 | (@code{GL_COLOR_ARRAY_BUFFER_BINDING}). | |
2062 | ||
2063 | When a color array is specified, @var{size}, @var{type}, @var{stride}, | |
2064 | and @var{pointer} are saved as client-side state, in addition to the | |
2065 | current vertex array buffer object binding. | |
2066 | ||
2067 | To enable and disable the color array, call @code{glEnableClientState} | |
2068 | and @code{glDisableClientState} with the argument @code{GL_COLOR_ARRAY}. | |
2069 | If enabled, the color array is used when @code{glDrawArrays}, | |
2070 | @code{glMultiDrawArrays}, @code{glDrawElements}, | |
2071 | @code{glMultiDrawElements}, @code{glDrawRangeElements}, or | |
2072 | @code{glArrayElement} is called. | |
2073 | ||
8925f36f AW |
2074 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 3 or 4. |
2075 | ||
2076 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
2077 | value. | |
2078 | ||
2079 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
2080 | ||
bb894c9d | 2081 | @end deftypefun |
8925f36f | 2082 | |
bb894c9d | 2083 | @deftypefun void glColorSubTable target start count format type data |
3c9b6116 AW |
2084 | Respecify a portion of a color table. |
2085 | ||
8925f36f AW |
2086 | @table @asis |
2087 | @item @var{target} | |
2088 | Must be one of @code{GL_COLOR_TABLE}, | |
2089 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
2090 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
2091 | ||
2092 | @item @var{start} | |
2093 | The starting index of the portion of the color table to be replaced. | |
2094 | ||
2095 | @item @var{count} | |
2096 | The number of table entries to replace. | |
2097 | ||
2098 | @item @var{format} | |
f37e7e3d | 2099 | The format of the pixel data in @var{data}. The allowable values are |
8925f36f AW |
2100 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
2101 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, | |
2102 | @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}. | |
2103 | ||
2104 | @item @var{type} | |
f37e7e3d | 2105 | The type of the pixel data in @var{data}. The allowable values are |
8925f36f AW |
2106 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT}, |
2107 | @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
2108 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
2109 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
2110 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
2111 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
2112 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
2113 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
2114 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
2115 | ||
2116 | @item @var{data} | |
2117 | Pointer to a one-dimensional array of pixel data that is processed to | |
2118 | replace the specified region of the color table. | |
2119 | ||
2120 | @end table | |
2121 | ||
8925f36f | 2122 | @code{glColorSubTable} is used to respecify a contiguous portion of a |
f37e7e3d | 2123 | color table previously defined using @code{glColorTable}. The pixels |
8925f36f | 2124 | referenced by @var{data} replace the portion of the existing table from |
f37e7e3d | 2125 | indices @var{start} to @r{@var{start}+@var{count}-1}, inclusive. This |
8925f36f | 2126 | region may not include any entries outside the range of the color table |
f37e7e3d | 2127 | as it was originally specified. It is not an error to specify a |
8925f36f AW |
2128 | subtexture with width of 0, but such a specification has no effect. |
2129 | ||
2130 | If a non-zero named buffer object is bound to the | |
2131 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2132 | portion of a color table is respecified, @var{data} is treated as a byte | |
2133 | offset into the buffer object's data store. | |
2134 | ||
8925f36f AW |
2135 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
2136 | allowable values. | |
2137 | ||
2138 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
2139 | allowable values. | |
2140 | ||
2141 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
2142 | allowable values. | |
2143 | ||
2144 | @code{GL_INVALID_VALUE} is generated if | |
3c9b6116 | 2145 | @r{@var{start}+@var{count}>@var{width}}. |
8925f36f AW |
2146 | |
2147 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2148 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2149 | object's data store is currently mapped. | |
2150 | ||
2151 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2152 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2153 | would be unpacked from the buffer object such that the memory reads | |
2154 | required would exceed the data store size. | |
2155 | ||
2156 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2157 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
2158 | is not evenly divisible into the number of bytes needed to store in | |
2159 | memory a datum indicated by @var{type}. | |
2160 | ||
2161 | @code{GL_INVALID_OPERATION} is generated if @code{glColorSubTable} is | |
2162 | executed between the execution of @code{glBegin} and the corresponding | |
2163 | execution of @code{glEnd}. | |
2164 | ||
bb894c9d | 2165 | @end deftypefun |
8925f36f | 2166 | |
b002944d AW |
2167 | @deftypefun void glColorTableParameterfv target pname params |
2168 | @deftypefunx void glColorTableParameteriv target pname params | |
2169 | Set color lookup table parameters. | |
2170 | ||
2171 | @table @asis | |
2172 | @item @var{target} | |
f37e7e3d | 2173 | The target color table. Must be @code{GL_COLOR_TABLE}, |
b002944d AW |
2174 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or |
2175 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
2176 | ||
2177 | @item @var{pname} | |
f37e7e3d DH |
2178 | The symbolic name of a texture color lookup table parameter. Must be one |
2179 | of @code{GL_COLOR_TABLE_SCALE} or @code{GL_COLOR_TABLE_BIAS}. | |
b002944d AW |
2180 | |
2181 | @item @var{params} | |
2182 | A pointer to an array where the values of the parameters are stored. | |
2183 | ||
2184 | @end table | |
2185 | ||
2186 | @code{glColorTableParameter} is used to specify the scale factors and | |
2187 | bias terms applied to color components when they are loaded into a color | |
f37e7e3d DH |
2188 | table. @var{target} indicates which color table the scale and bias terms |
2189 | apply to; it must be set to @code{GL_COLOR_TABLE}, | |
b002944d AW |
2190 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or |
2191 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
2192 | ||
2193 | @var{pname} must be @code{GL_COLOR_TABLE_SCALE} to set the scale | |
f37e7e3d | 2194 | factors. In this case, @var{params} points to an array of four values, |
b002944d AW |
2195 | which are the scale factors for red, green, blue, and alpha, in that |
2196 | order. | |
2197 | ||
f37e7e3d | 2198 | @var{pname} must be @code{GL_COLOR_TABLE_BIAS} to set the bias terms. In |
b002944d AW |
2199 | this case, @var{params} points to an array of four values, which are the |
2200 | bias terms for red, green, blue, and alpha, in that order. | |
2201 | ||
2202 | The color tables themselves are specified by calling | |
2203 | @code{glColorTable}. | |
2204 | ||
2205 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
2206 | not an acceptable value. | |
2207 | ||
2208 | @code{GL_INVALID_OPERATION} is generated if @code{glColorTableParameter} | |
2209 | is executed between the execution of @code{glBegin} and the | |
2210 | corresponding execution of @code{glEnd}. | |
2211 | ||
2212 | @end deftypefun | |
2213 | ||
bb894c9d | 2214 | @deftypefun void glColorTable target internalformat width format type data |
3c9b6116 AW |
2215 | Define a color lookup table. |
2216 | ||
8925f36f AW |
2217 | @table @asis |
2218 | @item @var{target} | |
2219 | Must be one of @code{GL_COLOR_TABLE}, | |
2220 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, | |
2221 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE}, | |
2222 | @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or | |
2223 | @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}. | |
2224 | ||
2225 | @item @var{internalformat} | |
f37e7e3d | 2226 | The internal format of the color table. The allowable values are |
8925f36f AW |
2227 | @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, |
2228 | @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
2229 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
2230 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
2231 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
2232 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
2233 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
2234 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
2235 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
2236 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
2237 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
2238 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
2239 | @code{GL_RGBA12}, and @code{GL_RGBA16}. | |
2240 | ||
2241 | @item @var{width} | |
2242 | The number of entries in the color lookup table specified by @var{data}. | |
2243 | ||
2244 | @item @var{format} | |
f37e7e3d | 2245 | The format of the pixel data in @var{data}. The allowable values are |
8925f36f AW |
2246 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
2247 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, | |
2248 | @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}. | |
2249 | ||
2250 | @item @var{type} | |
f37e7e3d | 2251 | The type of the pixel data in @var{data}. The allowable values are |
8925f36f AW |
2252 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT}, |
2253 | @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
2254 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
2255 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
2256 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
2257 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
2258 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
2259 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
2260 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
2261 | ||
2262 | @item @var{data} | |
2263 | Pointer to a one-dimensional array of pixel data that is processed to | |
2264 | build the color table. | |
2265 | ||
2266 | @end table | |
2267 | ||
8925f36f AW |
2268 | @code{glColorTable} may be used in two ways: to test the actual size and |
2269 | color resolution of a lookup table given a particular set of parameters, | |
f37e7e3d | 2270 | or to load the contents of a color lookup table. Use the targets |
8925f36f AW |
2271 | @code{GL_PROXY_*} for the first case and the other targets for the |
2272 | second case. | |
2273 | ||
2274 | If a non-zero named buffer object is bound to the | |
2275 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2276 | color table is specified, @var{data} is treated as a byte offset into | |
2277 | the buffer object's data store. | |
2278 | ||
2279 | If @var{target} is @code{GL_COLOR_TABLE}, | |
2280 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
2281 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{glColorTable} builds a | |
f37e7e3d DH |
2282 | color lookup table from an array of pixels. The pixel array specified by |
2283 | @var{width}, @var{format}, @var{type}, and @var{data} is extracted from | |
2284 | memory and processed just as if @code{glDrawPixels} were called, but | |
2285 | processing stops after the final expansion to RGBA is completed. | |
8925f36f AW |
2286 | |
2287 | The four scale parameters and the four bias parameters that are defined | |
2288 | for the table are then used to scale and bias the R, G, B, and A | |
f37e7e3d DH |
2289 | components of each pixel. (Use @code{glColorTableParameter} to set these |
2290 | scale and bias parameters.) | |
8925f36f | 2291 | |
f37e7e3d | 2292 | Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each |
3c9b6116 | 2293 | pixel is then converted to the internal format specified by |
f37e7e3d | 2294 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 2295 | of the pixel (R, G, B, and A) to the values included in the internal |
f37e7e3d | 2296 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
2297 | is as follows: |
2298 | ||
2299 | ||
2300 | ||
2301 | @table @asis | |
2302 | @item @strong{Internal Format} | |
2303 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
2304 | @strong{Luminance}, @strong{Intensity} | |
2305 | ||
2306 | @item @code{GL_ALPHA} | |
2307 | , , , A , , | |
2308 | ||
2309 | @item @code{GL_LUMINANCE} | |
2310 | , , , , R , | |
2311 | ||
2312 | @item @code{GL_LUMINANCE_ALPHA} | |
2313 | , , , A , R , | |
2314 | ||
2315 | @item @code{GL_INTENSITY} | |
2316 | , , , , , R | |
2317 | ||
2318 | @item @code{GL_RGB} | |
2319 | R , G , B , , , | |
2320 | ||
2321 | @item @code{GL_RGBA} | |
2322 | R , G , B , A , , | |
2323 | ||
2324 | @end table | |
2325 | ||
2326 | Finally, the red, green, blue, alpha, luminance, and/or intensity | |
f37e7e3d | 2327 | components of the resulting pixels are stored in the color table. They |
8925f36f | 2328 | form a one-dimensional table with indices in the range |
3c9b6116 | 2329 | @r{[0,@var{width}-1]}. |
8925f36f AW |
2330 | |
2331 | If @var{target} is @code{GL_PROXY_*}, @code{glColorTable} recomputes and | |
2332 | stores the values of the proxy color table's state variables | |
2333 | @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH}, | |
2334 | @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE}, | |
2335 | @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE}, | |
2336 | @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, and | |
f37e7e3d DH |
2337 | @code{GL_COLOR_TABLE_INTENSITY_SIZE}. There is no effect on the image or |
2338 | state of any actual color table. If the specified color table is too | |
8925f36f | 2339 | large to be supported, then all the proxy state variables listed above |
f37e7e3d | 2340 | are set to zero. Otherwise, the color table could be supported by |
8925f36f AW |
2341 | @code{glColorTable} using the corresponding non-proxy target, and the |
2342 | proxy state variables are set as if that target were being defined. | |
2343 | ||
2344 | The proxy state variables can be retrieved by calling | |
f37e7e3d | 2345 | @code{glGetColorTableParameter} with a target of @code{GL_PROXY_*}. This |
8925f36f AW |
2346 | allows the application to decide if a particular @code{glColorTable} |
2347 | command would succeed, and to determine what the resulting color table | |
2348 | attributes would be. | |
2349 | ||
2350 | If a color table is enabled, and its width is non-zero, then its | |
2351 | contents are used to replace a subset of the components of each RGBA | |
2352 | pixel group, based on the internal format of the table. | |
2353 | ||
2354 | Each pixel group has color components (R, G, B, A) that are in the range | |
f37e7e3d DH |
2355 | @r{[0.0,1.0]}. The color components are rescaled to the size of the |
2356 | color lookup table to form an index. Then a subset of the components | |
8925f36f | 2357 | based on the internal format of the table are replaced by the table |
f37e7e3d | 2358 | entry selected by that index. If the color components and contents of |
8925f36f AW |
2359 | the table are represented as follows: |
2360 | ||
2361 | ||
2362 | ||
2363 | @table @asis | |
2364 | @item @strong{Representation} | |
2365 | @strong{Meaning} | |
2366 | ||
2367 | @item @code{r} | |
2368 | Table index computed from @code{R} | |
2369 | ||
2370 | @item @code{g} | |
2371 | Table index computed from @code{G} | |
2372 | ||
2373 | @item @code{b} | |
2374 | Table index computed from @code{B} | |
2375 | ||
2376 | @item @code{a} | |
2377 | Table index computed from @code{A} | |
2378 | ||
2379 | @item @code{L[i]} | |
2380 | Luminance value at table index @code{i} | |
2381 | ||
2382 | @item @code{I[i]} | |
2383 | Intensity value at table index @code{i} | |
2384 | ||
2385 | @item @code{R[i]} | |
2386 | Red value at table index @code{i} | |
2387 | ||
2388 | @item @code{G[i]} | |
2389 | Green value at table index @code{i} | |
2390 | ||
2391 | @item @code{B[i]} | |
2392 | Blue value at table index @code{i} | |
2393 | ||
2394 | @item @code{A[i]} | |
2395 | Alpha value at table index @code{i} | |
2396 | ||
2397 | @end table | |
2398 | ||
2399 | then the result of color table lookup is as follows: | |
2400 | ||
2401 | ||
2402 | ||
2403 | @table @asis | |
2404 | @item @strong{} | |
2405 | @strong{Resulting Texture Components} | |
2406 | ||
2407 | @item @strong{Table Internal Format} | |
2408 | @strong{R}, @strong{G}, @strong{B}, @strong{A} | |
2409 | ||
2410 | @item @code{GL_ALPHA} | |
2411 | @code{R}, @code{G}, @code{B}, @code{A[a]} | |
2412 | ||
2413 | @item @code{GL_LUMINANCE} | |
2414 | @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{At} | |
2415 | ||
2416 | @item @code{GL_LUMINANCE_ALPHA} | |
2417 | @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{A[a]} | |
2418 | ||
2419 | @item @code{GL_INTENSITY} | |
2420 | @code{I[r]}, @code{I[g]}, @code{I[b]}, @code{I[a]} | |
2421 | ||
2422 | @item @code{GL_RGB} | |
2423 | @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A} | |
2424 | ||
2425 | @item @code{GL_RGBA} | |
2426 | @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A[a]} | |
2427 | ||
2428 | @end table | |
2429 | ||
2430 | When @code{GL_COLOR_TABLE} is enabled, the colors resulting from the | |
2431 | pixel map operation (if it is enabled) are mapped by the color lookup | |
f37e7e3d | 2432 | table before being passed to the convolution operation. The colors |
8925f36f AW |
2433 | resulting from the convolution operation are modified by the post |
2434 | convolution color lookup table when | |
f37e7e3d DH |
2435 | @code{GL_POST_CONVOLUTION_COLOR_TABLE} is enabled. These modified colors |
2436 | are then sent to the color matrix operation. Finally, if | |
8925f36f AW |
2437 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} is enabled, the colors resulting |
2438 | from the color matrix operation are mapped by the post color matrix | |
2439 | color lookup table before being used by the histogram operation. | |
2440 | ||
2441 | ||
2442 | ||
8925f36f AW |
2443 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
2444 | allowable values. | |
2445 | ||
2446 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
2447 | of the allowable values. | |
2448 | ||
2449 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
2450 | allowable values. | |
2451 | ||
2452 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
2453 | allowable values. | |
2454 | ||
2455 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero. | |
2456 | ||
2457 | @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is | |
2458 | too large to be supported by the implementation, and @var{target} is not | |
2459 | a @code{GL_PROXY_*} target. | |
2460 | ||
2461 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2462 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2463 | object's data store is currently mapped. | |
2464 | ||
2465 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2466 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2467 | would be unpacked from the buffer object such that the memory reads | |
2468 | required would exceed the data store size. | |
2469 | ||
2470 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2471 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
2472 | is not evenly divisible into the number of bytes needed to store in | |
2473 | memory a datum indicated by @var{type}. | |
2474 | ||
2475 | @code{GL_INVALID_OPERATION} is generated if @code{glColorTable} is | |
2476 | executed between the execution of @code{glBegin} and the corresponding | |
2477 | execution of @code{glEnd}. | |
2478 | ||
bb894c9d | 2479 | @end deftypefun |
8925f36f | 2480 | |
d172eed9 AW |
2481 | @deftypefun void glColor3b red green blue |
2482 | @deftypefunx void glColor3s red green blue | |
2483 | @deftypefunx void glColor3i red green blue | |
ca09631c | 2484 | @deftypefunx void glColor3f red green blue |
d172eed9 AW |
2485 | @deftypefunx void glColor3d red green blue |
2486 | @deftypefunx void glColor3ub red green blue | |
2487 | @deftypefunx void glColor3us red green blue | |
bb894c9d | 2488 | @deftypefunx void glColor3ui red green blue |
d172eed9 AW |
2489 | @deftypefunx void glColor4b red green blue alpha |
2490 | @deftypefunx void glColor4s red green blue alpha | |
bb894c9d | 2491 | @deftypefunx void glColor4i red green blue alpha |
ca09631c | 2492 | @deftypefunx void glColor4f red green blue alpha |
d172eed9 AW |
2493 | @deftypefunx void glColor4d red green blue alpha |
2494 | @deftypefunx void glColor4ub red green blue alpha | |
2495 | @deftypefunx void glColor4us red green blue alpha | |
bb894c9d | 2496 | @deftypefunx void glColor4ui red green blue alpha |
d172eed9 AW |
2497 | @deftypefunx void glColor3bv v |
2498 | @deftypefunx void glColor3sv v | |
2499 | @deftypefunx void glColor3iv v | |
2500 | @deftypefunx void glColor3fv v | |
2501 | @deftypefunx void glColor3dv v | |
2502 | @deftypefunx void glColor3ubv v | |
2503 | @deftypefunx void glColor3usv v | |
2504 | @deftypefunx void glColor3uiv v | |
2505 | @deftypefunx void glColor4bv v | |
2506 | @deftypefunx void glColor4sv v | |
2507 | @deftypefunx void glColor4iv v | |
2508 | @deftypefunx void glColor4fv v | |
2509 | @deftypefunx void glColor4dv v | |
2510 | @deftypefunx void glColor4ubv v | |
2511 | @deftypefunx void glColor4usv v | |
2512 | @deftypefunx void glColor4uiv v | |
3c9b6116 AW |
2513 | Set the current color. |
2514 | ||
8925f36f AW |
2515 | @table @asis |
2516 | @item @var{red} | |
2517 | @itemx @var{green} | |
2518 | @itemx @var{blue} | |
2519 | Specify new red, green, and blue values for the current color. | |
2520 | ||
2521 | @item @var{alpha} | |
f37e7e3d | 2522 | Specifies a new alpha value for the current color. Included only in the |
8925f36f AW |
2523 | four-argument @code{glColor4} commands. |
2524 | ||
2525 | @end table | |
2526 | ||
8925f36f | 2527 | The GL stores both a current single-valued color index and a current |
f37e7e3d DH |
2528 | four-valued RGBA color. @code{glColor} sets a new four-valued RGBA |
2529 | color. @code{glColor} has two major variants: @code{glColor3} and | |
2530 | @code{glColor4}. @code{glColor3} variants specify new red, green, and | |
8925f36f | 2531 | blue values explicitly and set the current alpha value to 1.0 (full |
f37e7e3d | 2532 | intensity) implicitly. @code{glColor4} variants specify all four color |
8925f36f AW |
2533 | components explicitly. |
2534 | ||
2535 | @code{glColor3b}, @code{glColor4b}, @code{glColor3s}, @code{glColor4s}, | |
2536 | @code{glColor3i}, and @code{glColor4i} take three or four signed byte, | |
f37e7e3d DH |
2537 | short, or long integers as arguments. When @strong{v} is appended to the |
2538 | name, the color commands can take a pointer to an array of such values. | |
8925f36f AW |
2539 | |
2540 | Current color values are stored in floating-point format, with | |
f37e7e3d | 2541 | unspecified mantissa and exponent sizes. Unsigned integer color |
8925f36f AW |
2542 | components, when specified, are linearly mapped to floating-point values |
2543 | such that the largest representable value maps to 1.0 (full intensity), | |
f37e7e3d | 2544 | and 0 maps to 0.0 (zero intensity). Signed integer color components, |
8925f36f AW |
2545 | when specified, are linearly mapped to floating-point values such that |
2546 | the most positive representable value maps to 1.0, and the most negative | |
f37e7e3d | 2547 | representable value maps to @r{-1.0}. (Note that this mapping does not |
3c9b6116 | 2548 | convert 0 precisely to 0.0.) Floating-point values are mapped directly. |
8925f36f AW |
2549 | |
2550 | Neither floating-point nor signed integer values are clamped to the | |
f37e7e3d | 2551 | range @r{[0,1]} before the current color is updated. However, color |
8925f36f AW |
2552 | components are clamped to this range before they are interpolated or |
2553 | written into a color buffer. | |
2554 | ||
bb894c9d | 2555 | @end deftypefun |
8925f36f | 2556 | |
bb894c9d | 2557 | @deftypefun void glCompileShader shader |
3c9b6116 AW |
2558 | Compiles a shader object. |
2559 | ||
8925f36f AW |
2560 | @table @asis |
2561 | @item @var{shader} | |
2562 | Specifies the shader object to be compiled. | |
2563 | ||
2564 | @end table | |
2565 | ||
8925f36f AW |
2566 | @code{glCompileShader} compiles the source code strings that have been |
2567 | stored in the shader object specified by @var{shader}. | |
2568 | ||
2569 | The compilation status will be stored as part of the shader object's | |
f37e7e3d | 2570 | state. This value will be set to @code{GL_TRUE} if the shader was |
8925f36f | 2571 | compiled without errors and is ready for use, and @code{GL_FALSE} |
f37e7e3d | 2572 | otherwise. It can be queried by calling @code{glGetShader} with |
8925f36f AW |
2573 | arguments @var{shader} and @code{GL_COMPILE_STATUS}. |
2574 | ||
2575 | Compilation of a shader can fail for a number of reasons as specified by | |
f37e7e3d | 2576 | the OpenGL Shading Language Specification. Whether or not the |
8925f36f AW |
2577 | compilation was successful, information about the compilation can be |
2578 | obtained from the shader object's information log by calling | |
2579 | @code{glGetShaderInfoLog}. | |
2580 | ||
8925f36f AW |
2581 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
2582 | generated by OpenGL. | |
2583 | ||
2584 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
2585 | object. | |
2586 | ||
2587 | @code{GL_INVALID_OPERATION} is generated if @code{glCompileShader} is | |
2588 | executed between the execution of @code{glBegin} and the corresponding | |
2589 | execution of @code{glEnd}. | |
2590 | ||
bb894c9d | 2591 | @end deftypefun |
8925f36f | 2592 | |
bb894c9d | 2593 | @deftypefun void glCompressedTexImage1D target level internalformat width border imageSize data |
3c9b6116 AW |
2594 | Specify a one-dimensional texture image in a compressed format. |
2595 | ||
8925f36f AW |
2596 | @table @asis |
2597 | @item @var{target} | |
f37e7e3d | 2598 | Specifies the target texture. Must be @code{GL_TEXTURE_1D} or |
8925f36f AW |
2599 | @code{GL_PROXY_TEXTURE_1D}. |
2600 | ||
2601 | @item @var{level} | |
f37e7e3d | 2602 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
2603 | Level @var{n} is the @var{n}th mipmap reduction image. |
2604 | ||
2605 | @item @var{internalformat} | |
2606 | Specifies the format of the compressed image data stored at address | |
2607 | @var{data}. | |
2608 | ||
2609 | @item @var{width} | |
f37e7e3d | 2610 | Specifies the width of the texture image including the border if any. If |
8925f36f | 2611 | the GL version does not support non-power-of-two sizes, this value must |
f37e7e3d | 2612 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 AW |
2613 | implementations support texture images that are at least 64 texels wide. |
2614 | The height of the 1D texture image is 1. | |
8925f36f AW |
2615 | |
2616 | @item @var{border} | |
f37e7e3d | 2617 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
2618 | |
2619 | @item @var{imageSize} | |
2620 | Specifies the number of unsigned bytes of image data starting at the | |
2621 | address specified by @var{data}. | |
2622 | ||
2623 | @item @var{data} | |
2624 | Specifies a pointer to the compressed image data in memory. | |
2625 | ||
2626 | @end table | |
2627 | ||
8925f36f | 2628 | Texturing maps a portion of a specified texture image onto each |
f37e7e3d | 2629 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
2630 | disable one-dimensional texturing, call @code{glEnable} and |
2631 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
2632 | ||
2633 | @code{glCompressedTexImage1D} loads a previously defined, and retrieved, | |
2634 | compressed one-dimensional texture image if @var{target} is | |
2635 | @code{GL_TEXTURE_1D} (see @code{glTexImage1D}). | |
2636 | ||
2637 | If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from | |
2638 | @var{data}, but all of the texture image state is recalculated, checked | |
2639 | for consistency, and checked against the implementation's capabilities. | |
2640 | If the implementation cannot handle a texture of the requested texture | |
2641 | size, it sets all of the image state to 0, but does not generate an | |
f37e7e3d | 2642 | error (see @code{glGetError}). To query for an entire mipmap array, use |
8925f36f AW |
2643 | an image array level greater than or equal to 1. |
2644 | ||
2645 | @var{internalformat} must be extension-specified compressed-texture | |
f37e7e3d | 2646 | format. When a texture is loaded with @code{glTexImage1D} using a |
8925f36f | 2647 | generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}) the |
f37e7e3d | 2648 | GL selects from one of its extensions supporting compressed textures. In |
8925f36f AW |
2649 | order to load the compressed texture image using |
2650 | @code{glCompressedTexImage1D}, query the compressed texture image's size | |
2651 | and format using @code{glGetTexLevelParameter}. | |
2652 | ||
2653 | If a non-zero named buffer object is bound to the | |
2654 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2655 | texture image is specified, @var{data} is treated as a byte offset into | |
2656 | the buffer object's data store. | |
2657 | ||
8925f36f AW |
2658 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of |
2659 | the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2660 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2661 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or | |
2662 | @code{GL_COMPRESSED_RGBA}. | |
2663 | ||
2664 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2665 | consistent with the format, dimensions, and contents of the specified | |
2666 | compressed image data. | |
2667 | ||
2668 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2669 | not supported by the specific compressed internal format as specified in | |
2670 | the specific texture compression extension. | |
2671 | ||
2672 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2673 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2674 | object's data store is currently mapped. | |
2675 | ||
2676 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2677 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2678 | would be unpacked from the buffer object such that the memory reads | |
2679 | required would exceed the data store size. | |
2680 | ||
2681 | @code{GL_INVALID_OPERATION} is generated if | |
2682 | @code{glCompressedTexImage1D} is executed between the execution of | |
2683 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2684 | ||
2685 | Undefined results, including abnormal program termination, are generated | |
2686 | if @var{data} is not encoded in a manner consistent with the extension | |
2687 | specification defining the internal compression format. | |
2688 | ||
bb894c9d | 2689 | @end deftypefun |
8925f36f | 2690 | |
bb894c9d | 2691 | @deftypefun void glCompressedTexImage2D target level internalformat width height border imageSize data |
3c9b6116 AW |
2692 | Specify a two-dimensional texture image in a compressed format. |
2693 | ||
8925f36f AW |
2694 | @table @asis |
2695 | @item @var{target} | |
f37e7e3d | 2696 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, |
8925f36f AW |
2697 | @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, |
2698 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
2699 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
2700 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
2701 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
2702 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
2703 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
2704 | ||
2705 | @item @var{level} | |
f37e7e3d | 2706 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
2707 | Level @var{n} is the @var{n}th mipmap reduction image. |
2708 | ||
2709 | @item @var{internalformat} | |
2710 | Specifies the format of the compressed image data stored at address | |
2711 | @var{data}. | |
2712 | ||
2713 | @item @var{width} | |
f37e7e3d | 2714 | Specifies the width of the texture image including the border if any. If |
8925f36f | 2715 | the GL version does not support non-power-of-two sizes, this value must |
f37e7e3d | 2716 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 AW |
2717 | implementations support 2D texture images that are at least 64 texels |
2718 | wide and cube-mapped texture images that are at least 16 texels wide. | |
8925f36f AW |
2719 | |
2720 | @item @var{height} | |
2721 | Specifies the height of the texture image including the border if any. | |
2722 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 | 2723 | must be Must be @r{2^@var{n}+2(@var{border},)} for some integer |
f37e7e3d | 2724 | @r{@var{n}}. All implementations support 2D texture images that are at |
3c9b6116 AW |
2725 | least 64 texels high and cube-mapped texture images that are at least 16 |
2726 | texels high. | |
8925f36f AW |
2727 | |
2728 | @item @var{border} | |
f37e7e3d | 2729 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
2730 | |
2731 | @item @var{imageSize} | |
2732 | Specifies the number of unsigned bytes of image data starting at the | |
2733 | address specified by @var{data}. | |
2734 | ||
2735 | @item @var{data} | |
2736 | Specifies a pointer to the compressed image data in memory. | |
2737 | ||
2738 | @end table | |
2739 | ||
8925f36f | 2740 | Texturing maps a portion of a specified texture image onto each |
f37e7e3d | 2741 | graphical primitive for which texturing is enabled. To enable and |
8925f36f | 2742 | disable two-dimensional texturing, call @code{glEnable} and |
f37e7e3d | 2743 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and |
8925f36f AW |
2744 | disable texturing using cube-mapped textures, call @code{glEnable} and |
2745 | @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}. | |
2746 | ||
2747 | @code{glCompressedTexImage2D} loads a previously defined, and retrieved, | |
2748 | compressed two-dimensional texture image if @var{target} is | |
2749 | @code{GL_TEXTURE_2D} (see @code{glTexImage2D}). | |
2750 | ||
2751 | If @var{target} is @code{GL_PROXY_TEXTURE_2D}, no data is read from | |
2752 | @var{data}, but all of the texture image state is recalculated, checked | |
2753 | for consistency, and checked against the implementation's capabilities. | |
2754 | If the implementation cannot handle a texture of the requested texture | |
2755 | size, it sets all of the image state to 0, but does not generate an | |
f37e7e3d | 2756 | error (see @code{glGetError}). To query for an entire mipmap array, use |
8925f36f AW |
2757 | an image array level greater than or equal to 1. |
2758 | ||
2759 | @var{internalformat} must be an extension-specified compressed-texture | |
f37e7e3d | 2760 | format. When a texture is loaded with @code{glTexImage2D} using a |
8925f36f | 2761 | generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the |
f37e7e3d | 2762 | GL selects from one of its extensions supporting compressed textures. In |
8925f36f AW |
2763 | order to load the compressed texture image using |
2764 | @code{glCompressedTexImage2D}, query the compressed texture image's size | |
2765 | and format using @code{glGetTexLevelParameter}. | |
2766 | ||
2767 | If a non-zero named buffer object is bound to the | |
2768 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2769 | texture image is specified, @var{data} is treated as a byte offset into | |
2770 | the buffer object's data store. | |
2771 | ||
8925f36f AW |
2772 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of |
2773 | the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2774 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2775 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or | |
2776 | @code{GL_COMPRESSED_RGBA}. | |
2777 | ||
2778 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2779 | consistent with the format, dimensions, and contents of the specified | |
2780 | compressed image data. | |
2781 | ||
2782 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2783 | not supported by the specific compressed internal format as specified in | |
2784 | the specific texture compression extension. | |
2785 | ||
2786 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2787 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2788 | object's data store is currently mapped. | |
2789 | ||
2790 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2791 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2792 | would be unpacked from the buffer object such that the memory reads | |
2793 | required would exceed the data store size. | |
2794 | ||
2795 | @code{GL_INVALID_OPERATION} is generated if | |
2796 | @code{glCompressedTexImage2D} is executed between the execution of | |
2797 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2798 | ||
2799 | Undefined results, including abnormal program termination, are generated | |
2800 | if @var{data} is not encoded in a manner consistent with the extension | |
2801 | specification defining the internal compression format. | |
2802 | ||
bb894c9d | 2803 | @end deftypefun |
8925f36f | 2804 | |
bb894c9d | 2805 | @deftypefun void glCompressedTexImage3D target level internalformat width height depth border imageSize data |
3c9b6116 AW |
2806 | Specify a three-dimensional texture image in a compressed format. |
2807 | ||
8925f36f AW |
2808 | @table @asis |
2809 | @item @var{target} | |
f37e7e3d | 2810 | Specifies the target texture. Must be @code{GL_TEXTURE_3D} or |
8925f36f AW |
2811 | @code{GL_PROXY_TEXTURE_3D}. |
2812 | ||
2813 | @item @var{level} | |
f37e7e3d | 2814 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
2815 | Level @var{n} is the @var{n}th mipmap reduction image. |
2816 | ||
2817 | @item @var{internalformat} | |
2818 | Specifies the format of the compressed image data stored at address | |
2819 | @var{data}. | |
2820 | ||
2821 | @item @var{width} | |
f37e7e3d | 2822 | Specifies the width of the texture image including the border if any. If |
8925f36f | 2823 | the GL version does not support non-power-of-two sizes, this value must |
f37e7e3d | 2824 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 AW |
2825 | implementations support 3D texture images that are at least 16 texels |
2826 | wide. | |
8925f36f AW |
2827 | |
2828 | @item @var{height} | |
2829 | Specifies the height of the texture image including the border if any. | |
2830 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
2831 | must be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. |
2832 | All implementations support 3D texture images that are at least 16 | |
2833 | texels high. | |
8925f36f AW |
2834 | |
2835 | @item @var{depth} | |
f37e7e3d | 2836 | Specifies the depth of the texture image including the border if any. If |
8925f36f | 2837 | the GL version does not support non-power-of-two sizes, this value must |
f37e7e3d | 2838 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 AW |
2839 | implementations support 3D texture images that are at least 16 texels |
2840 | deep. | |
8925f36f AW |
2841 | |
2842 | @item @var{border} | |
f37e7e3d | 2843 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
2844 | |
2845 | @item @var{imageSize} | |
2846 | Specifies the number of unsigned bytes of image data starting at the | |
2847 | address specified by @var{data}. | |
2848 | ||
2849 | @item @var{data} | |
2850 | Specifies a pointer to the compressed image data in memory. | |
2851 | ||
2852 | @end table | |
2853 | ||
8925f36f | 2854 | Texturing maps a portion of a specified texture image onto each |
f37e7e3d | 2855 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
2856 | disable three-dimensional texturing, call @code{glEnable} and |
2857 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
2858 | ||
2859 | @code{glCompressedTexImage3D} loads a previously defined, and retrieved, | |
2860 | compressed three-dimensional texture image if @var{target} is | |
2861 | @code{GL_TEXTURE_3D} (see @code{glTexImage3D}). | |
2862 | ||
2863 | If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from | |
2864 | @var{data}, but all of the texture image state is recalculated, checked | |
2865 | for consistency, and checked against the implementation's capabilities. | |
2866 | If the implementation cannot handle a texture of the requested texture | |
2867 | size, it sets all of the image state to 0, but does not generate an | |
f37e7e3d | 2868 | error (see @code{glGetError}). To query for an entire mipmap array, use |
8925f36f AW |
2869 | an image array level greater than or equal to 1. |
2870 | ||
2871 | @var{internalformat} must be an extension-specified compressed-texture | |
f37e7e3d | 2872 | format. When a texture is loaded with @code{glTexImage2D} using a |
8925f36f | 2873 | generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the |
f37e7e3d | 2874 | GL selects from one of its extensions supporting compressed textures. In |
8925f36f AW |
2875 | order to load the compressed texture image using |
2876 | @code{glCompressedTexImage3D}, query the compressed texture image's size | |
2877 | and format using @code{glGetTexLevelParameter}. | |
2878 | ||
2879 | If a non-zero named buffer object is bound to the | |
2880 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2881 | texture image is specified, @var{data} is treated as a byte offset into | |
2882 | the buffer object's data store. | |
2883 | ||
8925f36f AW |
2884 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of |
2885 | the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2886 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2887 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or | |
2888 | @code{GL_COMPRESSED_RGBA}. | |
2889 | ||
2890 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2891 | consistent with the format, dimensions, and contents of the specified | |
2892 | compressed image data. | |
2893 | ||
2894 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2895 | not supported by the specific compressed internal format as specified in | |
2896 | the specific texture compression extension. | |
2897 | ||
2898 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2899 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2900 | object's data store is currently mapped. | |
2901 | ||
2902 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2903 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2904 | would be unpacked from the buffer object such that the memory reads | |
2905 | required would exceed the data store size. | |
2906 | ||
2907 | @code{GL_INVALID_OPERATION} is generated if | |
2908 | @code{glCompressedTexImage3D} is executed between the execution of | |
2909 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2910 | ||
2911 | Undefined results, including abnormal program termination, are generated | |
2912 | if @var{data} is not encoded in a manner consistent with the extension | |
2913 | specification defining the internal compression format. | |
2914 | ||
bb894c9d | 2915 | @end deftypefun |
8925f36f | 2916 | |
bb894c9d | 2917 | @deftypefun void glCompressedTexSubImage1D target level xoffset width format imageSize data |
3c9b6116 AW |
2918 | Specify a one-dimensional texture subimage in a compressed format. |
2919 | ||
8925f36f AW |
2920 | @table @asis |
2921 | @item @var{target} | |
f37e7e3d | 2922 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. |
8925f36f AW |
2923 | |
2924 | @item @var{level} | |
f37e7e3d | 2925 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
2926 | Level @var{n} is the @var{n}th mipmap reduction image. |
2927 | ||
2928 | @item @var{xoffset} | |
2929 | Specifies a texel offset in the x direction within the texture array. | |
2930 | ||
2931 | @item @var{width} | |
2932 | Specifies the width of the texture subimage. | |
2933 | ||
2934 | @item @var{format} | |
2935 | Specifies the format of the compressed image data stored at address | |
2936 | @var{data}. | |
2937 | ||
2938 | @item @var{imageSize} | |
2939 | Specifies the number of unsigned bytes of image data starting at the | |
2940 | address specified by @var{data}. | |
2941 | ||
2942 | @item @var{data} | |
2943 | Specifies a pointer to the compressed image data in memory. | |
2944 | ||
2945 | @end table | |
2946 | ||
8925f36f | 2947 | Texturing maps a portion of a specified texture image onto each |
f37e7e3d | 2948 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
2949 | disable one-dimensional texturing, call @code{glEnable} and |
2950 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
2951 | ||
2952 | @code{glCompressedTexSubImage1D} redefines a contiguous subregion of an | |
f37e7e3d | 2953 | existing one-dimensional texture image. The texels referenced by |
8925f36f | 2954 | @var{data} replace the portion of the existing texture array with x |
3c9b6116 | 2955 | indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive. |
8925f36f | 2956 | This region may not include any texels outside the range of the texture |
f37e7e3d | 2957 | array as it was originally specified. It is not an error to specify a |
8925f36f AW |
2958 | subtexture with width of 0, but such a specification has no effect. |
2959 | ||
2960 | @var{format} must be an extension-specified compressed-texture format. | |
2961 | The @var{format} of the compressed texture image is selected by the GL | |
2962 | implementation that compressed it (see @code{glTexImage1D}), and should | |
2963 | be queried at the time the texture was compressed with | |
2964 | @code{glGetTexLevelParameter}. | |
2965 | ||
2966 | If a non-zero named buffer object is bound to the | |
2967 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2968 | texture image is specified, @var{data} is treated as a byte offset into | |
2969 | the buffer object's data store. | |
2970 | ||
8925f36f AW |
2971 | @code{GL_INVALID_ENUM} is generated if @var{format} is one of these |
2972 | generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2973 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2974 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
2975 | @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE}, | |
2976 | @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB}, | |
2977 | @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}. | |
2978 | ||
2979 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2980 | consistent with the format, dimensions, and contents of the specified | |
2981 | compressed image data. | |
2982 | ||
2983 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2984 | not supported by the specific compressed internal format as specified in | |
2985 | the specific texture compression extension. | |
2986 | ||
2987 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2988 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2989 | object's data store is currently mapped. | |
2990 | ||
2991 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2992 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2993 | would be unpacked from the buffer object such that the memory reads | |
2994 | required would exceed the data store size. | |
2995 | ||
2996 | @code{GL_INVALID_OPERATION} is generated if | |
2997 | @code{glCompressedTexSubImage1D} is executed between the execution of | |
2998 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2999 | ||
3000 | Undefined results, including abnormal program termination, are generated | |
3001 | if @var{data} is not encoded in a manner consistent with the extension | |
3002 | specification defining the internal compression format. | |
3003 | ||
bb894c9d | 3004 | @end deftypefun |
8925f36f | 3005 | |
bb894c9d | 3006 | @deftypefun void glCompressedTexSubImage2D target level xoffset yoffset width height format imageSize data |
3c9b6116 AW |
3007 | Specify a two-dimensional texture subimage in a compressed format. |
3008 | ||
8925f36f AW |
3009 | @table @asis |
3010 | @item @var{target} | |
f37e7e3d | 3011 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, |
8925f36f AW |
3012 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, |
3013 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
3014 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
3015 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
3016 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
3017 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
3018 | ||
3019 | @item @var{level} | |
f37e7e3d | 3020 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
3021 | Level @var{n} is the @var{n}th mipmap reduction image. |
3022 | ||
3023 | @item @var{xoffset} | |
3024 | Specifies a texel offset in the x direction within the texture array. | |
3025 | ||
3026 | @item @var{yoffset} | |
3027 | Specifies a texel offset in the y direction within the texture array. | |
3028 | ||
3029 | @item @var{width} | |
3030 | Specifies the width of the texture subimage. | |
3031 | ||
3032 | @item @var{height} | |
3033 | Specifies the height of the texture subimage. | |
3034 | ||
3035 | @item @var{format} | |
3036 | Specifies the format of the compressed image data stored at address | |
3037 | @var{data}. | |
3038 | ||
3039 | @item @var{imageSize} | |
3040 | Specifies the number of unsigned bytes of image data starting at the | |
3041 | address specified by @var{data}. | |
3042 | ||
3043 | @item @var{data} | |
3044 | Specifies a pointer to the compressed image data in memory. | |
3045 | ||
3046 | @end table | |
3047 | ||
8925f36f | 3048 | Texturing maps a portion of a specified texture image onto each |
f37e7e3d | 3049 | graphical primitive for which texturing is enabled. To enable and |
8925f36f | 3050 | disable two-dimensional texturing, call @code{glEnable} and |
f37e7e3d | 3051 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and |
8925f36f AW |
3052 | disable texturing using cube-mapped texture, call @code{glEnable} and |
3053 | @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}. | |
3054 | ||
3055 | @code{glCompressedTexSubImage2D} redefines a contiguous subregion of an | |
f37e7e3d | 3056 | existing two-dimensional texture image. The texels referenced by |
8925f36f | 3057 | @var{data} replace the portion of the existing texture array with x |
3c9b6116 AW |
3058 | indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y |
3059 | indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive. | |
3060 | This region may not include any texels outside the range of the texture | |
f37e7e3d | 3061 | array as it was originally specified. It is not an error to specify a |
3c9b6116 | 3062 | subtexture with width of 0, but such a specification has no effect. |
8925f36f AW |
3063 | |
3064 | @var{format} must be an extension-specified compressed-texture format. | |
3065 | The @var{format} of the compressed texture image is selected by the GL | |
3066 | implementation that compressed it (see @code{glTexImage2D}) and should | |
3067 | be queried at the time the texture was compressed with | |
3068 | @code{glGetTexLevelParameter}. | |
3069 | ||
3070 | If a non-zero named buffer object is bound to the | |
3071 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3072 | texture image is specified, @var{data} is treated as a byte offset into | |
3073 | the buffer object's data store. | |
3074 | ||
8925f36f AW |
3075 | @code{GL_INVALID_ENUM} is generated if @var{format} is one of these |
3076 | generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
3077 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
3078 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
3079 | @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE}, | |
3080 | @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB}, | |
3081 | @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}. | |
3082 | ||
3083 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
3084 | consistent with the format, dimensions, and contents of the specified | |
3085 | compressed image data. | |
3086 | ||
3087 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
3088 | not supported by the specific compressed internal format as specified in | |
3089 | the specific texture compression extension. | |
3090 | ||
3091 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3092 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3093 | object's data store is currently mapped. | |
3094 | ||
3095 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3096 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3097 | would be unpacked from the buffer object such that the memory reads | |
3098 | required would exceed the data store size. | |
3099 | ||
3100 | @code{GL_INVALID_OPERATION} is generated if | |
3101 | @code{glCompressedTexSubImage2D} is executed between the execution of | |
3102 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3103 | ||
3104 | Undefined results, including abnormal program termination, are generated | |
3105 | if @var{data} is not encoded in a manner consistent with the extension | |
3106 | specification defining the internal compression format. | |
3107 | ||
bb894c9d | 3108 | @end deftypefun |
8925f36f | 3109 | |
bb894c9d | 3110 | @deftypefun void glCompressedTexSubImage3D target level xoffset yoffset zoffset width height depth format imageSize data |
3c9b6116 AW |
3111 | Specify a three-dimensional texture subimage in a compressed format. |
3112 | ||
8925f36f AW |
3113 | @table @asis |
3114 | @item @var{target} | |
f37e7e3d | 3115 | Specifies the target texture. Must be @code{GL_TEXTURE_3D}. |
8925f36f AW |
3116 | |
3117 | @item @var{level} | |
f37e7e3d | 3118 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
3119 | Level @var{n} is the @var{n}th mipmap reduction image. |
3120 | ||
3121 | @item @var{xoffset} | |
3122 | Specifies a texel offset in the x direction within the texture array. | |
3123 | ||
3124 | @item @var{yoffset} | |
3125 | Specifies a texel offset in the y direction within the texture array. | |
3126 | ||
3127 | @item @var{width} | |
3128 | Specifies the width of the texture subimage. | |
3129 | ||
3130 | @item @var{height} | |
3131 | Specifies the height of the texture subimage. | |
3132 | ||
3133 | @item @var{depth} | |
3134 | Specifies the depth of the texture subimage. | |
3135 | ||
3136 | @item @var{format} | |
3137 | Specifies the format of the compressed image data stored at address | |
3138 | @var{data}. | |
3139 | ||
3140 | @item @var{imageSize} | |
3141 | Specifies the number of unsigned bytes of image data starting at the | |
3142 | address specified by @var{data}. | |
3143 | ||
3144 | @item @var{data} | |
3145 | Specifies a pointer to the compressed image data in memory. | |
3146 | ||
3147 | @end table | |
3148 | ||
8925f36f | 3149 | Texturing maps a portion of a specified texture image onto each |
f37e7e3d | 3150 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
3151 | disable three-dimensional texturing, call @code{glEnable} and |
3152 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
3153 | ||
3154 | @code{glCompressedTexSubImage3D} redefines a contiguous subregion of an | |
f37e7e3d | 3155 | existing three-dimensional texture image. The texels referenced by |
8925f36f | 3156 | @var{data} replace the portion of the existing texture array with x |
3c9b6116 AW |
3157 | indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y |
3158 | indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, and the z | |
3159 | indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive. | |
8925f36f | 3160 | This region may not include any texels outside the range of the texture |
f37e7e3d | 3161 | array as it was originally specified. It is not an error to specify a |
8925f36f AW |
3162 | subtexture with width of 0, but such a specification has no effect. |
3163 | ||
3164 | @var{format} must be an extension-specified compressed-texture format. | |
3165 | The @var{format} of the compressed texture image is selected by the GL | |
3166 | implementation that compressed it (see @code{glTexImage3D}) and should | |
3167 | be queried at the time the texture was compressed with | |
3168 | @code{glGetTexLevelParameter}. | |
3169 | ||
3170 | If a non-zero named buffer object is bound to the | |
3171 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3172 | texture image is specified, @var{data} is treated as a byte offset into | |
3173 | the buffer object's data store. | |
3174 | ||
8925f36f AW |
3175 | @code{GL_INVALID_ENUM} is generated if @var{format} is one of these |
3176 | generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
3177 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
3178 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
3179 | @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE}, | |
3180 | @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB}, | |
3181 | @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}. | |
3182 | ||
3183 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
3184 | consistent with the format, dimensions, and contents of the specified | |
3185 | compressed image data. | |
3186 | ||
3187 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
3188 | not supported by the specific compressed internal format as specified in | |
3189 | the specific texture compression extension. | |
3190 | ||
3191 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3192 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3193 | object's data store is currently mapped. | |
3194 | ||
3195 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3196 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3197 | would be unpacked from the buffer object such that the memory reads | |
3198 | required would exceed the data store size. | |
3199 | ||
3200 | @code{GL_INVALID_OPERATION} is generated if | |
3201 | @code{glCompressedTexSubImage3D} is executed between the execution of | |
3202 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3203 | ||
3204 | Undefined results, including abnormal program termination, are generated | |
3205 | if @var{data} is not encoded in a manner consistent with the extension | |
3206 | specification defining the internal compression format. | |
3207 | ||
bb894c9d | 3208 | @end deftypefun |
8925f36f | 3209 | |
bb894c9d | 3210 | @deftypefun void glConvolutionFilter1D target internalformat width format type data |
3c9b6116 AW |
3211 | Define a one-dimensional convolution filter. |
3212 | ||
8925f36f AW |
3213 | @table @asis |
3214 | @item @var{target} | |
3215 | Must be @code{GL_CONVOLUTION_1D}. | |
3216 | ||
3217 | @item @var{internalformat} | |
f37e7e3d | 3218 | The internal format of the convolution filter kernel. The allowable |
8925f36f AW |
3219 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, |
3220 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3221 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3222 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3223 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3224 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3225 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3226 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3227 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3228 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3229 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3230 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3231 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3232 | ||
3233 | @item @var{width} | |
3234 | The width of the pixel array referenced by @var{data}. | |
3235 | ||
3236 | @item @var{format} | |
f37e7e3d | 3237 | The format of the pixel data in @var{data}. The allowable values are |
8925f36f AW |
3238 | @code{GL_ALPHA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, |
3239 | @code{GL_INTENSITY}, @code{GL_RGB}, and @code{GL_RGBA}. | |
3240 | ||
3241 | @item @var{type} | |
f37e7e3d | 3242 | The type of the pixel data in @var{data}. Symbolic constants |
8925f36f AW |
3243 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
3244 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
3245 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
3246 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
3247 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
3248 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
3249 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
3250 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
3251 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
3252 | ||
3253 | @item @var{data} | |
3254 | Pointer to a one-dimensional array of pixel data that is processed to | |
3255 | build the convolution filter kernel. | |
3256 | ||
3257 | @end table | |
3258 | ||
8925f36f AW |
3259 | @code{glConvolutionFilter1D} builds a one-dimensional convolution filter |
3260 | kernel from an array of pixels. | |
3261 | ||
3262 | The pixel array specified by @var{width}, @var{format}, @var{type}, and | |
3263 | @var{data} is extracted from memory and processed just as if | |
3264 | @code{glDrawPixels} were called, but processing stops after the final | |
3265 | expansion to RGBA is completed. | |
3266 | ||
3267 | If a non-zero named buffer object is bound to the | |
3268 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3269 | convolution filter is specified, @var{data} is treated as a byte offset | |
3270 | into the buffer object's data store. | |
3271 | ||
3272 | The R, G, B, and A components of each pixel are next scaled by the four | |
3273 | 1D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four | |
f37e7e3d | 3274 | 1D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias |
8925f36f AW |
3275 | parameters are set by @code{glConvolutionParameter} using the |
3276 | @code{GL_CONVOLUTION_1D} target and the names | |
3277 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
f37e7e3d DH |
3278 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors |
3279 | of four values that are applied to red, green, blue, and alpha, in that | |
3280 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
3281 | during this process. | |
8925f36f AW |
3282 | |
3283 | Each pixel is then converted to the internal format specified by | |
f37e7e3d | 3284 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 3285 | of the pixel (R, G, B, and A) to the values included in the internal |
f37e7e3d | 3286 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
3287 | is as follows: |
3288 | ||
3289 | ||
3290 | ||
3291 | @table @asis | |
3292 | @item @strong{Internal Format} | |
3293 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3294 | @strong{Luminance}, @strong{Intensity} | |
3295 | ||
3296 | @item @code{GL_ALPHA} | |
3297 | , , , A , , | |
3298 | ||
3299 | @item @code{GL_LUMINANCE} | |
3300 | , , , , R , | |
3301 | ||
3302 | @item @code{GL_LUMINANCE_ALPHA} | |
3303 | , , , A , R , | |
3304 | ||
3305 | @item @code{GL_INTENSITY} | |
3306 | , , , , , R | |
3307 | ||
3308 | @item @code{GL_RGB} | |
3309 | R , G , B , , , | |
3310 | ||
3311 | @item @code{GL_RGBA} | |
3312 | R , G , B , A , , | |
3313 | ||
3314 | @end table | |
3315 | ||
3316 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3317 | the resulting pixels are stored in floating-point rather than integer | |
f37e7e3d | 3318 | format. They form a one-dimensional filter kernel image indexed with |
8925f36f | 3319 | coordinate @var{i} such that @var{i} starts at 0 and increases from left |
f37e7e3d | 3320 | to right. Kernel location @var{i} is derived from the @var{i}th pixel, |
8925f36f AW |
3321 | counting from 0. |
3322 | ||
3323 | Note that after a convolution is performed, the resulting color | |
3324 | components are also scaled by their corresponding | |
3325 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3326 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3327 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
f37e7e3d | 3328 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. |
8925f36f | 3329 | |
8925f36f AW |
3330 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3331 | @code{GL_CONVOLUTION_1D}. | |
3332 | ||
3333 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3334 | of the allowable values. | |
3335 | ||
3336 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
3337 | allowable values. | |
3338 | ||
3339 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
3340 | allowable values. | |
3341 | ||
3342 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
f37e7e3d DH |
3343 | greater than the maximum supported value. This value may be queried with |
3344 | @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_1D} | |
3345 | and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
8925f36f AW |
3346 | |
3347 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
3348 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
3349 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
3350 | and @var{type} is not @code{GL_RGB}. | |
3351 | ||
3352 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
3353 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
3354 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
3355 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
3356 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
3357 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{type} is neither | |
3358 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
3359 | ||
3360 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3361 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3362 | object's data store is currently mapped. | |
3363 | ||
3364 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3365 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3366 | would be unpacked from the buffer object such that the memory reads | |
3367 | required would exceed the data store size. | |
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 @var{data} | |
3371 | is not evenly divisible into the number of bytes needed to store in | |
3372 | memory a datum indicated by @var{type}. | |
3373 | ||
3374 | @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter1D} | |
3375 | is executed between the execution of @code{glBegin} and the | |
3376 | corresponding execution of @code{glEnd}. | |
3377 | ||
bb894c9d | 3378 | @end deftypefun |
8925f36f | 3379 | |
bb894c9d | 3380 | @deftypefun void glConvolutionFilter2D target internalformat width height format type data |
3c9b6116 AW |
3381 | Define a two-dimensional convolution filter. |
3382 | ||
8925f36f AW |
3383 | @table @asis |
3384 | @item @var{target} | |
3385 | Must be @code{GL_CONVOLUTION_2D}. | |
3386 | ||
3387 | @item @var{internalformat} | |
f37e7e3d | 3388 | The internal format of the convolution filter kernel. The allowable |
8925f36f AW |
3389 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, |
3390 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3391 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3392 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3393 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3394 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3395 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3396 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3397 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3398 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3399 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3400 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3401 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3402 | ||
3403 | @item @var{width} | |
3404 | The width of the pixel array referenced by @var{data}. | |
3405 | ||
3406 | @item @var{height} | |
3407 | The height of the pixel array referenced by @var{data}. | |
3408 | ||
3409 | @item @var{format} | |
f37e7e3d | 3410 | The format of the pixel data in @var{data}. The allowable values are |
8925f36f AW |
3411 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
3412 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
3413 | @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}. | |
3414 | ||
3415 | @item @var{type} | |
f37e7e3d | 3416 | The type of the pixel data in @var{data}. Symbolic constants |
8925f36f AW |
3417 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
3418 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
3419 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
3420 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
3421 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
3422 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
3423 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
3424 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
3425 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
3426 | ||
3427 | @item @var{data} | |
3428 | Pointer to a two-dimensional array of pixel data that is processed to | |
3429 | build the convolution filter kernel. | |
3430 | ||
3431 | @end table | |
3432 | ||
8925f36f AW |
3433 | @code{glConvolutionFilter2D} builds a two-dimensional convolution filter |
3434 | kernel from an array of pixels. | |
3435 | ||
3436 | The pixel array specified by @var{width}, @var{height}, @var{format}, | |
3437 | @var{type}, and @var{data} is extracted from memory and processed just | |
3438 | as if @code{glDrawPixels} were called, but processing stops after the | |
3439 | final expansion to RGBA is completed. | |
3440 | ||
3441 | If a non-zero named buffer object is bound to the | |
3442 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3443 | convolution filter is specified, @var{data} is treated as a byte offset | |
3444 | into the buffer object's data store. | |
3445 | ||
3446 | The R, G, B, and A components of each pixel are next scaled by the four | |
3447 | 2D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four | |
f37e7e3d | 3448 | 2D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias |
8925f36f AW |
3449 | parameters are set by @code{glConvolutionParameter} using the |
3450 | @code{GL_CONVOLUTION_2D} target and the names | |
3451 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
f37e7e3d DH |
3452 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors |
3453 | of four values that are applied to red, green, blue, and alpha, in that | |
3454 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
3455 | during this process. | |
8925f36f AW |
3456 | |
3457 | Each pixel is then converted to the internal format specified by | |
f37e7e3d | 3458 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 3459 | of the pixel (R, G, B, and A) to the values included in the internal |
f37e7e3d | 3460 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
3461 | is as follows: |
3462 | ||
3463 | ||
3464 | ||
3465 | @table @asis | |
3466 | @item @strong{Internal Format} | |
3467 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3468 | @strong{Luminance}, @strong{Intensity} | |
3469 | ||
3470 | @item @code{GL_ALPHA} | |
3471 | , , , A , , | |
3472 | ||
3473 | @item @code{GL_LUMINANCE} | |
3474 | , , , , R , | |
3475 | ||
3476 | @item @code{GL_LUMINANCE_ALPHA} | |
3477 | , , , A , R , | |
3478 | ||
3479 | @item @code{GL_INTENSITY} | |
3480 | , , , , , R | |
3481 | ||
3482 | @item @code{GL_RGB} | |
3483 | R , G , B , , , | |
3484 | ||
3485 | @item @code{GL_RGBA} | |
3486 | R , G , B , A , , | |
3487 | ||
3488 | @end table | |
3489 | ||
3490 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3491 | the resulting pixels are stored in floating-point rather than integer | |
f37e7e3d | 3492 | format. They form a two-dimensional filter kernel image indexed with |
8925f36f AW |
3493 | coordinates @var{i} and @var{j} such that @var{i} starts at zero and |
3494 | increases from left to right, and @var{j} starts at zero and increases | |
f37e7e3d | 3495 | from bottom to top. Kernel location @var{i,j} is derived from the |
8925f36f AW |
3496 | @var{N}th pixel, where @var{N} is @var{i}+@var{j}*@var{width}. |
3497 | ||
3498 | Note that after a convolution is performed, the resulting color | |
3499 | components are also scaled by their corresponding | |
3500 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3501 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3502 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
f37e7e3d | 3503 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. |
8925f36f | 3504 | |
8925f36f AW |
3505 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3506 | @code{GL_CONVOLUTION_2D}. | |
3507 | ||
3508 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3509 | of the allowable values. | |
3510 | ||
3511 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
3512 | allowable values. | |
3513 | ||
3514 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
3515 | allowable values. | |
3516 | ||
3517 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
f37e7e3d DH |
3518 | greater than the maximum supported value. This value may be queried with |
3519 | @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_2D} | |
3520 | and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
8925f36f AW |
3521 | |
3522 | @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero | |
f37e7e3d | 3523 | or greater than the maximum supported value. This value may be queried |
8925f36f AW |
3524 | with @code{glGetConvolutionParameter} using target |
3525 | @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
3526 | ||
3527 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
3528 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
3529 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
3530 | and @var{format} is not @code{GL_RGB}. | |
3531 | ||
3532 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
3533 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
3534 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
3535 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
3536 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
3537 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
3538 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
3539 | ||
3540 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3541 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3542 | object's data store is currently mapped. | |
3543 | ||
3544 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3545 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3546 | would be unpacked from the buffer object such that the memory reads | |
3547 | required would exceed the data store size. | |
3548 | ||
3549 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3550 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
3551 | is not evenly divisible into the number of bytes needed to store in | |
3552 | memory a datum indicated by @var{type}. | |
3553 | ||
3554 | @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter2D} | |
3555 | is executed between the execution of @code{glBegin} and the | |
3556 | corresponding execution of @code{glEnd}. | |
3557 | ||
bb894c9d | 3558 | @end deftypefun |
8925f36f | 3559 | |
bb894c9d AW |
3560 | @deftypefun void glConvolutionParameterf target pname params |
3561 | @deftypefunx void glConvolutionParameteri target pname params | |
d172eed9 AW |
3562 | @deftypefunx void glConvolutionParameterfv target pname params |
3563 | @deftypefunx void glConvolutionParameteriv target pname params | |
3c9b6116 AW |
3564 | Set convolution parameters. |
3565 | ||
8925f36f AW |
3566 | @table @asis |
3567 | @item @var{target} | |
f37e7e3d | 3568 | The target for the convolution parameter. Must be one of |
8925f36f AW |
3569 | @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or |
3570 | @code{GL_SEPARABLE_2D}. | |
3571 | ||
3572 | @item @var{pname} | |
f37e7e3d | 3573 | The parameter to be set. Must be @code{GL_CONVOLUTION_BORDER_MODE}. |
8925f36f AW |
3574 | |
3575 | @item @var{params} | |
f37e7e3d | 3576 | The parameter value. Must be one of @code{GL_REDUCE}, |
8925f36f AW |
3577 | @code{GL_CONSTANT_BORDER}, @code{GL_REPLICATE_BORDER}. |
3578 | ||
3579 | ||
3580 | ||
3581 | @end table | |
3582 | ||
8925f36f AW |
3583 | @code{glConvolutionParameter} sets the value of a convolution parameter. |
3584 | ||
3585 | @var{target} selects the convolution filter to be affected: | |
3586 | @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or | |
3587 | @code{GL_SEPARABLE_2D} for the 1D, 2D, or separable 2D filter, | |
3588 | respectively. | |
3589 | ||
3590 | @var{pname} selects the parameter to be changed. | |
3591 | @code{GL_CONVOLUTION_FILTER_SCALE} and @code{GL_CONVOLUTION_FILTER_BIAS} | |
3592 | affect the definition of the convolution filter kernel; see | |
3593 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and | |
f37e7e3d DH |
3594 | @code{glSeparableFilter2D} for details. In these cases, @var{params}v is |
3595 | an array of four values to be applied to red, green, blue, and alpha | |
3596 | values, respectively. The initial value for | |
8925f36f AW |
3597 | @code{GL_CONVOLUTION_FILTER_SCALE} is (1, 1, 1, 1), and the initial |
3598 | value for @code{GL_CONVOLUTION_FILTER_BIAS} is (0, 0, 0, 0). | |
3599 | ||
3600 | A @var{pname} value of @code{GL_CONVOLUTION_BORDER_MODE} controls the | |
f37e7e3d | 3601 | convolution border mode. The accepted modes are: |
8925f36f AW |
3602 | |
3603 | @table @asis | |
3604 | @item @code{GL_REDUCE} | |
3605 | The image resulting from convolution is smaller than the source image. | |
3c9b6116 AW |
3606 | If the filter width is @r{@var{Wf}} and height is @r{@var{Hf}}, and the |
3607 | source image width is @r{@var{Ws}} and height is @r{@var{Hs}}, then the | |
3608 | convolved image width will be @r{@var{Ws}-@var{Wf}+1} and height will be | |
f37e7e3d DH |
3609 | @r{@var{Hs}-@var{Hf}+1}. (If this reduction would generate an image with |
3610 | zero or negative width and/or height, the output is simply null, with no | |
3611 | error generated.) The coordinates of the image resulting from | |
3c9b6116 AW |
3612 | convolution are zero through @r{@var{Ws}-@var{Wf}} in width and zero |
3613 | through @r{@var{Hs}-@var{Hf}} in height. | |
8925f36f AW |
3614 | |
3615 | @item @code{GL_CONSTANT_BORDER} | |
3616 | The image resulting from convolution is the same size as the source | |
3617 | image, and processed as if the source image were surrounded by pixels | |
3618 | with their color specified by the @code{GL_CONVOLUTION_BORDER_COLOR}. | |
3619 | ||
3620 | @item @code{GL_REPLICATE_BORDER} | |
3621 | The image resulting from convolution is the same size as the source | |
3622 | image, and processed as if the outermost pixel on the border of the | |
3623 | source image were replicated. | |
3624 | ||
3625 | @end table | |
3626 | ||
8925f36f AW |
3627 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
3628 | allowable values. | |
3629 | ||
3630 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
3631 | allowable values. | |
3632 | ||
3633 | @code{GL_INVALID_ENUM} is generated if @var{pname} is | |
3634 | @code{GL_CONVOLUTION_BORDER_MODE} and @var{params} is not one of | |
3635 | @code{GL_REDUCE}, @code{GL_CONSTANT_BORDER}, or | |
3636 | @code{GL_REPLICATE_BORDER}. | |
3637 | ||
3638 | @code{GL_INVALID_OPERATION} is generated if | |
3639 | @code{glConvolutionParameter} is executed between the execution of | |
3640 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3641 | ||
bb894c9d | 3642 | @end deftypefun |
8925f36f | 3643 | |
bb894c9d | 3644 | @deftypefun void glCopyColorSubTable target start x y width |
3c9b6116 AW |
3645 | Respecify a portion of a color table. |
3646 | ||
8925f36f AW |
3647 | @table @asis |
3648 | @item @var{target} | |
3649 | Must be one of @code{GL_COLOR_TABLE}, | |
3650 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
3651 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
3652 | ||
3653 | @item @var{start} | |
3654 | The starting index of the portion of the color table to be replaced. | |
3655 | ||
3656 | @item @var{x} | |
3657 | @itemx @var{y} | |
3658 | The window coordinates of the left corner of the row of pixels to be | |
3659 | copied. | |
3660 | ||
3661 | @item @var{width} | |
3662 | The number of table entries to replace. | |
3663 | ||
3664 | @end table | |
3665 | ||
8925f36f | 3666 | @code{glCopyColorSubTable} is used to respecify a contiguous portion of |
f37e7e3d | 3667 | a color table previously defined using @code{glColorTable}. The pixels |
8925f36f | 3668 | copied from the framebuffer replace the portion of the existing table |
f37e7e3d | 3669 | from indices @var{start} to @r{@var{start}+@var{x}-1}, inclusive. This |
3c9b6116 | 3670 | region may not include any entries outside the range of the color table, |
f37e7e3d | 3671 | as was originally specified. It is not an error to specify a subtexture |
3c9b6116 | 3672 | with width of 0, but such a specification has no effect. |
8925f36f | 3673 | |
8925f36f AW |
3674 | @code{GL_INVALID_VALUE} is generated if @var{target} is not a previously |
3675 | defined color table. | |
3676 | ||
3677 | @code{GL_INVALID_VALUE} is generated if @var{target} is not one of the | |
3678 | allowable values. | |
3679 | ||
3680 | @code{GL_INVALID_VALUE} is generated if | |
3c9b6116 | 3681 | @r{@var{start}+@var{x}>@var{width}}. |
8925f36f AW |
3682 | |
3683 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorSubTable} | |
3684 | is executed between the execution of @code{glBegin} and the | |
3685 | corresponding execution of @code{glEnd}. | |
3686 | ||
bb894c9d | 3687 | @end deftypefun |
8925f36f | 3688 | |
bb894c9d | 3689 | @deftypefun void glCopyColorTable target internalformat x y width |
3c9b6116 AW |
3690 | Copy pixels into a color table. |
3691 | ||
8925f36f AW |
3692 | @table @asis |
3693 | @item @var{target} | |
f37e7e3d | 3694 | The color table target. Must be @code{GL_COLOR_TABLE}, |
8925f36f AW |
3695 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or |
3696 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
3697 | ||
3698 | @item @var{internalformat} | |
f37e7e3d | 3699 | The internal storage format of the texture image. Must be one of the |
8925f36f AW |
3700 | following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4}, |
3701 | @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16}, | |
3702 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, | |
3703 | @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3704 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3705 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3706 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3707 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3708 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3709 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3710 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3711 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3712 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3713 | ||
3714 | @item @var{x} | |
3715 | The x coordinate of the lower-left corner of the pixel rectangle to be | |
3716 | transferred to the color table. | |
3717 | ||
3718 | @item @var{y} | |
3719 | The y coordinate of the lower-left corner of the pixel rectangle to be | |
3720 | transferred to the color table. | |
3721 | ||
3722 | @item @var{width} | |
3723 | The width of the pixel rectangle. | |
3724 | ||
3725 | @end table | |
3726 | ||
8925f36f AW |
3727 | @code{glCopyColorTable} loads a color table with pixels from the current |
3728 | @code{GL_READ_BUFFER} (rather than from main memory, as is the case for | |
3729 | @code{glColorTable}). | |
3730 | ||
3731 | The screen-aligned pixel rectangle with lower-left corner at (@var{x},\ | |
3732 | @var{y}) having width @var{width} and height 1 is loaded into the color | |
f37e7e3d | 3733 | table. If any pixels within this region are outside the window that is |
8925f36f AW |
3734 | associated with the GL context, the values obtained for those pixels are |
3735 | undefined. | |
3736 | ||
3737 | The pixels in the rectangle are processed just as if @code{glReadPixels} | |
3738 | were called, with @var{internalformat} set to RGBA, but processing stops | |
3739 | after the final conversion to RGBA. | |
3740 | ||
3741 | The four scale parameters and the four bias parameters that are defined | |
3742 | for the table are then used to scale and bias the R, G, B, and A | |
f37e7e3d | 3743 | components of each pixel. The scale and bias parameters are set by |
8925f36f AW |
3744 | calling @code{glColorTableParameter}. |
3745 | ||
f37e7e3d | 3746 | Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each |
3c9b6116 | 3747 | pixel is then converted to the internal format specified by |
f37e7e3d | 3748 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 3749 | of the pixel (R, G, B, and A) to the values included in the internal |
f37e7e3d | 3750 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
3751 | is as follows: |
3752 | ||
3753 | ||
3754 | ||
3755 | @table @asis | |
3756 | @item @strong{Internal Format} | |
3757 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3758 | @strong{Luminance}, @strong{Intensity} | |
3759 | ||
3760 | @item @code{GL_ALPHA} | |
3761 | , , , A , , | |
3762 | ||
3763 | @item @code{GL_LUMINANCE} | |
3764 | , , , , R , | |
3765 | ||
3766 | @item @code{GL_LUMINANCE_ALPHA} | |
3767 | , , , A , R , | |
3768 | ||
3769 | @item @code{GL_INTENSITY} | |
3770 | , , , , , R | |
3771 | ||
3772 | @item @code{GL_RGB} | |
3773 | R , G , B , , , | |
3774 | ||
3775 | @item @code{GL_RGBA} | |
3776 | R , G , B , A , , | |
3777 | ||
3778 | @end table | |
3779 | ||
3780 | Finally, the red, green, blue, alpha, luminance, and/or intensity | |
f37e7e3d | 3781 | components of the resulting pixels are stored in the color table. They |
8925f36f | 3782 | form a one-dimensional table with indices in the range |
3c9b6116 | 3783 | @r{[0,@var{width}-1]}. |
8925f36f AW |
3784 | |
3785 | ||
3786 | ||
8925f36f AW |
3787 | @code{GL_INVALID_ENUM} is generated when @var{target} is not one of the |
3788 | allowable values. | |
3789 | ||
3790 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero. | |
3791 | ||
3792 | @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not one | |
3793 | of the allowable values. | |
3794 | ||
3795 | @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is | |
3796 | too large to be supported by the implementation. | |
3797 | ||
3798 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorTable} is | |
3799 | executed between the execution of @code{glBegin} and the corresponding | |
3800 | execution of @code{glEnd}. | |
3801 | ||
bb894c9d | 3802 | @end deftypefun |
8925f36f | 3803 | |
bb894c9d | 3804 | @deftypefun void glCopyConvolutionFilter1D target internalformat x y width |
3c9b6116 AW |
3805 | Copy pixels into a one-dimensional convolution filter. |
3806 | ||
8925f36f AW |
3807 | @table @asis |
3808 | @item @var{target} | |
3809 | Must be @code{GL_CONVOLUTION_1D}. | |
3810 | ||
3811 | @item @var{internalformat} | |
f37e7e3d | 3812 | The internal format of the convolution filter kernel. The allowable |
8925f36f AW |
3813 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, |
3814 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3815 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3816 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3817 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3818 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3819 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3820 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3821 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3822 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3823 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3824 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3825 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3826 | ||
3827 | @item @var{x} | |
3828 | @itemx @var{y} | |
3829 | The window space coordinates of the lower-left coordinate of the pixel | |
3830 | array to copy. | |
3831 | ||
3832 | @item @var{width} | |
3833 | The width of the pixel array to copy. | |
3834 | ||
3835 | @end table | |
3836 | ||
8925f36f AW |
3837 | @code{glCopyConvolutionFilter1D} defines a one-dimensional convolution |
3838 | filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather | |
3839 | than from main memory, as is the case for @code{glConvolutionFilter1D}). | |
3840 | ||
3841 | The screen-aligned pixel rectangle with lower-left corner at (@var{x},\ | |
3842 | @var{y}), width @var{width} and height 1 is used to define the | |
f37e7e3d | 3843 | convolution filter. If any pixels within this region are outside the |
8925f36f AW |
3844 | window that is associated with the GL context, the values obtained for |
3845 | those pixels are undefined. | |
3846 | ||
3847 | The pixels in the rectangle are processed exactly as if | |
3848 | @code{glReadPixels} had been called with @var{format} set to RGBA, but | |
f37e7e3d | 3849 | the process stops just before final conversion. The R, G, B, and A |
8925f36f AW |
3850 | components of each pixel are next scaled by the four 1D |
3851 | @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 1D | |
f37e7e3d | 3852 | @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias |
8925f36f AW |
3853 | parameters are set by @code{glConvolutionParameter} using the |
3854 | @code{GL_CONVOLUTION_1D} target and the names | |
3855 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
f37e7e3d DH |
3856 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors |
3857 | of four values that are applied to red, green, blue, and alpha, in that | |
3858 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
3859 | during this process. | |
8925f36f AW |
3860 | |
3861 | Each pixel is then converted to the internal format specified by | |
f37e7e3d | 3862 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 3863 | of the pixel (R, G, B, and A) to the values included in the internal |
f37e7e3d | 3864 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
3865 | is as follows: |
3866 | ||
3867 | ||
3868 | ||
3869 | @table @asis | |
3870 | @item @strong{Internal Format} | |
3871 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3872 | @strong{Luminance}, @strong{Intensity} | |
3873 | ||
3874 | @item @code{GL_ALPHA} | |
3875 | , , , A , , | |
3876 | ||
3877 | @item @code{GL_LUMINANCE} | |
3878 | , , , , R , | |
3879 | ||
3880 | @item @code{GL_LUMINANCE_ALPHA} | |
3881 | , , , A , R , | |
3882 | ||
3883 | @item @code{GL_INTENSITY} | |
3884 | , , , , , R | |
3885 | ||
3886 | @item @code{GL_RGB} | |
3887 | R , G , B , , , | |
3888 | ||
3889 | @item @code{GL_RGBA} | |
3890 | R , G , B , A , , | |
3891 | ||
3892 | @end table | |
3893 | ||
3894 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3895 | the resulting pixels are stored in floating-point rather than integer | |
3896 | format. | |
3897 | ||
3898 | Pixel ordering is such that lower x screen coordinates correspond to | |
3899 | lower @var{i} filter image coordinates. | |
3900 | ||
3901 | Note that after a convolution is performed, the resulting color | |
3902 | components are also scaled by their corresponding | |
3903 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3904 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3905 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
f37e7e3d | 3906 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. |
8925f36f | 3907 | |
8925f36f AW |
3908 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3909 | @code{GL_CONVOLUTION_1D}. | |
3910 | ||
3911 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3912 | of the allowable values. | |
3913 | ||
3914 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
f37e7e3d DH |
3915 | greater than the maximum supported value. This value may be queried with |
3916 | @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_1D} | |
3917 | and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
8925f36f AW |
3918 | |
3919 | @code{GL_INVALID_OPERATION} is generated if | |
3920 | @code{glCopyConvolutionFilter1D} is executed between the execution of | |
3921 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3922 | ||
bb894c9d | 3923 | @end deftypefun |
8925f36f | 3924 | |
bb894c9d | 3925 | @deftypefun void glCopyConvolutionFilter2D target internalformat x y width height |
3c9b6116 AW |
3926 | Copy pixels into a two-dimensional convolution filter. |
3927 | ||
8925f36f AW |
3928 | @table @asis |
3929 | @item @var{target} | |
3930 | Must be @code{GL_CONVOLUTION_2D}. | |
3931 | ||
3932 | @item @var{internalformat} | |
f37e7e3d | 3933 | The internal format of the convolution filter kernel. The allowable |
8925f36f AW |
3934 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, |
3935 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3936 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3937 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3938 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3939 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3940 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3941 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3942 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3943 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3944 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3945 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3946 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3947 | ||
3948 | @item @var{x} | |
3949 | @itemx @var{y} | |
3950 | The window space coordinates of the lower-left coordinate of the pixel | |
3951 | array to copy. | |
3952 | ||
3953 | @item @var{width} | |
3954 | The width of the pixel array to copy. | |
3955 | ||
3956 | @item @var{height} | |
3957 | The height of the pixel array to copy. | |
3958 | ||
3959 | @end table | |
3960 | ||
8925f36f AW |
3961 | @code{glCopyConvolutionFilter2D} defines a two-dimensional convolution |
3962 | filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather | |
3963 | than from main memory, as is the case for @code{glConvolutionFilter2D}). | |
3964 | ||
3965 | The screen-aligned pixel rectangle with lower-left corner at (@var{x},\ | |
3966 | @var{y}), width @var{width} and height @var{height} is used to define | |
f37e7e3d DH |
3967 | the convolution filter. If any pixels within this region are outside the |
3968 | window that is associated with the GL context, the values obtained for | |
3969 | those pixels are undefined. | |
8925f36f AW |
3970 | |
3971 | The pixels in the rectangle are processed exactly as if | |
3972 | @code{glReadPixels} had been called with @var{format} set to RGBA, but | |
f37e7e3d | 3973 | the process stops just before final conversion. The R, G, B, and A |
8925f36f AW |
3974 | components of each pixel are next scaled by the four 2D |
3975 | @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 2D | |
f37e7e3d | 3976 | @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias |
8925f36f AW |
3977 | parameters are set by @code{glConvolutionParameter} using the |
3978 | @code{GL_CONVOLUTION_2D} target and the names | |
3979 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
f37e7e3d DH |
3980 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors |
3981 | of four values that are applied to red, green, blue, and alpha, in that | |
3982 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
3983 | during this process. | |
8925f36f AW |
3984 | |
3985 | Each pixel is then converted to the internal format specified by | |
f37e7e3d | 3986 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 3987 | of the pixel (R, G, B, and A) to the values included in the internal |
f37e7e3d | 3988 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
3989 | is as follows: |
3990 | ||
3991 | ||
3992 | ||
3993 | @table @asis | |
3994 | @item @strong{Internal Format} | |
3995 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3996 | @strong{Luminance}, @strong{Intensity} | |
3997 | ||
3998 | @item @code{GL_ALPHA} | |
3999 | , , , A , , | |
4000 | ||
4001 | @item @code{GL_LUMINANCE} | |
4002 | , , , , R , | |
4003 | ||
4004 | @item @code{GL_LUMINANCE_ALPHA} | |
4005 | , , , A , R , | |
4006 | ||
4007 | @item @code{GL_INTENSITY} | |
4008 | , , , , , R | |
4009 | ||
4010 | @item @code{GL_RGB} | |
4011 | R , G , B , , , | |
4012 | ||
4013 | @item @code{GL_RGBA} | |
4014 | R , G , B , A , , | |
4015 | ||
4016 | @end table | |
4017 | ||
4018 | The red, green, blue, alpha, luminance, and/or intensity components of | |
4019 | the resulting pixels are stored in floating-point rather than integer | |
4020 | format. | |
4021 | ||
4022 | Pixel ordering is such that lower x screen coordinates correspond to | |
4023 | lower @var{i} filter image coordinates, and lower y screen coordinates | |
4024 | correspond to lower @var{j} filter image coordinates. | |
4025 | ||
4026 | Note that after a convolution is performed, the resulting color | |
4027 | components are also scaled by their corresponding | |
4028 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
4029 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
4030 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
f37e7e3d | 4031 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. |
8925f36f | 4032 | |
8925f36f AW |
4033 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
4034 | @code{GL_CONVOLUTION_2D}. | |
4035 | ||
4036 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
4037 | of the allowable values. | |
4038 | ||
4039 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
f37e7e3d DH |
4040 | greater than the maximum supported value. This value may be queried with |
4041 | @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_2D} | |
4042 | and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
8925f36f AW |
4043 | |
4044 | @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero | |
f37e7e3d | 4045 | or greater than the maximum supported value. This value may be queried |
8925f36f AW |
4046 | with @code{glGetConvolutionParameter} using target |
4047 | @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
4048 | ||
4049 | @code{GL_INVALID_OPERATION} is generated if | |
4050 | @code{glCopyConvolutionFilter2D} is executed between the execution of | |
4051 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
4052 | ||
bb894c9d | 4053 | @end deftypefun |
8925f36f | 4054 | |
bb894c9d | 4055 | @deftypefun void glCopyPixels x y width height type |
3c9b6116 AW |
4056 | Copy pixels in the frame buffer. |
4057 | ||
8925f36f AW |
4058 | @table @asis |
4059 | @item @var{x} | |
4060 | @itemx @var{y} | |
4061 | Specify the window coordinates of the lower left corner of the | |
4062 | rectangular region of pixels to be copied. | |
4063 | ||
4064 | @item @var{width} | |
4065 | @itemx @var{height} | |
4066 | Specify the dimensions of the rectangular region of pixels to be copied. | |
4067 | Both must be nonnegative. | |
4068 | ||
4069 | @item @var{type} | |
4070 | Specifies whether color values, depth values, or stencil values are to | |
f37e7e3d | 4071 | be copied. Symbolic constants @code{GL_COLOR}, @code{GL_DEPTH}, and |
8925f36f AW |
4072 | @code{GL_STENCIL} are accepted. |
4073 | ||
4074 | @end table | |
4075 | ||
8925f36f AW |
4076 | @code{glCopyPixels} copies a screen-aligned rectangle of pixels from the |
4077 | specified frame buffer location to a region relative to the current | |
f37e7e3d DH |
4078 | raster position. Its operation is well defined only if the entire pixel |
4079 | source region is within the exposed portion of the window. Results of | |
8925f36f AW |
4080 | copies from outside the window, or from regions of the window that are |
4081 | not exposed, are hardware dependent and undefined. | |
4082 | ||
4083 | @var{x} and @var{y} specify the window coordinates of the lower left | |
f37e7e3d | 4084 | corner of the rectangular region to be copied. @var{width} and |
8925f36f | 4085 | @var{height} specify the dimensions of the rectangular region to be |
f37e7e3d | 4086 | copied. Both @var{width} and @var{height} must not be negative. |
8925f36f AW |
4087 | |
4088 | Several parameters control the processing of the pixel data while it is | |
f37e7e3d DH |
4089 | being copied. These parameters are set with three commands: |
4090 | @code{glPixelTransfer}, @code{glPixelMap}, and @code{glPixelZoom}. This | |
8925f36f AW |
4091 | reference page describes the effects on @code{glCopyPixels} of most, but |
4092 | not all, of the parameters specified by these three commands. | |
4093 | ||
4094 | @code{glCopyPixels} copies values from each pixel with the lower | |
3c9b6116 | 4095 | left-hand corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for |
f37e7e3d DH |
4096 | @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel |
4097 | is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels | |
3c9b6116 AW |
4098 | are copied in row order from the lowest to the highest row, left to |
4099 | right in each row. | |
8925f36f AW |
4100 | |
4101 | @var{type} specifies whether color, depth, or stencil data is to be | |
f37e7e3d | 4102 | copied. The details of the transfer for each data type are as follows: |
8925f36f AW |
4103 | |
4104 | @table @asis | |
4105 | @item @code{GL_COLOR} | |
4106 | Indices or RGBA colors are read from the buffer currently specified as | |
f37e7e3d | 4107 | the read source buffer (see @code{glReadBuffer}). If the GL is in color |
8925f36f AW |
4108 | index mode, each index that is read from this buffer is converted to a |
4109 | fixed-point format with an unspecified number of bits to the right of | |
f37e7e3d DH |
4110 | the binary point. Each index is then shifted left by |
4111 | @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If | |
4112 | @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either | |
8925f36f AW |
4113 | case, zero bits fill otherwise unspecified bit locations in the result. |
4114 | If @code{GL_MAP_COLOR} is true, the index is replaced with the value | |
f37e7e3d | 4115 | that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether |
8925f36f | 4116 | the lookup replacement of the index is done or not, the integer part of |
3c9b6116 AW |
4117 | the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
4118 | number of bits in a color index buffer. | |
8925f36f AW |
4119 | |
4120 | If the GL is in RGBA mode, the red, green, blue, and alpha components of | |
4121 | each pixel that is read are converted to an internal floating-point | |
f37e7e3d DH |
4122 | format with unspecified precision. The conversion maps the largest |
4123 | representable component value to 1.0, and component value 0 to 0.0. The | |
8925f36f AW |
4124 | resulting floating-point color values are then multiplied by |
4125 | @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED, | |
f37e7e3d DH |
4126 | GREEN, BLUE, and ALPHA for the respective color components. The results |
4127 | are clamped to the range [0,1]. If @code{GL_MAP_COLOR} is true, each | |
8925f36f AW |
4128 | color component is scaled by the size of lookup table |
4129 | @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the value that it | |
f37e7e3d | 4130 | references in that table. @var{c} is R, G, B, or A. |
8925f36f AW |
4131 | |
4132 | If the @code{ARB_imaging} extension is supported, the color values may | |
4133 | be additionally processed by color-table lookups, color-matrix | |
4134 | transformations, and convolution filters. | |
4135 | ||
4136 | The GL then converts the resulting indices or RGBA colors to fragments | |
4137 | by attaching the current raster position @var{z} coordinate and texture | |
4138 | coordinates to each pixel, then assigning window coordinates | |
3c9b6116 AW |
4139 | @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where |
4140 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, | |
4141 | and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row. | |
4142 | These pixel fragments are then treated just like the fragments generated | |
f37e7e3d DH |
4143 | by rasterizing points, lines, or polygons. Texture mapping, fog, and all |
4144 | the fragment operations are applied before the fragments are written to | |
4145 | the frame buffer. | |
8925f36f AW |
4146 | |
4147 | @item @code{GL_DEPTH} | |
4148 | Depth values are read from the depth buffer and converted directly to an | |
f37e7e3d DH |
4149 | internal floating-point format with unspecified precision. The resulting |
4150 | floating-point depth value is then multiplied by @code{GL_DEPTH_SCALE} | |
4151 | and added to @code{GL_DEPTH_BIAS}. The result is clamped to the range | |
4152 | [0,1]. | |
8925f36f AW |
4153 | |
4154 | The GL then converts the resulting depth components to fragments by | |
4155 | attaching the current raster position color or color index and texture | |
4156 | coordinates to each pixel, then assigning window coordinates | |
3c9b6116 AW |
4157 | @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where |
4158 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, | |
4159 | and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row. | |
4160 | These pixel fragments are then treated just like the fragments generated | |
f37e7e3d DH |
4161 | by rasterizing points, lines, or polygons. Texture mapping, fog, and all |
4162 | the fragment operations are applied before the fragments are written to | |
4163 | the frame buffer. | |
8925f36f AW |
4164 | |
4165 | @item @code{GL_STENCIL} | |
4166 | Stencil indices are read from the stencil buffer and converted to an | |
4167 | internal fixed-point format with an unspecified number of bits to the | |
f37e7e3d DH |
4168 | right of the binary point. Each fixed-point index is then shifted left |
4169 | by @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If | |
4170 | @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either | |
8925f36f AW |
4171 | case, zero bits fill otherwise unspecified bit locations in the result. |
4172 | If @code{GL_MAP_STENCIL} is true, the index is replaced with the value | |
f37e7e3d | 4173 | that it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether |
8925f36f | 4174 | the lookup replacement of the index is done or not, the integer part of |
3c9b6116 | 4175 | the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
f37e7e3d | 4176 | number of bits in the stencil buffer. The resulting stencil indices are |
3c9b6116 AW |
4177 | then written to the stencil buffer such that the index read from the |
4178 | @r{@var{i}}th location of the @r{@var{j}}th row is written to location | |
4179 | @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where | |
4180 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position. | |
8925f36f AW |
4181 | Only the pixel ownership test, the scissor test, and the stencil |
4182 | writemask affect these write operations. | |
4183 | ||
4184 | @end table | |
4185 | ||
4186 | The rasterization described thus far assumes pixel zoom factors of 1.0. | |
3c9b6116 | 4187 | If @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}} |
f37e7e3d | 4188 | pixel zoom factors, pixels are converted to fragments as follows. If |
3c9b6116 AW |
4189 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, |
4190 | and a given pixel is in the @r{@var{i}}th location in the @r{@var{j}}th | |
4191 | row of the source pixel rectangle, then fragments are generated for | |
4192 | pixels whose centers are in the rectangle with corners at | |
8925f36f | 4193 | |
3c9b6116 | 4194 | @r{(@var{x}_@var{r}+@var{zoom}_@var{x},@var{i},@var{y}_@var{r}+@var{zoom}_@var{y},@var{j})} |
8925f36f AW |
4195 | |
4196 | and | |
4197 | ||
3c9b6116 | 4198 | @r{(@var{x}_@var{r}+@var{zoom}_@var{x},(@var{i}+1,),@var{y}_@var{r}+@var{zoom}_@var{y},(@var{j}+1,))} |
8925f36f | 4199 | |
3c9b6116 AW |
4200 | where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and |
4201 | @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}. | |
8925f36f | 4202 | |
8925f36f AW |
4203 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
4204 | value. | |
4205 | ||
4206 | @code{GL_INVALID_VALUE} is generated if either @var{width} or | |
4207 | @var{height} is negative. | |
4208 | ||
4209 | @code{GL_INVALID_OPERATION} is generated if @var{type} is | |
4210 | @code{GL_DEPTH} and there is no depth buffer. | |
4211 | ||
4212 | @code{GL_INVALID_OPERATION} is generated if @var{type} is | |
4213 | @code{GL_STENCIL} and there is no stencil buffer. | |
4214 | ||
4215 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyPixels} is | |
4216 | executed between the execution of @code{glBegin} and the corresponding | |
4217 | execution of @code{glEnd}. | |
4218 | ||
bb894c9d | 4219 | @end deftypefun |
8925f36f | 4220 | |
bb894c9d | 4221 | @deftypefun void glCopyTexImage1D target level internalformat x y width border |
3c9b6116 AW |
4222 | Copy pixels into a 1D texture image. |
4223 | ||
8925f36f AW |
4224 | @table @asis |
4225 | @item @var{target} | |
f37e7e3d | 4226 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. |
8925f36f AW |
4227 | |
4228 | @item @var{level} | |
f37e7e3d | 4229 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
4230 | Level @var{n} is the @var{n}th mipmap reduction image. |
4231 | ||
4232 | @item @var{internalformat} | |
f37e7e3d | 4233 | Specifies the internal format of the texture. Must be one of the |
8925f36f AW |
4234 | following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4}, |
4235 | @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16}, | |
4236 | @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE}, | |
4237 | @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
4238 | @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA}, | |
4239 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4240 | @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32}, | |
4241 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, | |
4242 | @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
4243 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
4244 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
4245 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
4246 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
4247 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB}, | |
4248 | @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
4249 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
4250 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
4251 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16}, | |
4252 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
4253 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
4254 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
4255 | ||
4256 | @item @var{x} | |
4257 | @itemx @var{y} | |
4258 | Specify the window coordinates of the left corner of the row of pixels | |
4259 | to be copied. | |
4260 | ||
4261 | @item @var{width} | |
f37e7e3d DH |
4262 | Specifies the width of the texture image. Must be 0 or |
4263 | @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. The height | |
4264 | of the texture image is 1. | |
8925f36f AW |
4265 | |
4266 | @item @var{border} | |
f37e7e3d | 4267 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
4268 | |
4269 | @end table | |
4270 | ||
8925f36f AW |
4271 | @code{glCopyTexImage1D} defines a one-dimensional texture image with |
4272 | pixels from the current @code{GL_READ_BUFFER}. | |
4273 | ||
3c9b6116 AW |
4274 | The screen-aligned pixel row with left corner at @r{(@var{x},@var{y})} |
4275 | and with a length of @r{@var{width}+2(@var{border},)} defines the | |
4276 | texture array at the mipmap level specified by @var{level}. | |
4277 | @var{internalformat} specifies the internal format of the texture array. | |
8925f36f AW |
4278 | |
4279 | The pixels in the row are processed exactly as if @code{glCopyPixels} | |
f37e7e3d | 4280 | had been called, but the process stops just before final conversion. At |
3c9b6116 AW |
4281 | this point all pixel component values are clamped to the range @r{[0,1]} |
4282 | and then converted to the texture's internal format for storage in the | |
4283 | texel array. | |
8925f36f | 4284 | |
3c9b6116 | 4285 | Pixel ordering is such that lower @r{@var{x}} screen coordinates |
8925f36f AW |
4286 | correspond to lower texture coordinates. |
4287 | ||
4288 | If any of the pixels within the specified row of the current | |
4289 | @code{GL_READ_BUFFER} are outside the window associated with the current | |
4290 | rendering context, then the values obtained for those pixels are | |
4291 | undefined. | |
4292 | ||
4293 | @code{glCopyTexImage1D} defines a one-dimensional texture image with | |
4294 | pixels from the current @code{GL_READ_BUFFER}. | |
4295 | ||
4296 | When @var{internalformat} is one of the sRGB types, the GL does not | |
f37e7e3d DH |
4297 | automatically convert the source pixels to the sRGB color space. In this |
4298 | case, the @code{glPixelMap} function can be used to accomplish the | |
8925f36f AW |
4299 | conversion. |
4300 | ||
8925f36f AW |
4301 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
4302 | allowable values. | |
4303 | ||
4304 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4305 | ||
4306 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
4307 | @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of |
4308 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
4309 | |
4310 | @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an | |
4311 | allowable value. | |
4312 | ||
4313 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or | |
4314 | greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
4315 | ||
4316 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
4317 | not supported and the @var{width} cannot be represented as | |
3c9b6116 | 4318 | @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}. |
8925f36f AW |
4319 | |
4320 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
4321 | ||
4322 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage1D} is | |
4323 | executed between the execution of @code{glBegin} and the corresponding | |
4324 | execution of @code{glEnd}. | |
4325 | ||
4326 | @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is | |
4327 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4328 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is | |
4329 | no depth buffer. | |
4330 | ||
bb894c9d | 4331 | @end deftypefun |
8925f36f | 4332 | |
bb894c9d | 4333 | @deftypefun void glCopyTexImage2D target level internalformat x y width height border |
3c9b6116 AW |
4334 | Copy pixels into a 2D texture image. |
4335 | ||
8925f36f AW |
4336 | @table @asis |
4337 | @item @var{target} | |
f37e7e3d | 4338 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, |
8925f36f AW |
4339 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, |
4340 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4341 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4342 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4343 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4344 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4345 | ||
4346 | @item @var{level} | |
f37e7e3d | 4347 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
4348 | Level @var{n} is the @var{n}th mipmap reduction image. |
4349 | ||
4350 | @item @var{internalformat} | |
f37e7e3d | 4351 | Specifies the internal format of the texture. Must be one of the |
8925f36f AW |
4352 | following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4}, |
4353 | @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16}, | |
4354 | @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE}, | |
4355 | @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
4356 | @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA}, | |
4357 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4358 | @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32}, | |
4359 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, | |
4360 | @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
4361 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
4362 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
4363 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
4364 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
4365 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB}, | |
4366 | @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
4367 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
4368 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
4369 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16}, | |
4370 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
4371 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
4372 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
4373 | ||
4374 | @item @var{x} | |
4375 | @itemx @var{y} | |
4376 | Specify the window coordinates of the lower left corner of the | |
4377 | rectangular region of pixels to be copied. | |
4378 | ||
4379 | @item @var{width} | |
f37e7e3d | 4380 | Specifies the width of the texture image. Must be 0 or |
3c9b6116 | 4381 | @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. |
8925f36f AW |
4382 | |
4383 | @item @var{height} | |
f37e7e3d | 4384 | Specifies the height of the texture image. Must be 0 or |
3c9b6116 | 4385 | @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}. |
8925f36f AW |
4386 | |
4387 | @item @var{border} | |
f37e7e3d | 4388 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
4389 | |
4390 | @end table | |
4391 | ||
8925f36f AW |
4392 | @code{glCopyTexImage2D} defines a two-dimensional texture image, or |
4393 | cube-map texture image with pixels from the current | |
4394 | @code{GL_READ_BUFFER}. | |
4395 | ||
4396 | The screen-aligned pixel rectangle with lower left corner at (@var{x}, | |
3c9b6116 AW |
4397 | @var{y}) and with a width of @r{@var{width}+2(@var{border},)} and a |
4398 | height of @r{@var{height}+2(@var{border},)} defines the texture array | |
f37e7e3d | 4399 | at the mipmap level specified by @var{level}. @var{internalformat} |
8925f36f AW |
4400 | specifies the internal format of the texture array. |
4401 | ||
4402 | The pixels in the rectangle are processed exactly as if | |
4403 | @code{glCopyPixels} had been called, but the process stops just before | |
f37e7e3d | 4404 | final conversion. At this point all pixel component values are clamped |
3c9b6116 | 4405 | to the range @r{[0,1]} and then converted to the texture's internal |
8925f36f AW |
4406 | format for storage in the texel array. |
4407 | ||
3c9b6116 AW |
4408 | Pixel ordering is such that lower @r{@var{x}} and @r{@var{y}} screen |
4409 | coordinates correspond to lower @r{@var{s}} and @r{@var{t}} texture | |
4410 | coordinates. | |
8925f36f AW |
4411 | |
4412 | If any of the pixels within the specified rectangle of the current | |
4413 | @code{GL_READ_BUFFER} are outside the window associated with the current | |
4414 | rendering context, then the values obtained for those pixels are | |
4415 | undefined. | |
4416 | ||
4417 | When @var{internalformat} is one of the sRGB types, the GL does not | |
f37e7e3d DH |
4418 | automatically convert the source pixels to the sRGB color space. In this |
4419 | case, the @code{glPixelMap} function can be used to accomplish the | |
8925f36f AW |
4420 | conversion. |
4421 | ||
8925f36f AW |
4422 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
4423 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
4424 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4425 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4426 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4427 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4428 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4429 | ||
4430 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4431 | ||
4432 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
4433 | @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of |
4434 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
4435 | |
4436 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or | |
4437 | greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
4438 | ||
4439 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
4440 | not supported and the @var{width} or @var{depth} cannot be represented | |
3c9b6116 | 4441 | as @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}. |
8925f36f AW |
4442 | |
4443 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
4444 | ||
4445 | @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an | |
4446 | accepted format. | |
4447 | ||
4448 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage2D} is | |
4449 | executed between the execution of @code{glBegin} and the corresponding | |
4450 | execution of @code{glEnd}. | |
4451 | ||
4452 | @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is | |
4453 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4454 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is | |
4455 | no depth buffer. | |
4456 | ||
bb894c9d | 4457 | @end deftypefun |
8925f36f | 4458 | |
bb894c9d | 4459 | @deftypefun void glCopyTexSubImage1D target level xoffset x y width |
3c9b6116 AW |
4460 | Copy a one-dimensional texture subimage. |
4461 | ||
8925f36f AW |
4462 | @table @asis |
4463 | @item @var{target} | |
f37e7e3d | 4464 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. |
8925f36f AW |
4465 | |
4466 | @item @var{level} | |
f37e7e3d | 4467 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
4468 | Level @var{n} is the @var{n}th mipmap reduction image. |
4469 | ||
4470 | @item @var{xoffset} | |
4471 | Specifies the texel offset within the texture array. | |
4472 | ||
4473 | @item @var{x} | |
4474 | @itemx @var{y} | |
4475 | Specify the window coordinates of the left corner of the row of pixels | |
4476 | to be copied. | |
4477 | ||
4478 | @item @var{width} | |
4479 | Specifies the width of the texture subimage. | |
4480 | ||
4481 | @end table | |
4482 | ||
8925f36f AW |
4483 | @code{glCopyTexSubImage1D} replaces a portion of a one-dimensional |
4484 | texture image with pixels from the current @code{GL_READ_BUFFER} (rather | |
4485 | than from main memory, as is the case for @code{glTexSubImage1D}). | |
4486 | ||
4487 | The screen-aligned pixel row with left corner at (@var{x},\ @var{y}), | |
4488 | and with length @var{width} replaces the portion of the texture array | |
3c9b6116 | 4489 | with x indices @var{xoffset} through @r{@var{xoffset}+@var{width}-1}, |
f37e7e3d | 4490 | inclusive. The destination in the texture array may not include any |
8925f36f AW |
4491 | texels outside the texture array as it was originally specified. |
4492 | ||
4493 | The pixels in the row are processed exactly as if @code{glCopyPixels} | |
f37e7e3d | 4494 | had been called, but the process stops just before final conversion. At |
8925f36f | 4495 | this point, all pixel component values are clamped to the range |
3c9b6116 | 4496 | @r{[0,1]} and then converted to the texture's internal format for |
8925f36f AW |
4497 | storage in the texel array. |
4498 | ||
4499 | It is not an error to specify a subtexture with zero width, but such a | |
f37e7e3d | 4500 | specification has no effect. If any of the pixels within the specified |
8925f36f AW |
4501 | row of the current @code{GL_READ_BUFFER} are outside the read window |
4502 | associated with the current rendering context, then the values obtained | |
4503 | for those pixels are undefined. | |
4504 | ||
4505 | No change is made to the @var{internalformat}, @var{width}, or | |
4506 | @var{border} parameters of the specified texture array or to texel | |
4507 | values outside the specified subregion. | |
4508 | ||
8925f36f AW |
4509 | @code{GL_INVALID_ENUM} is generated if /@var{target} is not |
4510 | @code{GL_TEXTURE_1D}. | |
4511 | ||
4512 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
4513 | been defined by a previous @code{glTexImage1D} or | |
4514 | @code{glCopyTexImage1D} operation. | |
4515 | ||
4516 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4517 | ||
4518 | @code{GL_INVALID_VALUE} may be generated if | |
3c9b6116 | 4519 | @r{@var{level}>@var{log}_2(@var{max},)}, where @var{max} is the |
8925f36f AW |
4520 | returned value of @code{GL_MAX_TEXTURE_SIZE}. |
4521 | ||
3c9b6116 AW |
4522 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or |
4523 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where @r{@var{w}} | |
4524 | is the @code{GL_TEXTURE_WIDTH} and @r{@var{b}} is the | |
f37e7e3d | 4525 | @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that |
3c9b6116 | 4526 | @r{@var{w}} includes twice the border width. |
8925f36f AW |
4527 | |
4528 | ||
4529 | ||
bb894c9d | 4530 | @end deftypefun |
8925f36f | 4531 | |
bb894c9d | 4532 | @deftypefun void glCopyTexSubImage2D target level xoffset yoffset x y width height |
3c9b6116 AW |
4533 | Copy a two-dimensional texture subimage. |
4534 | ||
8925f36f AW |
4535 | @table @asis |
4536 | @item @var{target} | |
f37e7e3d | 4537 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, |
8925f36f AW |
4538 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, |
4539 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4540 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4541 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4542 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4543 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4544 | ||
4545 | @item @var{level} | |
f37e7e3d | 4546 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
4547 | Level @var{n} is the @var{n}th mipmap reduction image. |
4548 | ||
4549 | @item @var{xoffset} | |
4550 | Specifies a texel offset in the x direction within the texture array. | |
4551 | ||
4552 | @item @var{yoffset} | |
4553 | Specifies a texel offset in the y direction within the texture array. | |
4554 | ||
4555 | @item @var{x} | |
4556 | @itemx @var{y} | |
4557 | Specify the window coordinates of the lower left corner of the | |
4558 | rectangular region of pixels to be copied. | |
4559 | ||
4560 | @item @var{width} | |
4561 | Specifies the width of the texture subimage. | |
4562 | ||
4563 | @item @var{height} | |
4564 | Specifies the height of the texture subimage. | |
4565 | ||
4566 | @end table | |
4567 | ||
8925f36f AW |
4568 | @code{glCopyTexSubImage2D} replaces a rectangular portion of a |
4569 | two-dimensional texture image or cube-map texture image with pixels from | |
4570 | the current @code{GL_READ_BUFFER} (rather than from main memory, as is | |
4571 | the case for @code{glTexSubImage2D}). | |
4572 | ||
4573 | The screen-aligned pixel rectangle with lower left corner at | |
3c9b6116 AW |
4574 | @r{(@var{x},@var{y})} and with width @var{width} and height @var{height} |
4575 | replaces the portion of the texture array with x indices @var{xoffset} | |
4576 | through @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices | |
4577 | @var{yoffset} through @r{@var{yoffset}+@var{height}-1}, inclusive, at | |
4578 | the mipmap level specified by @var{level}. | |
8925f36f AW |
4579 | |
4580 | The pixels in the rectangle are processed exactly as if | |
4581 | @code{glCopyPixels} had been called, but the process stops just before | |
f37e7e3d | 4582 | final conversion. At this point, all pixel component values are clamped |
3c9b6116 | 4583 | to the range @r{[0,1]} and then converted to the texture's internal |
8925f36f AW |
4584 | format for storage in the texel array. |
4585 | ||
4586 | The destination rectangle in the texture array may not include any | |
f37e7e3d | 4587 | texels outside the texture array as it was originally specified. It is |
8925f36f AW |
4588 | not an error to specify a subtexture with zero width or height, but such |
4589 | a specification has no effect. | |
4590 | ||
4591 | If any of the pixels within the specified rectangle of the current | |
4592 | @code{GL_READ_BUFFER} are outside the read window associated with the | |
4593 | current rendering context, then the values obtained for those pixels are | |
4594 | undefined. | |
4595 | ||
4596 | No change is made to the @var{internalformat}, @var{width}, | |
4597 | @var{height}, or @var{border} parameters of the specified texture array | |
4598 | or to texel values outside the specified subregion. | |
4599 | ||
8925f36f AW |
4600 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
4601 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
4602 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4603 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4604 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4605 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4606 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4607 | ||
4608 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
4609 | been defined by a previous @code{glTexImage2D} or | |
4610 | @code{glCopyTexImage2D} operation. | |
4611 | ||
4612 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4613 | ||
4614 | @code{GL_INVALID_VALUE} may be generated if | |
3c9b6116 AW |
4615 | @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the |
4616 | returned value of @code{GL_MAX_TEXTURE_SIZE}. | |
4617 | ||
4618 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, | |
4619 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
4620 | @r{@var{yoffset}<-@var{b}}, or | |
4621 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}} | |
4622 | is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the | |
4623 | @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the | |
f37e7e3d | 4624 | @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that |
3c9b6116 | 4625 | @r{@var{w}} and @r{@var{h}} include twice the border width. |
8925f36f AW |
4626 | |
4627 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage2D} | |
4628 | is executed between the execution of @code{glBegin} and the | |
4629 | corresponding execution of @code{glEnd}. | |
4630 | ||
bb894c9d | 4631 | @end deftypefun |
8925f36f | 4632 | |
bb894c9d | 4633 | @deftypefun void glCopyTexSubImage3D target level xoffset yoffset zoffset x y width height |
3c9b6116 AW |
4634 | Copy a three-dimensional texture subimage. |
4635 | ||
8925f36f AW |
4636 | @table @asis |
4637 | @item @var{target} | |
f37e7e3d | 4638 | Specifies the target texture. Must be @code{GL_TEXTURE_3D} |
8925f36f AW |
4639 | |
4640 | @item @var{level} | |
f37e7e3d | 4641 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
4642 | Level @var{n} is the @var{n}th mipmap reduction image. |
4643 | ||
4644 | @item @var{xoffset} | |
4645 | Specifies a texel offset in the x direction within the texture array. | |
4646 | ||
4647 | @item @var{yoffset} | |
4648 | Specifies a texel offset in the y direction within the texture array. | |
4649 | ||
4650 | @item @var{zoffset} | |
4651 | Specifies a texel offset in the z direction within the texture array. | |
4652 | ||
4653 | @item @var{x} | |
4654 | @itemx @var{y} | |
4655 | Specify the window coordinates of the lower left corner of the | |
4656 | rectangular region of pixels to be copied. | |
4657 | ||
4658 | @item @var{width} | |
4659 | Specifies the width of the texture subimage. | |
4660 | ||
4661 | @item @var{height} | |
4662 | Specifies the height of the texture subimage. | |
4663 | ||
4664 | @end table | |
4665 | ||
8925f36f AW |
4666 | @code{glCopyTexSubImage3D} replaces a rectangular portion of a |
4667 | three-dimensional texture image with pixels from the current | |
4668 | @code{GL_READ_BUFFER} (rather than from main memory, as is the case for | |
4669 | @code{glTexSubImage3D}). | |
4670 | ||
4671 | The screen-aligned pixel rectangle with lower left corner at (@var{x},\ | |
4672 | @var{y}) and with width @var{width} and height @var{height} replaces the | |
4673 | portion of the texture array with x indices @var{xoffset} through | |
3c9b6116 AW |
4674 | @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices @var{yoffset} |
4675 | through @r{@var{yoffset}+@var{height}-1}, inclusive, at z index | |
4676 | @var{zoffset} and at the mipmap level specified by @var{level}. | |
8925f36f AW |
4677 | |
4678 | The pixels in the rectangle are processed exactly as if | |
4679 | @code{glCopyPixels} had been called, but the process stops just before | |
f37e7e3d | 4680 | final conversion. At this point, all pixel component values are clamped |
3c9b6116 | 4681 | to the range @r{[0,1]} and then converted to the texture's internal |
8925f36f AW |
4682 | format for storage in the texel array. |
4683 | ||
4684 | The destination rectangle in the texture array may not include any | |
f37e7e3d | 4685 | texels outside the texture array as it was originally specified. It is |
8925f36f AW |
4686 | not an error to specify a subtexture with zero width or height, but such |
4687 | a specification has no effect. | |
4688 | ||
4689 | If any of the pixels within the specified rectangle of the current | |
4690 | @code{GL_READ_BUFFER} are outside the read window associated with the | |
4691 | current rendering context, then the values obtained for those pixels are | |
4692 | undefined. | |
4693 | ||
4694 | No change is made to the @var{internalformat}, @var{width}, | |
4695 | @var{height}, @var{depth}, or @var{border} parameters of the specified | |
4696 | texture array or to texel values outside the specified subregion. | |
4697 | ||
8925f36f AW |
4698 | @code{GL_INVALID_ENUM} is generated if /@var{target} is not |
4699 | @code{GL_TEXTURE_3D}. | |
4700 | ||
4701 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
4702 | been defined by a previous @code{glTexImage3D} operation. | |
4703 | ||
4704 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4705 | ||
4706 | @code{GL_INVALID_VALUE} may be generated if | |
3c9b6116 AW |
4707 | @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the |
4708 | returned value of @code{GL_MAX_3D_TEXTURE_SIZE}. | |
4709 | ||
4710 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, | |
4711 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
4712 | @r{@var{yoffset}<-@var{b}}, | |
4713 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, | |
4714 | @r{@var{zoffset}<-@var{b}}, or | |
4715 | @r{(@var{zoffset}+1,)>(@var{d}-@var{b},)}, where @r{@var{w}} is the | |
4716 | @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the @code{GL_TEXTURE_HEIGHT}, | |
4717 | @r{@var{d}} is the @code{GL_TEXTURE_DEPTH}, and @r{@var{b}} is the | |
f37e7e3d | 4718 | @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that |
3c9b6116 AW |
4719 | @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the border |
4720 | width. | |
8925f36f AW |
4721 | |
4722 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage3D} | |
4723 | is executed between the execution of @code{glBegin} and the | |
4724 | corresponding execution of @code{glEnd}. | |
4725 | ||
bb894c9d | 4726 | @end deftypefun |
8925f36f | 4727 | |
bb894c9d | 4728 | @deftypefun GLuint glCreateProgram |
3c9b6116 AW |
4729 | Creates a program object. |
4730 | ||
8925f36f | 4731 | @code{glCreateProgram} creates an empty program object and returns a |
f37e7e3d DH |
4732 | non-zero value by which it can be referenced. A program object is an |
4733 | object to which shader objects can be attached. This provides a | |
8925f36f | 4734 | mechanism to specify the shader objects that will be linked to create a |
f37e7e3d | 4735 | program. It also provides a means for checking the compatibility of the |
8925f36f | 4736 | shaders that will be used to create a program (for instance, checking |
f37e7e3d | 4737 | the compatibility between a vertex shader and a fragment shader). When |
8925f36f AW |
4738 | no longer needed as part of a program object, shader objects can be |
4739 | detached. | |
4740 | ||
4741 | One or more executables are created in a program object by successfully | |
4742 | attaching shader objects to it with @code{glAttachShader}, successfully | |
4743 | compiling the shader objects with @code{glCompileShader}, and | |
f37e7e3d | 4744 | successfully linking the program object with @code{glLinkProgram}. These |
8925f36f | 4745 | executables are made part of current state when @code{glUseProgram} is |
f37e7e3d DH |
4746 | called. Program objects can be deleted by calling |
4747 | @code{glDeleteProgram}. The memory associated with the program object | |
8925f36f AW |
4748 | will be deleted when it is no longer part of current rendering state for |
4749 | any context. | |
4750 | ||
8925f36f AW |
4751 | This function returns 0 if an error occurs creating the program object. |
4752 | ||
4753 | @code{GL_INVALID_OPERATION} is generated if @code{glCreateProgram} is | |
4754 | executed between the execution of @code{glBegin} and the corresponding | |
4755 | execution of @code{glEnd}. | |
4756 | ||
bb894c9d | 4757 | @end deftypefun |
8925f36f | 4758 | |
bb894c9d | 4759 | @deftypefun GLuint glCreateShader shaderType |
3c9b6116 AW |
4760 | Creates a shader object. |
4761 | ||
8925f36f AW |
4762 | @table @asis |
4763 | @item @var{shaderType} | |
f37e7e3d | 4764 | Specifies the type of shader to be created. Must be either |
8925f36f AW |
4765 | @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER}. |
4766 | ||
4767 | @end table | |
4768 | ||
8925f36f | 4769 | @code{glCreateShader} creates an empty shader object and returns a |
f37e7e3d DH |
4770 | non-zero value by which it can be referenced. A shader object is used to |
4771 | maintain the source code strings that define a shader. @var{shaderType} | |
4772 | indicates the type of shader to be created. Two types of shaders are | |
4773 | supported. A shader of type @code{GL_VERTEX_SHADER} is a shader that is | |
4774 | intended to run on the programmable vertex processor and replace the | |
4775 | fixed functionality vertex processing in OpenGL. A shader of type | |
4776 | @code{GL_FRAGMENT_SHADER} is a shader that is intended to run on the | |
4777 | programmable fragment processor and replace the fixed functionality | |
8925f36f AW |
4778 | fragment processing in OpenGL. |
4779 | ||
4780 | When created, a shader object's @code{GL_SHADER_TYPE} parameter is set | |
4781 | to either @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER}, | |
4782 | depending on the value of @var{shaderType}. | |
4783 | ||
8925f36f AW |
4784 | This function returns 0 if an error occurs creating the shader object. |
4785 | ||
4786 | @code{GL_INVALID_ENUM} is generated if @var{shaderType} is not an | |
4787 | accepted value. | |
4788 | ||
4789 | @code{GL_INVALID_OPERATION} is generated if @code{glCreateShader} is | |
4790 | executed between the execution of @code{glBegin} and the corresponding | |
4791 | execution of @code{glEnd}. | |
4792 | ||
bb894c9d | 4793 | @end deftypefun |
8925f36f | 4794 | |
bb894c9d | 4795 | @deftypefun void glCullFace mode |
3c9b6116 AW |
4796 | Specify whether front- or back-facing facets can be culled. |
4797 | ||
8925f36f AW |
4798 | @table @asis |
4799 | @item @var{mode} | |
4800 | Specifies whether front- or back-facing facets are candidates for | |
f37e7e3d DH |
4801 | culling. Symbolic constants @code{GL_FRONT}, @code{GL_BACK}, and |
4802 | @code{GL_FRONT_AND_BACK} are accepted. The initial value is | |
8925f36f AW |
4803 | @code{GL_BACK}. |
4804 | ||
4805 | @end table | |
4806 | ||
8925f36f | 4807 | @code{glCullFace} specifies whether front- or back-facing facets are |
f37e7e3d DH |
4808 | culled (as specified by @var{mode}) when facet culling is enabled. Facet |
4809 | culling is initially disabled. To enable and disable facet culling, call | |
4810 | the @code{glEnable} and @code{glDisable} commands with the argument | |
4811 | @code{GL_CULL_FACE}. Facets include triangles, quadrilaterals, polygons, | |
4812 | and rectangles. | |
8925f36f AW |
4813 | |
4814 | @code{glFrontFace} specifies which of the clockwise and counterclockwise | |
f37e7e3d | 4815 | facets are front-facing and back-facing. See @code{glFrontFace}. |
8925f36f | 4816 | |
8925f36f AW |
4817 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
4818 | value. | |
4819 | ||
4820 | @code{GL_INVALID_OPERATION} is generated if @code{glCullFace} is | |
4821 | executed between the execution of @code{glBegin} and the corresponding | |
4822 | execution of @code{glEnd}. | |
4823 | ||
bb894c9d | 4824 | @end deftypefun |
8925f36f | 4825 | |
bb894c9d | 4826 | @deftypefun void glDeleteBuffers n buffers |
3c9b6116 AW |
4827 | Delete named buffer objects. |
4828 | ||
8925f36f AW |
4829 | @table @asis |
4830 | @item @var{n} | |
4831 | Specifies the number of buffer objects to be deleted. | |
4832 | ||
4833 | @item @var{buffers} | |
4834 | Specifies an array of buffer objects to be deleted. | |
4835 | ||
4836 | @end table | |
4837 | ||
8925f36f | 4838 | @code{glDeleteBuffers} deletes @var{n} buffer objects named by the |
f37e7e3d | 4839 | elements of the array @var{buffers}. After a buffer object is deleted, |
8925f36f | 4840 | it has no contents, and its name is free for reuse (for example by |
f37e7e3d | 4841 | @code{glGenBuffers}). If a buffer object that is currently bound is |
8925f36f AW |
4842 | deleted, the binding reverts to 0 (the absence of any buffer object, |
4843 | which reverts to client memory usage). | |
4844 | ||
4845 | @code{glDeleteBuffers} silently ignores 0's and names that do not | |
4846 | correspond to existing buffer objects. | |
4847 | ||
8925f36f AW |
4848 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
4849 | ||
4850 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteBuffers} is | |
4851 | executed between the execution of @code{glBegin} and the corresponding | |
4852 | execution of @code{glEnd}. | |
4853 | ||
bb894c9d | 4854 | @end deftypefun |
8925f36f | 4855 | |
bb894c9d | 4856 | @deftypefun void glDeleteLists list range |
3c9b6116 AW |
4857 | Delete a contiguous group of display lists. |
4858 | ||
8925f36f AW |
4859 | @table @asis |
4860 | @item @var{list} | |
4861 | Specifies the integer name of the first display list to delete. | |
4862 | ||
4863 | @item @var{range} | |
4864 | Specifies the number of display lists to delete. | |
4865 | ||
4866 | @end table | |
4867 | ||
8925f36f | 4868 | @code{glDeleteLists} causes a contiguous group of display lists to be |
f37e7e3d DH |
4869 | deleted. @var{list} is the name of the first display list to be deleted, |
4870 | and @var{range} is the number of display lists to delete. All display | |
4871 | lists @r{@var{d}} with @r{@var{list}<=@var{d}<=@var{list}+@var{range}-1} | |
4872 | are deleted. | |
8925f36f AW |
4873 | |
4874 | All storage locations allocated to the specified display lists are | |
f37e7e3d | 4875 | freed, and the names are available for reuse at a later time. Names |
8925f36f | 4876 | within the range that do not have an associated display list are |
f37e7e3d | 4877 | ignored. If @var{range} is 0, nothing happens. |
8925f36f | 4878 | |
8925f36f AW |
4879 | @code{GL_INVALID_VALUE} is generated if @var{range} is negative. |
4880 | ||
4881 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteLists} is | |
4882 | executed between the execution of @code{glBegin} and the corresponding | |
4883 | execution of @code{glEnd}. | |
4884 | ||
bb894c9d | 4885 | @end deftypefun |
8925f36f | 4886 | |
bb894c9d | 4887 | @deftypefun void glDeleteProgram program |
3c9b6116 AW |
4888 | Deletes a program object. |
4889 | ||
8925f36f AW |
4890 | @table @asis |
4891 | @item @var{program} | |
4892 | Specifies the program object to be deleted. | |
4893 | ||
4894 | @end table | |
4895 | ||
8925f36f AW |
4896 | @code{glDeleteProgram} frees the memory and invalidates the name |
4897 | associated with the program object specified by @var{program.} This | |
4898 | command effectively undoes the effects of a call to | |
4899 | @code{glCreateProgram}. | |
4900 | ||
4901 | If a program object is in use as part of current rendering state, it | |
4902 | will be flagged for deletion, but it will not be deleted until it is no | |
f37e7e3d | 4903 | longer part of current state for any rendering context. If a program |
8925f36f AW |
4904 | object to be deleted has shader objects attached to it, those shader |
4905 | objects will be automatically detached but not deleted unless they have | |
4906 | already been flagged for deletion by a previous call to | |
f37e7e3d | 4907 | @code{glDeleteShader}. A value of 0 for @var{program} will be silently |
8925f36f AW |
4908 | ignored. |
4909 | ||
4910 | To determine whether a program object has been flagged for deletion, | |
4911 | call @code{glGetProgram} with arguments @var{program} and | |
4912 | @code{GL_DELETE_STATUS}. | |
4913 | ||
8925f36f AW |
4914 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
4915 | generated by OpenGL. | |
4916 | ||
4917 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteProgram} is | |
4918 | executed between the execution of @code{glBegin} and the corresponding | |
4919 | execution of @code{glEnd}. | |
4920 | ||
bb894c9d | 4921 | @end deftypefun |
8925f36f | 4922 | |
bb894c9d | 4923 | @deftypefun void glDeleteQueries n ids |
3c9b6116 AW |
4924 | Delete named query objects. |
4925 | ||
8925f36f AW |
4926 | @table @asis |
4927 | @item @var{n} | |
4928 | Specifies the number of query objects to be deleted. | |
4929 | ||
4930 | @item @var{ids} | |
4931 | Specifies an array of query objects to be deleted. | |
4932 | ||
4933 | @end table | |
4934 | ||
8925f36f | 4935 | @code{glDeleteQueries} deletes @var{n} query objects named by the |
f37e7e3d DH |
4936 | elements of the array @var{ids}. After a query object is deleted, it has |
4937 | no contents, and its name is free for reuse (for example by | |
8925f36f AW |
4938 | @code{glGenQueries}). |
4939 | ||
4940 | @code{glDeleteQueries} silently ignores 0's and names that do not | |
4941 | correspond to existing query objects. | |
4942 | ||
8925f36f AW |
4943 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
4944 | ||
4945 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteQueries} is | |
4946 | executed between the execution of @code{glBegin} and the corresponding | |
4947 | execution of @code{glEnd}. | |
4948 | ||
bb894c9d | 4949 | @end deftypefun |
8925f36f | 4950 | |
bb894c9d | 4951 | @deftypefun void glDeleteShader shader |
3c9b6116 AW |
4952 | Deletes a shader object. |
4953 | ||
8925f36f AW |
4954 | @table @asis |
4955 | @item @var{shader} | |
4956 | Specifies the shader object to be deleted. | |
4957 | ||
4958 | @end table | |
4959 | ||
8925f36f | 4960 | @code{glDeleteShader} frees the memory and invalidates the name |
f37e7e3d | 4961 | associated with the shader object specified by @var{shader}. This |
8925f36f AW |
4962 | command effectively undoes the effects of a call to |
4963 | @code{glCreateShader}. | |
4964 | ||
4965 | If a shader object to be deleted is attached to a program object, it | |
4966 | will be flagged for deletion, but it will not be deleted until it is no | |
4967 | longer attached to any program object, for any rendering context (i.e., | |
4968 | it must be detached from wherever it was attached before it will be | |
f37e7e3d | 4969 | deleted). A value of 0 for @var{shader} will be silently ignored. |
8925f36f AW |
4970 | |
4971 | To determine whether an object has been flagged for deletion, call | |
4972 | @code{glGetShader} with arguments @var{shader} and | |
4973 | @code{GL_DELETE_STATUS}. | |
4974 | ||
8925f36f AW |
4975 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
4976 | generated by OpenGL. | |
4977 | ||
4978 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteShader} is | |
4979 | executed between the execution of @code{glBegin} and the corresponding | |
4980 | execution of @code{glEnd}. | |
4981 | ||
bb894c9d | 4982 | @end deftypefun |
8925f36f | 4983 | |
bb894c9d | 4984 | @deftypefun void glDeleteTextures n textures |
3c9b6116 AW |
4985 | Delete named textures. |
4986 | ||
8925f36f AW |
4987 | @table @asis |
4988 | @item @var{n} | |
4989 | Specifies the number of textures to be deleted. | |
4990 | ||
4991 | @item @var{textures} | |
4992 | Specifies an array of textures to be deleted. | |
4993 | ||
4994 | @end table | |
4995 | ||
8925f36f | 4996 | @code{glDeleteTextures} deletes @var{n} textures named by the elements |
f37e7e3d | 4997 | of the array @var{textures}. After a texture is deleted, it has no |
8925f36f | 4998 | contents or dimensionality, and its name is free for reuse (for example |
f37e7e3d | 4999 | by @code{glGenTextures}). If a texture that is currently bound is |
8925f36f AW |
5000 | deleted, the binding reverts to 0 (the default texture). |
5001 | ||
5002 | @code{glDeleteTextures} silently ignores 0's and names that do not | |
5003 | correspond to existing textures. | |
5004 | ||
8925f36f AW |
5005 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
5006 | ||
5007 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteTextures} is | |
5008 | executed between the execution of @code{glBegin} and the corresponding | |
5009 | execution of @code{glEnd}. | |
5010 | ||
bb894c9d | 5011 | @end deftypefun |
8925f36f | 5012 | |
bb894c9d | 5013 | @deftypefun void glDepthFunc func |
3c9b6116 AW |
5014 | Specify the value used for depth buffer comparisons. |
5015 | ||
8925f36f AW |
5016 | @table @asis |
5017 | @item @var{func} | |
f37e7e3d | 5018 | Specifies the depth comparison function. Symbolic constants |
8925f36f AW |
5019 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_EQUAL}, @code{GL_LEQUAL}, |
5020 | @code{GL_GREATER}, @code{GL_NOTEQUAL}, @code{GL_GEQUAL}, and | |
f37e7e3d | 5021 | @code{GL_ALWAYS} are accepted. The initial value is @code{GL_LESS}. |
8925f36f AW |
5022 | |
5023 | @end table | |
5024 | ||
8925f36f | 5025 | @code{glDepthFunc} specifies the function used to compare each incoming |
f37e7e3d DH |
5026 | pixel depth value with the depth value present in the depth buffer. The |
5027 | comparison is performed only if depth testing is enabled. (See | |
8925f36f AW |
5028 | @code{glEnable} and @code{glDisable} of @code{GL_DEPTH_TEST}.) |
5029 | ||
5030 | @var{func} specifies the conditions under which the pixel will be drawn. | |
5031 | The comparison functions are as follows: | |
5032 | ||
5033 | @table @asis | |
5034 | @item @code{GL_NEVER} | |
5035 | Never passes. | |
5036 | ||
5037 | @item @code{GL_LESS} | |
5038 | Passes if the incoming depth value is less than the stored depth value. | |
5039 | ||
5040 | @item @code{GL_EQUAL} | |
5041 | Passes if the incoming depth value is equal to the stored depth value. | |
5042 | ||
5043 | @item @code{GL_LEQUAL} | |
5044 | Passes if the incoming depth value is less than or equal to the stored | |
5045 | depth value. | |
5046 | ||
5047 | @item @code{GL_GREATER} | |
5048 | Passes if the incoming depth value is greater than the stored depth | |
5049 | value. | |
5050 | ||
5051 | @item @code{GL_NOTEQUAL} | |
5052 | Passes if the incoming depth value is not equal to the stored depth | |
5053 | value. | |
5054 | ||
5055 | @item @code{GL_GEQUAL} | |
5056 | Passes if the incoming depth value is greater than or equal to the | |
5057 | stored depth value. | |
5058 | ||
5059 | @item @code{GL_ALWAYS} | |
5060 | Always passes. | |
5061 | ||
5062 | @end table | |
5063 | ||
f37e7e3d DH |
5064 | The initial value of @var{func} is @code{GL_LESS}. Initially, depth |
5065 | testing is disabled. If depth testing is disabled or if no depth buffer | |
8925f36f AW |
5066 | exists, it is as if the depth test always passes. |
5067 | ||
8925f36f AW |
5068 | @code{GL_INVALID_ENUM} is generated if @var{func} is not an accepted |
5069 | value. | |
5070 | ||
5071 | @code{GL_INVALID_OPERATION} is generated if @code{glDepthFunc} is | |
5072 | executed between the execution of @code{glBegin} and the corresponding | |
5073 | execution of @code{glEnd}. | |
5074 | ||
bb894c9d | 5075 | @end deftypefun |
8925f36f | 5076 | |
bb894c9d | 5077 | @deftypefun void glDepthMask flag |
3c9b6116 AW |
5078 | Enable or disable writing into the depth buffer. |
5079 | ||
8925f36f AW |
5080 | @table @asis |
5081 | @item @var{flag} | |
f37e7e3d DH |
5082 | Specifies whether the depth buffer is enabled for writing. If @var{flag} |
5083 | is @code{GL_FALSE}, depth buffer writing is disabled. Otherwise, it is | |
5084 | enabled. Initially, depth buffer writing is enabled. | |
8925f36f AW |
5085 | |
5086 | @end table | |
5087 | ||
8925f36f | 5088 | @code{glDepthMask} specifies whether the depth buffer is enabled for |
f37e7e3d DH |
5089 | writing. If @var{flag} is @code{GL_FALSE}, depth buffer writing is |
5090 | disabled. Otherwise, it is enabled. Initially, depth buffer writing is | |
8925f36f AW |
5091 | enabled. |
5092 | ||
8925f36f AW |
5093 | @code{GL_INVALID_OPERATION} is generated if @code{glDepthMask} is |
5094 | executed between the execution of @code{glBegin} and the corresponding | |
5095 | execution of @code{glEnd}. | |
5096 | ||
bb894c9d | 5097 | @end deftypefun |
8925f36f | 5098 | |
bb894c9d | 5099 | @deftypefun void glDepthRange nearVal farVal |
3c9b6116 AW |
5100 | Specify mapping of depth values from normalized device coordinates to |
5101 | window coordinates. | |
5102 | ||
8925f36f AW |
5103 | @table @asis |
5104 | @item @var{nearVal} | |
5105 | Specifies the mapping of the near clipping plane to window coordinates. | |
5106 | The initial value is 0. | |
5107 | ||
5108 | @item @var{farVal} | |
5109 | Specifies the mapping of the far clipping plane to window coordinates. | |
5110 | The initial value is 1. | |
5111 | ||
5112 | @end table | |
5113 | ||
8925f36f | 5114 | After clipping and division by @var{w}, depth coordinates range from |
3c9b6116 | 5115 | @r{-1} to 1, corresponding to the near and far clipping planes. |
8925f36f | 5116 | @code{glDepthRange} specifies a linear mapping of the normalized depth |
f37e7e3d DH |
5117 | coordinates in this range to window depth coordinates. Regardless of the |
5118 | actual depth buffer implementation, window coordinate depth values are | |
5119 | treated as though they range from 0 through 1 (like color components). | |
5120 | Thus, the values accepted by @code{glDepthRange} are both clamped to | |
5121 | this range before they are accepted. | |
8925f36f AW |
5122 | |
5123 | The setting of (0,1) maps the near plane to 0 and the far plane to 1. | |
5124 | With this mapping, the depth buffer range is fully utilized. | |
5125 | ||
8925f36f AW |
5126 | @code{GL_INVALID_OPERATION} is generated if @code{glDepthRange} is |
5127 | executed between the execution of @code{glBegin} and the corresponding | |
5128 | execution of @code{glEnd}. | |
5129 | ||
bb894c9d | 5130 | @end deftypefun |
8925f36f | 5131 | |
bb894c9d | 5132 | @deftypefun void glDetachShader program shader |
3c9b6116 AW |
5133 | Detaches a shader object from a program object to which it is attached. |
5134 | ||
8925f36f AW |
5135 | @table @asis |
5136 | @item @var{program} | |
5137 | Specifies the program object from which to detach the shader object. | |
5138 | ||
5139 | @item @var{shader} | |
5140 | Specifies the shader object to be detached. | |
5141 | ||
5142 | @end table | |
5143 | ||
8925f36f | 5144 | @code{glDetachShader} detaches the shader object specified by |
f37e7e3d | 5145 | @var{shader} from the program object specified by @var{program}. This |
8925f36f AW |
5146 | command can be used to undo the effect of the command |
5147 | @code{glAttachShader}. | |
5148 | ||
5149 | If @var{shader} has already been flagged for deletion by a call to | |
5150 | @code{glDeleteShader} and it is not attached to any other program | |
5151 | object, it will be deleted after it has been detached. | |
5152 | ||
8925f36f AW |
5153 | @code{GL_INVALID_VALUE} is generated if either @var{program} or |
5154 | @var{shader} is a value that was not generated by OpenGL. | |
5155 | ||
5156 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
5157 | program object. | |
5158 | ||
5159 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
5160 | object. | |
5161 | ||
5162 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not attached | |
5163 | to @var{program}. | |
5164 | ||
5165 | @code{GL_INVALID_OPERATION} is generated if @code{glDetachShader} is | |
5166 | executed between the execution of @code{glBegin} and the corresponding | |
5167 | execution of @code{glEnd}. | |
5168 | ||
bb894c9d | 5169 | @end deftypefun |
8925f36f | 5170 | |
bb894c9d | 5171 | @deftypefun void glDrawArrays mode first count |
3c9b6116 AW |
5172 | Render primitives from array data. |
5173 | ||
8925f36f AW |
5174 | @table @asis |
5175 | @item @var{mode} | |
f37e7e3d | 5176 | Specifies what kind of primitives to render. Symbolic constants |
8925f36f AW |
5177 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, |
5178 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
5179 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
5180 | @code{GL_POLYGON} are accepted. | |
5181 | ||
5182 | @item @var{first} | |
5183 | Specifies the starting index in the enabled arrays. | |
5184 | ||
5185 | @item @var{count} | |
5186 | Specifies the number of indices to be rendered. | |
5187 | ||
5188 | @end table | |
5189 | ||
8925f36f | 5190 | @code{glDrawArrays} specifies multiple geometric primitives with very |
f37e7e3d | 5191 | few subroutine calls. Instead of calling a GL procedure to pass each |
8925f36f AW |
5192 | individual vertex, normal, texture coordinate, edge flag, or color, you |
5193 | can prespecify separate arrays of vertices, normals, and colors and use | |
5194 | them to construct a sequence of primitives with a single call to | |
5195 | @code{glDrawArrays}. | |
5196 | ||
5197 | When @code{glDrawArrays} is called, it uses @var{count} sequential | |
5198 | elements from each enabled array to construct a sequence of geometric | |
f37e7e3d | 5199 | primitives, beginning with element @var{first}. @var{mode} specifies |
8925f36f | 5200 | what kind of primitives are constructed and how the array elements |
f37e7e3d DH |
5201 | construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, no |
5202 | geometric primitives are generated. | |
8925f36f AW |
5203 | |
5204 | Vertex attributes that are modified by @code{glDrawArrays} have an | |
f37e7e3d | 5205 | unspecified value after @code{glDrawArrays} returns. For example, if |
8925f36f | 5206 | @code{GL_COLOR_ARRAY} is enabled, the value of the current color is |
f37e7e3d | 5207 | undefined after @code{glDrawArrays} executes. Attributes that aren't |
8925f36f AW |
5208 | modified remain well defined. |
5209 | ||
8925f36f AW |
5210 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
5211 | value. | |
5212 | ||
5213 | @code{GL_INVALID_VALUE} is generated if @var{count} is negative. | |
5214 | ||
5215 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5216 | name is bound to an enabled array and the buffer object's data store is | |
5217 | currently mapped. | |
5218 | ||
5219 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawArrays} is | |
5220 | executed between the execution of @code{glBegin} and the corresponding | |
5221 | @code{glEnd}. | |
5222 | ||
bb894c9d | 5223 | @end deftypefun |
8925f36f | 5224 | |
bb894c9d | 5225 | @deftypefun void glDrawBuffers n bufs |
3c9b6116 AW |
5226 | Specifies a list of color buffers to be drawn into. |
5227 | ||
8925f36f AW |
5228 | @table @asis |
5229 | @item @var{n} | |
5230 | Specifies the number of buffers in @var{bufs}. | |
5231 | ||
5232 | @item @var{bufs} | |
5233 | Points to an array of symbolic constants specifying the buffers into | |
5234 | which fragment colors or data values will be written. | |
5235 | ||
5236 | @end table | |
5237 | ||
8925f36f | 5238 | @code{glDrawBuffers} defines an array of buffers into which fragment |
f37e7e3d | 5239 | color values or fragment data will be written. If no fragment shader is |
8925f36f AW |
5240 | active, rendering operations will generate only one fragment color per |
5241 | fragment and it will be written into each of the buffers specified by | |
f37e7e3d | 5242 | @var{bufs}. If a fragment shader is active and it writes a value to the |
8925f36f | 5243 | output variable @code{gl_FragColor}, then that value will be written |
f37e7e3d | 5244 | into each of the buffers specified by @var{bufs}. If a fragment shader |
8925f36f AW |
5245 | is active and it writes a value to one or more elements of the output |
5246 | array variable @code{gl_FragData[]}, then the value of | |
5247 | @code{gl_FragData[0] } will be written into the first buffer specified | |
5248 | by @var{bufs}, the value of @code{gl_FragData[1] } will be written into | |
5249 | the second buffer specified by @var{bufs}, and so on up to | |
f37e7e3d | 5250 | @code{gl_FragData[n-1]}. The draw buffer used for @code{gl_FragData[n]} |
8925f36f AW |
5251 | and beyond is implicitly set to be @code{GL_NONE}. |
5252 | ||
5253 | The symbolic constants contained in @var{bufs} may be any of the | |
5254 | following: | |
5255 | ||
5256 | @table @asis | |
5257 | @item @code{GL_NONE} | |
5258 | The fragment color/data value is not written into any color buffer. | |
5259 | ||
5260 | @item @code{GL_FRONT_LEFT} | |
5261 | The fragment color/data value is written into the front left color | |
5262 | buffer. | |
5263 | ||
5264 | @item @code{GL_FRONT_RIGHT} | |
5265 | The fragment color/data value is written into the front right color | |
5266 | buffer. | |
5267 | ||
5268 | @item @code{GL_BACK_LEFT} | |
5269 | The fragment color/data value is written into the back left color | |
5270 | buffer. | |
5271 | ||
5272 | @item @code{GL_BACK_RIGHT} | |
5273 | The fragment color/data value is written into the back right color | |
5274 | buffer. | |
5275 | ||
5276 | @item @code{GL_AUXi} | |
5277 | The fragment color/data value is written into auxiliary buffer @code{i}. | |
5278 | ||
5279 | @end table | |
5280 | ||
5281 | Except for @code{GL_NONE}, the preceding symbolic constants may not | |
f37e7e3d | 5282 | appear more than once in @var{bufs}. The maximum number of draw buffers |
8925f36f | 5283 | supported is implementation dependent and can be queried by calling |
f37e7e3d DH |
5284 | @code{glGet} with the argument @code{GL_MAX_DRAW_BUFFERS}. The number of |
5285 | auxiliary buffers can be queried by calling @code{glGet} with the | |
8925f36f AW |
5286 | argument @code{GL_AUX_BUFFERS}. |
5287 | ||
8925f36f AW |
5288 | @code{GL_INVALID_ENUM} is generated if one of the values in @var{bufs} |
5289 | is not an accepted value. | |
5290 | ||
5291 | @code{GL_INVALID_ENUM} is generated if @var{n} is less than 0. | |
5292 | ||
5293 | @code{GL_INVALID_OPERATION} is generated if a symbolic constant other | |
5294 | than @code{GL_NONE} appears more than once in @var{bufs}. | |
5295 | ||
5296 | @code{GL_INVALID_OPERATION} is generated if any of the entries in | |
5297 | @var{bufs} (other than @code{GL_NONE} ) indicates a color buffer that | |
5298 | does not exist in the current GL context. | |
5299 | ||
5300 | @code{GL_INVALID_VALUE} is generated if @var{n} is greater than | |
5301 | @code{GL_MAX_DRAW_BUFFERS}. | |
5302 | ||
5303 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffers} is | |
5304 | executed between the execution of @code{glBegin} and the corresponding | |
5305 | execution of @code{glEnd}. | |
5306 | ||
bb894c9d | 5307 | @end deftypefun |
8925f36f | 5308 | |
bb894c9d | 5309 | @deftypefun void glDrawBuffer mode |
3c9b6116 AW |
5310 | Specify which color buffers are to be drawn into. |
5311 | ||
8925f36f AW |
5312 | @table @asis |
5313 | @item @var{mode} | |
f37e7e3d | 5314 | Specifies up to four color buffers to be drawn into. Symbolic constants |
8925f36f AW |
5315 | @code{GL_NONE}, @code{GL_FRONT_LEFT}, @code{GL_FRONT_RIGHT}, |
5316 | @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT}, @code{GL_FRONT}, | |
5317 | @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT}, | |
5318 | @code{GL_FRONT_AND_BACK}, and @code{GL_AUX}@var{i}, where @var{i} is | |
5319 | between 0 and the value of @code{GL_AUX_BUFFERS} minus 1, are accepted. | |
5320 | (@code{GL_AUX_BUFFERS} is not the upper limit; use @code{glGet} to query | |
5321 | the number of available aux buffers.) The initial value is | |
5322 | @code{GL_FRONT} for single-buffered contexts, and @code{GL_BACK} for | |
5323 | double-buffered contexts. | |
5324 | ||
5325 | @end table | |
5326 | ||
8925f36f | 5327 | When colors are written to the frame buffer, they are written into the |
f37e7e3d | 5328 | color buffers specified by @code{glDrawBuffer}. The specifications are |
8925f36f AW |
5329 | as follows: |
5330 | ||
5331 | @table @asis | |
5332 | @item @code{GL_NONE} | |
5333 | No color buffers are written. | |
5334 | ||
5335 | @item @code{GL_FRONT_LEFT} | |
5336 | Only the front left color buffer is written. | |
5337 | ||
5338 | @item @code{GL_FRONT_RIGHT} | |
5339 | Only the front right color buffer is written. | |
5340 | ||
5341 | @item @code{GL_BACK_LEFT} | |
5342 | Only the back left color buffer is written. | |
5343 | ||
5344 | @item @code{GL_BACK_RIGHT} | |
5345 | Only the back right color buffer is written. | |
5346 | ||
5347 | @item @code{GL_FRONT} | |
f37e7e3d | 5348 | Only the front left and front right color buffers are written. If there |
8925f36f AW |
5349 | is no front right color buffer, only the front left color buffer is |
5350 | written. | |
5351 | ||
5352 | @item @code{GL_BACK} | |
f37e7e3d DH |
5353 | Only the back left and back right color buffers are written. If there is |
5354 | no back right color buffer, only the back left color buffer is written. | |
8925f36f AW |
5355 | |
5356 | @item @code{GL_LEFT} | |
f37e7e3d DH |
5357 | Only the front left and back left color buffers are written. If there is |
5358 | no back left color buffer, only the front left color buffer is written. | |
8925f36f AW |
5359 | |
5360 | @item @code{GL_RIGHT} | |
f37e7e3d | 5361 | Only the front right and back right color buffers are written. If there |
8925f36f AW |
5362 | is no back right color buffer, only the front right color buffer is |
5363 | written. | |
5364 | ||
5365 | @item @code{GL_FRONT_AND_BACK} | |
5366 | All the front and back color buffers (front left, front right, back | |
f37e7e3d DH |
5367 | left, back right) are written. If there are no back color buffers, only |
5368 | the front left and front right color buffers are written. If there are | |
8925f36f | 5369 | no right color buffers, only the front left and back left color buffers |
f37e7e3d DH |
5370 | are written. If there are no right or back color buffers, only the front |
5371 | left color buffer is written. | |
8925f36f AW |
5372 | |
5373 | @item @code{GL_AUX}@var{i} | |
5374 | Only auxiliary color buffer @var{i} is written. | |
5375 | ||
5376 | @end table | |
5377 | ||
5378 | If more than one color buffer is selected for drawing, then blending or | |
5379 | logical operations are computed and applied independently for each color | |
5380 | buffer and can produce different results in each buffer. | |
5381 | ||
5382 | Monoscopic contexts include only @var{left} buffers, and stereoscopic | |
f37e7e3d | 5383 | contexts include both @var{left} and @var{right} buffers. Likewise, |
8925f36f AW |
5384 | single-buffered contexts include only @var{front} buffers, and |
5385 | double-buffered contexts include both @var{front} and @var{back} | |
f37e7e3d | 5386 | buffers. The context is selected at GL initialization. |
8925f36f | 5387 | |
8925f36f AW |
5388 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
5389 | value. | |
5390 | ||
5391 | @code{GL_INVALID_OPERATION} is generated if none of the buffers | |
5392 | indicated by @var{mode} exists. | |
5393 | ||
5394 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffer} is | |
5395 | executed between the execution of @code{glBegin} and the corresponding | |
5396 | execution of @code{glEnd}. | |
5397 | ||
bb894c9d | 5398 | @end deftypefun |
8925f36f | 5399 | |
bb894c9d | 5400 | @deftypefun void glDrawElements mode count type indices |
3c9b6116 AW |
5401 | Render primitives from array data. |
5402 | ||
8925f36f AW |
5403 | @table @asis |
5404 | @item @var{mode} | |
f37e7e3d | 5405 | Specifies what kind of primitives to render. Symbolic constants |
8925f36f AW |
5406 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, |
5407 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
5408 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
5409 | @code{GL_POLYGON} are accepted. | |
5410 | ||
5411 | @item @var{count} | |
5412 | Specifies the number of elements to be rendered. | |
5413 | ||
5414 | @item @var{type} | |
f37e7e3d | 5415 | Specifies the type of the values in @var{indices}. Must be one of |
8925f36f AW |
5416 | @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or |
5417 | @code{GL_UNSIGNED_INT}. | |
5418 | ||
5419 | @item @var{indices} | |
5420 | Specifies a pointer to the location where the indices are stored. | |
5421 | ||
5422 | @end table | |
5423 | ||
8925f36f | 5424 | @code{glDrawElements} specifies multiple geometric primitives with very |
f37e7e3d | 5425 | few subroutine calls. Instead of calling a GL function to pass each |
8925f36f AW |
5426 | individual vertex, normal, texture coordinate, edge flag, or color, you |
5427 | can prespecify separate arrays of vertices, normals, and so on, and use | |
5428 | them to construct a sequence of primitives with a single call to | |
5429 | @code{glDrawElements}. | |
5430 | ||
5431 | When @code{glDrawElements} is called, it uses @var{count} sequential | |
5432 | elements from an enabled array, starting at @var{indices} to construct a | |
f37e7e3d | 5433 | sequence of geometric primitives. @var{mode} specifies what kind of |
8925f36f | 5434 | primitives are constructed and how the array elements construct these |
f37e7e3d | 5435 | primitives. If more than one array is enabled, each is used. If |
8925f36f AW |
5436 | @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are |
5437 | constructed. | |
5438 | ||
5439 | Vertex attributes that are modified by @code{glDrawElements} have an | |
f37e7e3d | 5440 | unspecified value after @code{glDrawElements} returns. For example, if |
8925f36f | 5441 | @code{GL_COLOR_ARRAY} is enabled, the value of the current color is |
f37e7e3d | 5442 | undefined after @code{glDrawElements} executes. Attributes that aren't |
8925f36f AW |
5443 | modified maintain their previous values. |
5444 | ||
8925f36f AW |
5445 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
5446 | value. | |
5447 | ||
5448 | @code{GL_INVALID_VALUE} is generated if @var{count} is negative. | |
5449 | ||
5450 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5451 | name is bound to an enabled array or the element array and the buffer | |
5452 | object's data store is currently mapped. | |
5453 | ||
5454 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawElements} is | |
5455 | executed between the execution of @code{glBegin} and the corresponding | |
5456 | @code{glEnd}. | |
5457 | ||
bb894c9d | 5458 | @end deftypefun |
8925f36f | 5459 | |
bb894c9d | 5460 | @deftypefun void glDrawPixels width height format type data |
3c9b6116 AW |
5461 | Write a block of pixels to the frame buffer. |
5462 | ||
8925f36f AW |
5463 | @table @asis |
5464 | @item @var{width} | |
5465 | @itemx @var{height} | |
5466 | Specify the dimensions of the pixel rectangle to be written into the | |
5467 | frame buffer. | |
5468 | ||
5469 | @item @var{format} | |
f37e7e3d | 5470 | Specifies the format of the pixel data. Symbolic constants |
8925f36f AW |
5471 | @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, |
5472 | @code{GL_DEPTH_COMPONENT}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, | |
5473 | @code{GL_BGRA}, @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, | |
5474 | @code{GL_ALPHA}, @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA} are | |
5475 | accepted. | |
5476 | ||
5477 | @item @var{type} | |
f37e7e3d | 5478 | Specifies the data type for @var{data}. Symbolic constants |
8925f36f AW |
5479 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
5480 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
5481 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
5482 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
5483 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
5484 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
5485 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
5486 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
5487 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
5488 | ||
5489 | @item @var{data} | |
5490 | Specifies a pointer to the pixel data. | |
5491 | ||
5492 | @end table | |
5493 | ||
8925f36f AW |
5494 | @code{glDrawPixels} reads pixel data from memory and writes it into the |
5495 | frame buffer relative to the current raster position, provided that the | |
f37e7e3d | 5496 | raster position is valid. Use @code{glRasterPos} or @code{glWindowPos} |
8925f36f AW |
5497 | to set the current raster position; use @code{glGet} with argument |
5498 | @code{GL_CURRENT_RASTER_POSITION_VALID} to determine if the specified | |
5499 | raster position is valid, and @code{glGet} with argument | |
5500 | @code{GL_CURRENT_RASTER_POSITION} to query the raster position. | |
5501 | ||
5502 | Several parameters define the encoding of pixel data in memory and | |
5503 | control the processing of the pixel data before it is placed in the | |
f37e7e3d | 5504 | frame buffer. These parameters are set with four commands: |
8925f36f | 5505 | @code{glPixelStore}, @code{glPixelTransfer}, @code{glPixelMap}, and |
f37e7e3d | 5506 | @code{glPixelZoom}. This reference page describes the effects on |
8925f36f AW |
5507 | @code{glDrawPixels} of many, but not all, of the parameters specified by |
5508 | these four commands. | |
5509 | ||
5510 | Data is read from @var{data} as a sequence of signed or unsigned bytes, | |
5511 | signed or unsigned shorts, signed or unsigned integers, or | |
f37e7e3d | 5512 | single-precision floating-point values, depending on @var{type}. When |
8925f36f AW |
5513 | @var{type} is one of @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, |
5514 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
5515 | @code{GL_INT}, or @code{GL_FLOAT} each of these bytes, shorts, integers, | |
5516 | or floating-point values is interpreted as one color or depth component, | |
f37e7e3d | 5517 | or one index, depending on @var{format}. When @var{type} is one of |
8925f36f AW |
5518 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_SHORT_5_6_5}, |
5519 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
5520 | @code{GL_UNSIGNED_INT_8_8_8_8}, or @code{GL_UNSIGNED_INT_10_10_10_2}, | |
5521 | each unsigned value is interpreted as containing all the components for | |
5522 | a single pixel, with the color components arranged according to | |
f37e7e3d | 5523 | @var{format}. When @var{type} is one of |
8925f36f AW |
5524 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, |
5525 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
5526 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
5527 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, or | |
5528 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}, each unsigned value is | |
5529 | interpreted as containing all color components, specified by | |
f37e7e3d DH |
5530 | @var{format}, for a single pixel in a reversed order. Indices are always |
5531 | treated individually. Color components are treated as groups of one, | |
5532 | two, three, or four values, again based on @var{format}. Both individual | |
5533 | indices and groups of components are referred to as pixels. If | |
5534 | @var{type} is @code{GL_BITMAP}, the data must be unsigned bytes, and | |
8925f36f | 5535 | @var{format} must be either @code{GL_COLOR_INDEX} or |
f37e7e3d | 5536 | @code{GL_STENCIL_INDEX}. Each unsigned byte is treated as eight 1-bit |
8925f36f AW |
5537 | pixels, with bit ordering determined by @code{GL_UNPACK_LSB_FIRST} (see |
5538 | @code{glPixelStore}). | |
5539 | ||
3c9b6116 | 5540 | @r{@var{width}×@var{height}} pixels are read from memory, starting at |
f37e7e3d | 5541 | location @var{data}. By default, these pixels are taken from adjacent |
8925f36f | 5542 | memory locations, except that after all @var{width} pixels are read, the |
f37e7e3d | 5543 | read pointer is advanced to the next four-byte boundary. The four-byte |
8925f36f AW |
5544 | row alignment is specified by @code{glPixelStore} with argument |
5545 | @code{GL_UNPACK_ALIGNMENT}, and it can be set to one, two, four, or | |
f37e7e3d DH |
5546 | eight bytes. Other pixel store parameters specify different read pointer |
5547 | advancements, both before the first pixel is read and after all | |
5548 | @var{width} pixels are read. See the @code{glPixelStore} reference page | |
8925f36f AW |
5549 | for details on these options. |
5550 | ||
5551 | If a non-zero named buffer object is bound to the | |
5552 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
5553 | block of pixels is specified, @var{data} is treated as a byte offset | |
5554 | into the buffer object's data store. | |
5555 | ||
3c9b6116 | 5556 | The @r{@var{width}×@var{height}} pixels that are read from memory are |
8925f36f AW |
5557 | each operated on in the same way, based on the values of several |
5558 | parameters specified by @code{glPixelTransfer} and @code{glPixelMap}. | |
5559 | The details of these operations, as well as the target buffer into which | |
5560 | the pixels are drawn, are specific to the format of the pixels, as | |
f37e7e3d | 5561 | specified by @var{format}. @var{format} can assume one of 13 symbolic |
8925f36f AW |
5562 | values: |
5563 | ||
5564 | @table @asis | |
5565 | @item @code{GL_COLOR_INDEX} | |
f37e7e3d | 5566 | Each pixel is a single value, a color index. It is converted to |
8925f36f | 5567 | fixed-point format, with an unspecified number of bits to the right of |
f37e7e3d DH |
5568 | the binary point, regardless of the memory data type. Floating-point |
5569 | values convert to true fixed-point values. Signed and unsigned integer | |
5570 | data is converted with all fraction bits set to 0. Bitmap data convert | |
8925f36f AW |
5571 | to either 0 or 1. |
5572 | ||
5573 | Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT} | |
f37e7e3d DH |
5574 | bits and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is |
5575 | negative, the shift is to the right. In either case, zero bits fill | |
8925f36f AW |
5576 | otherwise unspecified bit locations in the result. |
5577 | ||
5578 | If the GL is in RGBA mode, the resulting index is converted to an RGBA | |
5579 | pixel with the help of the @code{GL_PIXEL_MAP_I_TO_R}, | |
5580 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
f37e7e3d DH |
5581 | @code{GL_PIXEL_MAP_I_TO_A} tables. If the GL is in color index mode, and |
5582 | if @code{GL_MAP_COLOR} is true, the index is replaced with the value | |
5583 | that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether | |
8925f36f | 5584 | the lookup replacement of the index is done or not, the integer part of |
3c9b6116 AW |
5585 | the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
5586 | number of bits in a color index buffer. | |
8925f36f AW |
5587 | |
5588 | The GL then converts the resulting indices or RGBA colors to fragments | |
5589 | by attaching the current raster position @var{z} coordinate and texture | |
3c9b6116 AW |
5590 | coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}} |
5591 | window coordinates to the @r{@var{n}}th fragment such that | |
5592 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} | |
8925f36f | 5593 | |
3c9b6116 | 5594 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
f37e7e3d DH |
5595 | position. These pixel fragments are then treated just like the fragments |
5596 | generated by rasterizing points, lines, or polygons. Texture mapping, | |
5597 | fog, and all the fragment operations are applied before the fragments | |
5598 | are written to the frame buffer. | |
8925f36f AW |
5599 | |
5600 | @item @code{GL_STENCIL_INDEX} | |
f37e7e3d | 5601 | Each pixel is a single value, a stencil index. It is converted to |
8925f36f | 5602 | fixed-point format, with an unspecified number of bits to the right of |
f37e7e3d DH |
5603 | the binary point, regardless of the memory data type. Floating-point |
5604 | values convert to true fixed-point values. Signed and unsigned integer | |
5605 | data is converted with all fraction bits set to 0. Bitmap data convert | |
8925f36f AW |
5606 | to either 0 or 1. |
5607 | ||
5608 | Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT} | |
f37e7e3d DH |
5609 | bits, and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is |
5610 | negative, the shift is to the right. In either case, zero bits fill | |
5611 | otherwise unspecified bit locations in the result. If | |
8925f36f | 5612 | @code{GL_MAP_STENCIL} is true, the index is replaced with the value that |
f37e7e3d | 5613 | it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether the |
8925f36f | 5614 | lookup replacement of the index is done or not, the integer part of the |
3c9b6116 | 5615 | index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
f37e7e3d | 5616 | number of bits in the stencil buffer. The resulting stencil indices are |
3c9b6116 AW |
5617 | then written to the stencil buffer such that the @r{@var{n}}th index is |
5618 | written to location | |
8925f36f | 5619 | |
3c9b6116 | 5620 | @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 | 5621 | |
3c9b6116 | 5622 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
f37e7e3d | 5623 | position. Only the pixel ownership test, the scissor test, and the |
8925f36f AW |
5624 | stencil writemask affect these write operations. |
5625 | ||
5626 | @item @code{GL_DEPTH_COMPONENT} | |
f37e7e3d DH |
5627 | Each pixel is a single-depth component. Floating-point data is converted |
5628 | directly to an internal floating-point format with unspecified | |
5629 | precision. Signed integer data is mapped linearly to the internal | |
8925f36f AW |
5630 | floating-point format such that the most positive representable integer |
5631 | value maps to 1.0, and the most negative representable value maps to | |
f37e7e3d DH |
5632 | @r{-1.0}. Unsigned integer data is mapped similarly: the largest integer |
5633 | value maps to 1.0, and 0 maps to 0.0. The resulting floating-point depth | |
5634 | value is then multiplied by @code{GL_DEPTH_SCALE} and added to | |
5635 | @code{GL_DEPTH_BIAS}. The result is clamped to the range @r{[0,1]}. | |
8925f36f AW |
5636 | |
5637 | The GL then converts the resulting depth components to fragments by | |
5638 | attaching the current raster position color or color index and texture | |
3c9b6116 AW |
5639 | coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}} |
5640 | window coordinates to the @r{@var{n}}th fragment such that | |
8925f36f | 5641 | |
3c9b6116 | 5642 | @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 | 5643 | |
3c9b6116 | 5644 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
f37e7e3d DH |
5645 | position. These pixel fragments are then treated just like the fragments |
5646 | generated by rasterizing points, lines, or polygons. Texture mapping, | |
5647 | fog, and all the fragment operations are applied before the fragments | |
5648 | are written to the frame buffer. | |
8925f36f AW |
5649 | |
5650 | @item @code{GL_RGBA} | |
5651 | @item @code{GL_BGRA} | |
5652 | Each pixel is a four-component group: For @code{GL_RGBA}, the red | |
5653 | component is first, followed by green, followed by blue, followed by | |
5654 | alpha; for @code{GL_BGRA} the order is blue, green, red and then alpha. | |
5655 | Floating-point values are converted directly to an internal | |
f37e7e3d | 5656 | floating-point format with unspecified precision. Signed integer values |
8925f36f AW |
5657 | are mapped linearly to the internal floating-point format such that the |
5658 | most positive representable integer value maps to 1.0, and the most | |
f37e7e3d | 5659 | negative representable value maps to @r{-1.0}. (Note that this mapping |
3c9b6116 | 5660 | does not convert 0 precisely to 0.0.) Unsigned integer data is mapped |
f37e7e3d | 5661 | similarly: The largest integer value maps to 1.0, and 0 maps to 0.0. The |
3c9b6116 | 5662 | resulting floating-point color values are then multiplied by |
8925f36f | 5663 | @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED, |
f37e7e3d | 5664 | GREEN, BLUE, and ALPHA for the respective color components. The results |
3c9b6116 | 5665 | are clamped to the range @r{[0,1]}. |
8925f36f AW |
5666 | |
5667 | If @code{GL_MAP_COLOR} is true, each color component is scaled by the | |
5668 | size of lookup table @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the | |
f37e7e3d | 5669 | value that it references in that table. @var{c} is R, G, B, or A |
8925f36f AW |
5670 | respectively. |
5671 | ||
5672 | The GL then converts the resulting RGBA colors to fragments by attaching | |
5673 | the current raster position @var{z} coordinate and texture coordinates | |
3c9b6116 AW |
5674 | to each pixel, then assigning @r{@var{x}} and @r{@var{y}} window |
5675 | coordinates to the @r{@var{n}}th fragment such that | |
8925f36f | 5676 | |
3c9b6116 | 5677 | @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 | 5678 | |
3c9b6116 | 5679 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
f37e7e3d DH |
5680 | position. These pixel fragments are then treated just like the fragments |
5681 | generated by rasterizing points, lines, or polygons. Texture mapping, | |
5682 | fog, and all the fragment operations are applied before the fragments | |
5683 | are written to the frame buffer. | |
8925f36f AW |
5684 | |
5685 | @item @code{GL_RED} | |
f37e7e3d DH |
5686 | Each pixel is a single red component. This component is converted to the |
5687 | internal floating-point format in the same way the red component of an | |
5688 | RGBA pixel is. It is then converted to an RGBA pixel with green and blue | |
5689 | set to 0, and alpha set to 1. After this conversion, the pixel is | |
8925f36f AW |
5690 | treated as if it had been read as an RGBA pixel. |
5691 | ||
5692 | @item @code{GL_GREEN} | |
f37e7e3d | 5693 | Each pixel is a single green component. This component is converted to |
8925f36f | 5694 | the internal floating-point format in the same way the green component |
f37e7e3d DH |
5695 | of an RGBA pixel is. It is then converted to an RGBA pixel with red and |
5696 | blue set to 0, and alpha set to 1. After this conversion, the pixel is | |
8925f36f AW |
5697 | treated as if it had been read as an RGBA pixel. |
5698 | ||
5699 | @item @code{GL_BLUE} | |
f37e7e3d | 5700 | Each pixel is a single blue component. This component is converted to |
8925f36f | 5701 | the internal floating-point format in the same way the blue component of |
f37e7e3d DH |
5702 | an RGBA pixel is. It is then converted to an RGBA pixel with red and |
5703 | green set to 0, and alpha set to 1. After this conversion, the pixel is | |
8925f36f AW |
5704 | treated as if it had been read as an RGBA pixel. |
5705 | ||
5706 | @item @code{GL_ALPHA} | |
f37e7e3d | 5707 | Each pixel is a single alpha component. This component is converted to |
8925f36f | 5708 | the internal floating-point format in the same way the alpha component |
f37e7e3d DH |
5709 | of an RGBA pixel is. It is then converted to an RGBA pixel with red, |
5710 | green, and blue set to 0. After this conversion, the pixel is treated as | |
5711 | if it had been read as an RGBA pixel. | |
8925f36f AW |
5712 | |
5713 | @item @code{GL_RGB} | |
5714 | @item @code{GL_BGR} | |
5715 | Each pixel is a three-component group: red first, followed by green, | |
5716 | followed by blue; for @code{GL_BGR}, the first component is blue, | |
f37e7e3d | 5717 | followed by green and then red. Each component is converted to the |
8925f36f | 5718 | internal floating-point format in the same way the red, green, and blue |
f37e7e3d DH |
5719 | components of an RGBA pixel are. The color triple is converted to an |
5720 | RGBA pixel with alpha set to 1. After this conversion, the pixel is | |
8925f36f AW |
5721 | treated as if it had been read as an RGBA pixel. |
5722 | ||
5723 | @item @code{GL_LUMINANCE} | |
f37e7e3d | 5724 | Each pixel is a single luminance component. This component is converted |
8925f36f | 5725 | to the internal floating-point format in the same way the red component |
f37e7e3d | 5726 | of an RGBA pixel is. It is then converted to an RGBA pixel with red, |
8925f36f | 5727 | green, and blue set to the converted luminance value, and alpha set to |
f37e7e3d DH |
5728 | 1. After this conversion, the pixel is treated as if it had been read as |
5729 | an RGBA pixel. | |
8925f36f AW |
5730 | |
5731 | @item @code{GL_LUMINANCE_ALPHA} | |
5732 | Each pixel is a two-component group: luminance first, followed by alpha. | |
5733 | The two components are converted to the internal floating-point format | |
f37e7e3d | 5734 | in the same way the red component of an RGBA pixel is. They are then |
8925f36f AW |
5735 | converted to an RGBA pixel with red, green, and blue set to the |
5736 | converted luminance value, and alpha set to the converted alpha value. | |
5737 | After this conversion, the pixel is treated as if it had been read as an | |
5738 | RGBA pixel. | |
5739 | ||
5740 | @end table | |
5741 | ||
5742 | The following table summarizes the meaning of the valid constants for | |
5743 | the @var{type} parameter: | |
5744 | ||
5745 | ||
5746 | ||
5747 | @table @asis | |
5748 | @item @strong{Type} | |
5749 | @strong{Corresponding Type} | |
5750 | ||
5751 | @item @code{GL_UNSIGNED_BYTE} | |
5752 | unsigned 8-bit integer | |
5753 | ||
5754 | @item @code{GL_BYTE} | |
5755 | signed 8-bit integer | |
5756 | ||
5757 | @item @code{GL_BITMAP} | |
5758 | single bits in unsigned 8-bit integers | |
5759 | ||
5760 | @item @code{GL_UNSIGNED_SHORT} | |
5761 | unsigned 16-bit integer | |
5762 | ||
5763 | @item @code{GL_SHORT} | |
5764 | signed 16-bit integer | |
5765 | ||
5766 | @item @code{GL_UNSIGNED_INT} | |
5767 | unsigned 32-bit integer | |
5768 | ||
5769 | @item @code{GL_INT} | |
5770 | 32-bit integer | |
5771 | ||
5772 | @item @code{GL_FLOAT} | |
5773 | single-precision floating-point | |
5774 | ||
5775 | @item @code{GL_UNSIGNED_BYTE_3_3_2} | |
5776 | unsigned 8-bit integer | |
5777 | ||
5778 | @item @code{GL_UNSIGNED_BYTE_2_3_3_REV} | |
5779 | unsigned 8-bit integer with reversed component ordering | |
5780 | ||
5781 | @item @code{GL_UNSIGNED_SHORT_5_6_5} | |
5782 | unsigned 16-bit integer | |
5783 | ||
5784 | @item @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
5785 | unsigned 16-bit integer with reversed component ordering | |
5786 | ||
5787 | @item @code{GL_UNSIGNED_SHORT_4_4_4_4} | |
5788 | unsigned 16-bit integer | |
5789 | ||
5790 | @item @code{GL_UNSIGNED_SHORT_4_4_4_4_REV} | |
5791 | unsigned 16-bit integer with reversed component ordering | |
5792 | ||
5793 | @item @code{GL_UNSIGNED_SHORT_5_5_5_1} | |
5794 | unsigned 16-bit integer | |
5795 | ||
5796 | @item @code{GL_UNSIGNED_SHORT_1_5_5_5_REV} | |
5797 | unsigned 16-bit integer with reversed component ordering | |
5798 | ||
5799 | @item @code{GL_UNSIGNED_INT_8_8_8_8} | |
5800 | unsigned 32-bit integer | |
5801 | ||
5802 | @item @code{GL_UNSIGNED_INT_8_8_8_8_REV} | |
5803 | unsigned 32-bit integer with reversed component ordering | |
5804 | ||
5805 | @item @code{GL_UNSIGNED_INT_10_10_10_2} | |
5806 | unsigned 32-bit integer | |
5807 | ||
5808 | @item @code{GL_UNSIGNED_INT_2_10_10_10_REV} | |
5809 | unsigned 32-bit integer with reversed component ordering | |
5810 | ||
5811 | @end table | |
5812 | ||
5813 | ||
5814 | ||
f37e7e3d | 5815 | The rasterization described so far assumes pixel zoom factors of 1. If |
3c9b6116 | 5816 | @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}} |
f37e7e3d | 5817 | pixel zoom factors, pixels are converted to fragments as follows. If |
3c9b6116 AW |
5818 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, |
5819 | and a given pixel is in the @r{@var{n}}th column and @r{@var{m}}th row | |
5820 | of the pixel rectangle, then fragments are generated for pixels whose | |
5821 | centers are in the rectangle with corners at | |
8925f36f | 5822 | |
3c9b6116 | 5823 | @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 | 5824 | |
3c9b6116 AW |
5825 | where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and |
5826 | @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}. | |
8925f36f | 5827 | |
8925f36f AW |
5828 | @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not |
5829 | one of the accepted values. | |
5830 | ||
5831 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
5832 | and @var{format} is not either @code{GL_COLOR_INDEX} or | |
5833 | @code{GL_STENCIL_INDEX}. | |
5834 | ||
5835 | @code{GL_INVALID_VALUE} is generated if either @var{width} or | |
5836 | @var{height} is negative. | |
5837 | ||
5838 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
5839 | @code{GL_STENCIL_INDEX} and there is no stencil buffer. | |
5840 | ||
5841 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
5842 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
5843 | @code{GL_RGB}, @code{GL_RGBA}, @code{GL_BGR}, @code{GL_BGRA}, | |
5844 | @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}, and the GL is in | |
5845 | color index mode. | |
5846 | ||
5847 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
5848 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
5849 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
5850 | and @var{format} is not @code{GL_RGB}. | |
5851 | ||
5852 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
5853 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
5854 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
5855 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
5856 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
5857 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
5858 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
5859 | ||
5860 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5861 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
5862 | object's data store is currently mapped. | |
5863 | ||
5864 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5865 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
5866 | would be unpacked from the buffer object such that the memory reads | |
5867 | required would exceed the data store size. | |
5868 | ||
5869 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5870 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
5871 | is not evenly divisible into the number of bytes needed to store in | |
5872 | memory a datum indicated by @var{type}. | |
5873 | ||
5874 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawPixels} is | |
5875 | executed between the execution of @code{glBegin} and the corresponding | |
5876 | execution of @code{glEnd}. | |
5877 | ||
bb894c9d | 5878 | @end deftypefun |
8925f36f | 5879 | |
bb894c9d | 5880 | @deftypefun void glDrawRangeElements mode start end count type indices |
3c9b6116 AW |
5881 | Render primitives from array data. |
5882 | ||
8925f36f AW |
5883 | @table @asis |
5884 | @item @var{mode} | |
f37e7e3d | 5885 | Specifies what kind of primitives to render. Symbolic constants |
8925f36f AW |
5886 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, |
5887 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
5888 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
5889 | @code{GL_POLYGON} are accepted. | |
5890 | ||
5891 | @item @var{start} | |
5892 | Specifies the minimum array index contained in @var{indices}. | |
5893 | ||
5894 | @item @var{end} | |
5895 | Specifies the maximum array index contained in @var{indices}. | |
5896 | ||
5897 | @item @var{count} | |
5898 | Specifies the number of elements to be rendered. | |
5899 | ||
5900 | @item @var{type} | |
f37e7e3d | 5901 | Specifies the type of the values in @var{indices}. Must be one of |
8925f36f AW |
5902 | @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or |
5903 | @code{GL_UNSIGNED_INT}. | |
5904 | ||
5905 | @item @var{indices} | |
5906 | Specifies a pointer to the location where the indices are stored. | |
5907 | ||
5908 | @end table | |
5909 | ||
8925f36f | 5910 | @code{glDrawRangeElements} is a restricted form of |
f37e7e3d | 5911 | @code{glDrawElements}. @var{mode}, @var{start}, @var{end}, and |
8925f36f AW |
5912 | @var{count} match the corresponding arguments to @code{glDrawElements}, |
5913 | with the additional constraint that all values in the arrays @var{count} | |
5914 | must lie between @var{start} and @var{end}, inclusive. | |
5915 | ||
5916 | Implementations denote recommended maximum amounts of vertex and index | |
5917 | data, which may be queried by calling @code{glGet} with argument | |
f37e7e3d | 5918 | @code{GL_MAX_ELEMENTS_VERTICES} and @code{GL_MAX_ELEMENTS_INDICES}. If |
3c9b6116 | 5919 | @r{@var{end}-@var{start}+1} is greater than the value of |
8925f36f AW |
5920 | @code{GL_MAX_ELEMENTS_VERTICES}, or if @var{count} is greater than the |
5921 | value of @code{GL_MAX_ELEMENTS_INDICES}, then the call may operate at | |
f37e7e3d DH |
5922 | reduced performance. There is no requirement that all vertices in the |
5923 | range @r{[@var{start},@var{end}]} be referenced. However, the | |
8925f36f AW |
5924 | implementation may partially process unused vertices, reducing |
5925 | performance from what could be achieved with an optimal index set. | |
5926 | ||
5927 | When @code{glDrawRangeElements} is called, it uses @var{count} | |
5928 | sequential elements from an enabled array, starting at @var{start} to | |
f37e7e3d | 5929 | construct a sequence of geometric primitives. @var{mode} specifies what |
8925f36f | 5930 | kind of primitives are constructed, and how the array elements construct |
f37e7e3d | 5931 | these primitives. If more than one array is enabled, each is used. If |
8925f36f AW |
5932 | @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are |
5933 | constructed. | |
5934 | ||
5935 | Vertex attributes that are modified by @code{glDrawRangeElements} have | |
f37e7e3d | 5936 | an unspecified value after @code{glDrawRangeElements} returns. For |
8925f36f | 5937 | example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current |
f37e7e3d | 5938 | color is undefined after @code{glDrawRangeElements} executes. Attributes |
8925f36f AW |
5939 | that aren't modified maintain their previous values. |
5940 | ||
8925f36f | 5941 | It is an error for indices to lie outside the range |
3c9b6116 | 5942 | @r{[@var{start},@var{end}]}, but implementations may not check for this |
f37e7e3d | 5943 | situation. Such indices cause implementation-dependent behavior. |
8925f36f AW |
5944 | |
5945 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted | |
5946 | value. | |
5947 | ||
5948 | @code{GL_INVALID_VALUE} is generated if @var{count} is negative. | |
5949 | ||
3c9b6116 | 5950 | @code{GL_INVALID_VALUE} is generated if @r{@var{end}<@var{start}}. |
8925f36f AW |
5951 | |
5952 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5953 | name is bound to an enabled array or the element array and the buffer | |
5954 | object's data store is currently mapped. | |
5955 | ||
5956 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawRangeElements} | |
5957 | is executed between the execution of @code{glBegin} and the | |
5958 | corresponding @code{glEnd}. | |
5959 | ||
bb894c9d | 5960 | @end deftypefun |
8925f36f | 5961 | |
bb894c9d | 5962 | @deftypefun void glEdgeFlagPointer stride pointer |
3c9b6116 AW |
5963 | Define an array of edge flags. |
5964 | ||
8925f36f AW |
5965 | @table @asis |
5966 | @item @var{stride} | |
f37e7e3d | 5967 | Specifies the byte offset between consecutive edge flags. If |
8925f36f | 5968 | @var{stride} is 0, the edge flags are understood to be tightly packed in |
f37e7e3d | 5969 | the array. The initial value is 0. |
8925f36f AW |
5970 | |
5971 | @item @var{pointer} | |
f37e7e3d | 5972 | Specifies a pointer to the first edge flag in the array. The initial |
8925f36f AW |
5973 | value is 0. |
5974 | ||
5975 | @end table | |
5976 | ||
8925f36f | 5977 | @code{glEdgeFlagPointer} specifies the location and data format of an |
f37e7e3d | 5978 | array of boolean edge flags to use when rendering. @var{stride} |
8925f36f AW |
5979 | specifies the byte stride from one edge flag to the next, allowing |
5980 | vertices and attributes to be packed into a single array or stored in | |
5981 | separate arrays. | |
5982 | ||
5983 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
5984 | target (see @code{glBindBuffer}) while an edge flag array is specified, | |
5985 | @var{pointer} is treated as a byte offset into the buffer object's data | |
f37e7e3d | 5986 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) |
8925f36f AW |
5987 | is saved as edge flag vertex array client-side state |
5988 | (@code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING}). | |
5989 | ||
5990 | When an edge flag array is specified, @var{stride} and @var{pointer} are | |
5991 | saved as client-side state, in addition to the current vertex array | |
5992 | buffer object binding. | |
5993 | ||
5994 | To enable and disable the edge flag array, call | |
5995 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
f37e7e3d | 5996 | argument @code{GL_EDGE_FLAG_ARRAY}. If enabled, the edge flag array is |
8925f36f AW |
5997 | used when @code{glDrawArrays}, @code{glMultiDrawArrays}, |
5998 | @code{glDrawElements}, @code{glMultiDrawElements}, | |
5999 | @code{glDrawRangeElements}, or @code{glArrayElement} is called. | |
6000 | ||
8925f36f AW |
6001 | @code{GL_INVALID_ENUM} is generated if @var{stride} is negative. |
6002 | ||
bb894c9d | 6003 | @end deftypefun |
8925f36f | 6004 | |
bb894c9d | 6005 | @deftypefun void glEdgeFlag flag |
d172eed9 | 6006 | @deftypefunx void glEdgeFlagv flag |
3c9b6116 AW |
6007 | Flag edges as either boundary or nonboundary. |
6008 | ||
8925f36f AW |
6009 | @table @asis |
6010 | @item @var{flag} | |
6011 | Specifies the current edge flag value, either @code{GL_TRUE} or | |
f37e7e3d | 6012 | @code{GL_FALSE}. The initial value is @code{GL_TRUE}. |
8925f36f AW |
6013 | |
6014 | @end table | |
6015 | ||
8925f36f AW |
6016 | Each vertex of a polygon, separate triangle, or separate quadrilateral |
6017 | specified between a @code{glBegin}/@code{glEnd} pair is marked as the | |
f37e7e3d DH |
6018 | start of either a boundary or nonboundary edge. If the current edge flag |
6019 | is true when the vertex is specified, the vertex is marked as the start | |
6020 | of a boundary edge. Otherwise, the vertex is marked as the start of a | |
6021 | nonboundary edge. @code{glEdgeFlag} sets the edge flag bit to | |
8925f36f AW |
6022 | @code{GL_TRUE} if @var{flag} is @code{GL_TRUE} and to @code{GL_FALSE} |
6023 | otherwise. | |
6024 | ||
6025 | The vertices of connected triangles and connected quadrilaterals are | |
6026 | always marked as boundary, regardless of the value of the edge flag. | |
6027 | ||
6028 | Boundary and nonboundary edge flags on vertices are significant only if | |
f37e7e3d | 6029 | @code{GL_POLYGON_MODE} is set to @code{GL_POINT} or @code{GL_LINE}. See |
8925f36f AW |
6030 | @code{glPolygonMode}. |
6031 | ||
bb894c9d | 6032 | @end deftypefun |
8925f36f | 6033 | |
bb894c9d AW |
6034 | @deftypefun void glEnableClientState cap |
6035 | @deftypefunx void glDisableClientState cap | |
3c9b6116 AW |
6036 | Enable or disable client-side capability. |
6037 | ||
8925f36f AW |
6038 | @table @asis |
6039 | @item @var{cap} | |
f37e7e3d | 6040 | Specifies the capability to enable. Symbolic constants |
8925f36f AW |
6041 | @code{GL_COLOR_ARRAY}, @code{GL_EDGE_FLAG_ARRAY}, |
6042 | @code{GL_FOG_COORD_ARRAY}, @code{GL_INDEX_ARRAY}, | |
6043 | @code{GL_NORMAL_ARRAY}, @code{GL_SECONDARY_COLOR_ARRAY}, | |
6044 | @code{GL_TEXTURE_COORD_ARRAY}, and @code{GL_VERTEX_ARRAY} are accepted. | |
6045 | ||
6046 | @end table | |
6047 | ||
8925f36f | 6048 | @code{glEnableClientState} and @code{glDisableClientState} enable or |
f37e7e3d DH |
6049 | disable individual client-side capabilities. By default, all client-side |
6050 | capabilities are disabled. Both @code{glEnableClientState} and | |
6051 | @code{glDisableClientState} take a single argument, @var{cap}, which can | |
6052 | assume one of the following values: | |
8925f36f AW |
6053 | |
6054 | @table @asis | |
6055 | @item @code{GL_COLOR_ARRAY} | |
6056 | If enabled, the color array is enabled for writing and used during | |
6057 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6058 | @code{glDrawElements}, | |
6059 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
f37e7e3d | 6060 | @code{glMultiDrawElements} is called. See @code{glColorPointer}. |
8925f36f AW |
6061 | |
6062 | @item @code{GL_EDGE_FLAG_ARRAY} | |
6063 | If enabled, the edge flag array is enabled for writing and used during | |
6064 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6065 | @code{glDrawElements}, | |
6066 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
f37e7e3d | 6067 | @code{glMultiDrawElements} is called. See @code{glEdgeFlagPointer}. |
8925f36f AW |
6068 | |
6069 | @item @code{GL_FOG_COORD_ARRAY} | |
6070 | If enabled, the fog coordinate array is enabled for writing and used | |
6071 | during rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6072 | @code{glDrawElements}, | |
6073 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
f37e7e3d | 6074 | @code{glMultiDrawElements} is called. See @code{glFogCoordPointer}. |
8925f36f AW |
6075 | |
6076 | @item @code{GL_INDEX_ARRAY} | |
6077 | If enabled, the index array is enabled for writing and used during | |
6078 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6079 | @code{glDrawElements}, | |
6080 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
f37e7e3d | 6081 | @code{glMultiDrawElements} is called. See @code{glIndexPointer}. |
8925f36f AW |
6082 | |
6083 | @item @code{GL_NORMAL_ARRAY} | |
6084 | If enabled, the normal array is enabled for writing and used during | |
6085 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6086 | @code{glDrawElements}, | |
6087 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
f37e7e3d | 6088 | @code{glMultiDrawElements} is called. See @code{glNormalPointer}. |
8925f36f AW |
6089 | |
6090 | @item @code{GL_SECONDARY_COLOR_ARRAY} | |
6091 | If enabled, the secondary color array is enabled for writing and used | |
6092 | during rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6093 | @code{glDrawElements}, | |
6094 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
f37e7e3d | 6095 | @code{glMultiDrawElements} is called. See @code{glColorPointer}. |
8925f36f AW |
6096 | |
6097 | @item @code{GL_TEXTURE_COORD_ARRAY} | |
6098 | If enabled, the texture coordinate array is enabled for writing and used | |
6099 | during rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6100 | @code{glDrawElements}, | |
6101 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
f37e7e3d | 6102 | @code{glMultiDrawElements} is called. See @code{glTexCoordPointer}. |
8925f36f AW |
6103 | |
6104 | @item @code{GL_VERTEX_ARRAY} | |
6105 | If enabled, the vertex array is enabled for writing and used during | |
6106 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6107 | @code{glDrawElements}, | |
6108 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
f37e7e3d | 6109 | @code{glMultiDrawElements} is called. See @code{glVertexPointer}. |
8925f36f AW |
6110 | |
6111 | @end table | |
6112 | ||
8925f36f AW |
6113 | @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted |
6114 | value. | |
6115 | ||
6116 | @code{glEnableClientState} is not allowed between the execution of | |
6117 | @code{glBegin} and the corresponding @code{glEnd}, but an error may or | |
f37e7e3d | 6118 | may not be generated. If no error is generated, the behavior is |
8925f36f AW |
6119 | undefined. |
6120 | ||
bb894c9d | 6121 | @end deftypefun |
8925f36f | 6122 | |
bb894c9d AW |
6123 | @deftypefun void glEnableVertexAttribArray index |
6124 | @deftypefunx void glDisableVertexAttribArray index | |
3c9b6116 AW |
6125 | Enable or disable a generic vertex attribute array. |
6126 | ||
8925f36f AW |
6127 | @table @asis |
6128 | @item @var{index} | |
6129 | Specifies the index of the generic vertex attribute to be enabled or | |
6130 | disabled. | |
6131 | ||
6132 | @end table | |
6133 | ||
8925f36f | 6134 | @code{glEnableVertexAttribArray} enables the generic vertex attribute |
f37e7e3d DH |
6135 | array specified by @var{index}. @code{glDisableVertexAttribArray} |
6136 | disables the generic vertex attribute array specified by @var{index}. By | |
8925f36f | 6137 | default, all client-side capabilities are disabled, including all |
f37e7e3d | 6138 | generic vertex attribute arrays. If enabled, the values in the generic |
8925f36f AW |
6139 | vertex attribute array will be accessed and used for rendering when |
6140 | calls are made to vertex array commands such as @code{glDrawArrays}, | |
6141 | @code{glDrawElements}, @code{glDrawRangeElements}, | |
6142 | @code{glArrayElement}, @code{glMultiDrawElements}, or | |
6143 | @code{glMultiDrawArrays}. | |
6144 | ||
8925f36f AW |
6145 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
6146 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
6147 | ||
6148 | @code{GL_INVALID_OPERATION} is generated if either | |
6149 | @code{glEnableVertexAttribArray } or @code{glDisableVertexAttribArray } | |
6150 | is executed between the execution of @code{glBegin} and the | |
6151 | corresponding execution of @code{glEnd}. | |
6152 | ||
bb894c9d | 6153 | @end deftypefun |
8925f36f | 6154 | |
bb894c9d AW |
6155 | @deftypefun void glEnable cap |
6156 | @deftypefunx void glDisable cap | |
3c9b6116 AW |
6157 | Enable or disable server-side GL capabilities. |
6158 | ||
8925f36f AW |
6159 | @table @asis |
6160 | @item @var{cap} | |
6161 | Specifies a symbolic constant indicating a GL capability. | |
6162 | ||
6163 | @end table | |
6164 | ||
8925f36f | 6165 | @code{glEnable} and @code{glDisable} enable and disable various |
f37e7e3d DH |
6166 | capabilities. Use @code{glIsEnabled} or @code{glGet} to determine the |
6167 | current setting of any capability. The initial value for each capability | |
6168 | with the exception of @code{GL_DITHER} and @code{GL_MULTISAMPLE} is | |
6169 | @code{GL_FALSE}. The initial value for @code{GL_DITHER} and | |
6170 | @code{GL_MULTISAMPLE} is @code{GL_TRUE}. | |
8925f36f AW |
6171 | |
6172 | Both @code{glEnable} and @code{glDisable} take a single argument, | |
6173 | @var{cap}, which can assume one of the following values: | |
6174 | ||
6175 | @table @asis | |
6176 | @item @code{GL_ALPHA_TEST} | |
6177 | ||
6178 | ||
f37e7e3d | 6179 | If enabled, do alpha testing. See @code{glAlphaFunc}. |
8925f36f AW |
6180 | |
6181 | @item @code{GL_AUTO_NORMAL} | |
6182 | ||
6183 | ||
6184 | If enabled, generate normal vectors when either @code{GL_MAP2_VERTEX_3} | |
f37e7e3d | 6185 | or @code{GL_MAP2_VERTEX_4} is used to generate vertices. See |
8925f36f AW |
6186 | @code{glMap2}. |
6187 | ||
6188 | @item @code{GL_BLEND} | |
6189 | ||
6190 | ||
6191 | If enabled, blend the computed fragment color values with the values in | |
f37e7e3d | 6192 | the color buffers. See @code{glBlendFunc}. |
8925f36f AW |
6193 | |
6194 | @item @code{GL_CLIP_PLANE}@var{i} | |
6195 | ||
6196 | ||
6197 | If enabled, clip geometry against user-defined clipping plane @var{i}. | |
6198 | See @code{glClipPlane}. | |
6199 | ||
6200 | @item @code{GL_COLOR_LOGIC_OP} | |
6201 | ||
6202 | ||
6203 | If enabled, apply the currently selected logical operation to the | |
f37e7e3d | 6204 | computed fragment color and color buffer values. See @code{glLogicOp}. |
8925f36f AW |
6205 | |
6206 | @item @code{GL_COLOR_MATERIAL} | |
6207 | ||
6208 | ||
6209 | If enabled, have one or more material parameters track the current | |
f37e7e3d | 6210 | color. See @code{glColorMaterial}. |
8925f36f AW |
6211 | |
6212 | @item @code{GL_COLOR_SUM} | |
6213 | ||
6214 | ||
6215 | If enabled and no fragment shader is active, add the secondary color | |
f37e7e3d | 6216 | value to the computed fragment color. See @code{glSecondaryColor}. |
8925f36f AW |
6217 | |
6218 | @item @code{GL_COLOR_TABLE} | |
6219 | ||
6220 | ||
6221 | If enabled, perform a color table lookup on the incoming RGBA color | |
f37e7e3d | 6222 | values. See @code{glColorTable}. |
8925f36f AW |
6223 | |
6224 | @item @code{GL_CONVOLUTION_1D} | |
6225 | ||
6226 | ||
6227 | If enabled, perform a 1D convolution operation on incoming RGBA color | |
f37e7e3d | 6228 | values. See @code{glConvolutionFilter1D}. |
8925f36f AW |
6229 | |
6230 | @item @code{GL_CONVOLUTION_2D} | |
6231 | ||
6232 | ||
6233 | If enabled, perform a 2D convolution operation on incoming RGBA color | |
f37e7e3d | 6234 | values. See @code{glConvolutionFilter2D}. |
8925f36f AW |
6235 | |
6236 | @item @code{GL_CULL_FACE} | |
6237 | ||
6238 | ||
6239 | If enabled, cull polygons based on their winding in window coordinates. | |
6240 | See @code{glCullFace}. | |
6241 | ||
6242 | @item @code{GL_DEPTH_TEST} | |
6243 | ||
6244 | ||
f37e7e3d | 6245 | If enabled, do depth comparisons and update the depth buffer. Note that |
8925f36f | 6246 | even if the depth buffer exists and the depth mask is non-zero, the |
f37e7e3d | 6247 | depth buffer is not updated if the depth test is disabled. See |
8925f36f AW |
6248 | @code{glDepthFunc} and @code{glDepthRange}. |
6249 | ||
6250 | @item @code{GL_DITHER} | |
6251 | ||
6252 | ||
6253 | If enabled, dither color components or indices before they are written | |
6254 | to the color buffer. | |
6255 | ||
6256 | @item @code{GL_FOG} | |
6257 | ||
6258 | ||
6259 | If enabled and no fragment shader is active, blend a fog color into the | |
f37e7e3d | 6260 | post-texturing color. See @code{glFog}. |
8925f36f AW |
6261 | |
6262 | @item @code{GL_HISTOGRAM} | |
6263 | ||
6264 | ||
f37e7e3d | 6265 | If enabled, histogram incoming RGBA color values. See |
8925f36f AW |
6266 | @code{glHistogram}. |
6267 | ||
6268 | @item @code{GL_INDEX_LOGIC_OP} | |
6269 | ||
6270 | ||
6271 | If enabled, apply the currently selected logical operation to the | |
f37e7e3d | 6272 | incoming index and color buffer indices. See @code{glLogicOp}. |
8925f36f AW |
6273 | |
6274 | @item @code{GL_LIGHT}@var{i} | |
6275 | ||
6276 | ||
6277 | If enabled, include light @var{i} in the evaluation of the lighting | |
f37e7e3d | 6278 | equation. See @code{glLightModel} and @code{glLight}. |
8925f36f AW |
6279 | |
6280 | @item @code{GL_LIGHTING} | |
6281 | ||
6282 | ||
6283 | If enabled and no vertex shader is active, use the current lighting | |
f37e7e3d DH |
6284 | parameters to compute the vertex color or index. Otherwise, simply |
6285 | associate the current color or index with each vertex. See | |
8925f36f AW |
6286 | @code{glMaterial}, @code{glLightModel}, and @code{glLight}. |
6287 | ||
6288 | @item @code{GL_LINE_SMOOTH} | |
6289 | ||
6290 | ||
f37e7e3d DH |
6291 | If enabled, draw lines with correct filtering. Otherwise, draw aliased |
6292 | lines. See @code{glLineWidth}. | |
8925f36f AW |
6293 | |
6294 | @item @code{GL_LINE_STIPPLE} | |
6295 | ||
6296 | ||
f37e7e3d | 6297 | If enabled, use the current line stipple pattern when drawing lines. See |
8925f36f AW |
6298 | @code{glLineStipple}. |
6299 | ||
6300 | @item @code{GL_MAP1_COLOR_4} | |
6301 | ||
6302 | ||
6303 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
f37e7e3d | 6304 | @code{glEvalPoint1} generate RGBA values. See @code{glMap1}. |
8925f36f AW |
6305 | |
6306 | @item @code{GL_MAP1_INDEX} | |
6307 | ||
6308 | ||
6309 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
f37e7e3d | 6310 | @code{glEvalPoint1} generate color indices. See @code{glMap1}. |
8925f36f AW |
6311 | |
6312 | @item @code{GL_MAP1_NORMAL} | |
6313 | ||
6314 | ||
6315 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
f37e7e3d | 6316 | @code{glEvalPoint1} generate normals. See @code{glMap1}. |
8925f36f AW |
6317 | |
6318 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
6319 | ||
6320 | ||
6321 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
f37e7e3d | 6322 | @code{glEvalPoint1} generate @var{s} texture coordinates. See |
8925f36f AW |
6323 | @code{glMap1}. |
6324 | ||
6325 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
6326 | ||
6327 | ||
6328 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6329 | @code{glEvalPoint1} generate @var{s} and @var{t} texture coordinates. | |
6330 | See @code{glMap1}. | |
6331 | ||
6332 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
6333 | ||
6334 | ||
6335 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6336 | @code{glEvalPoint1} generate @var{s}, @var{t}, and @var{r} texture | |
f37e7e3d | 6337 | coordinates. See @code{glMap1}. |
8925f36f AW |
6338 | |
6339 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
6340 | ||
6341 | ||
6342 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6343 | @code{glEvalPoint1} generate @var{s}, @var{t}, @var{r}, and @var{q} | |
f37e7e3d | 6344 | texture coordinates. See @code{glMap1}. |
8925f36f AW |
6345 | |
6346 | @item @code{GL_MAP1_VERTEX_3} | |
6347 | ||
6348 | ||
6349 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6350 | @code{glEvalPoint1} generate @var{x}, @var{y}, and @var{z} vertex | |
f37e7e3d | 6351 | coordinates. See @code{glMap1}. |
8925f36f AW |
6352 | |
6353 | @item @code{GL_MAP1_VERTEX_4} | |
6354 | ||
6355 | ||
6356 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6357 | @code{glEvalPoint1} generate homogeneous @var{x}, @var{y}, @var{z}, and | |
f37e7e3d | 6358 | @var{w} vertex coordinates. See @code{glMap1}. |
8925f36f AW |
6359 | |
6360 | @item @code{GL_MAP2_COLOR_4} | |
6361 | ||
6362 | ||
6363 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
f37e7e3d | 6364 | @code{glEvalPoint2} generate RGBA values. See @code{glMap2}. |
8925f36f AW |
6365 | |
6366 | @item @code{GL_MAP2_INDEX} | |
6367 | ||
6368 | ||
6369 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
f37e7e3d | 6370 | @code{glEvalPoint2} generate color indices. See @code{glMap2}. |
8925f36f AW |
6371 | |
6372 | @item @code{GL_MAP2_NORMAL} | |
6373 | ||
6374 | ||
6375 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
f37e7e3d | 6376 | @code{glEvalPoint2} generate normals. See @code{glMap2}. |
8925f36f AW |
6377 | |
6378 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
6379 | ||
6380 | ||
6381 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
f37e7e3d | 6382 | @code{glEvalPoint2} generate @var{s} texture coordinates. See |
8925f36f AW |
6383 | @code{glMap2}. |
6384 | ||
6385 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
6386 | ||
6387 | ||
6388 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6389 | @code{glEvalPoint2} generate @var{s} and @var{t} texture coordinates. | |
6390 | See @code{glMap2}. | |
6391 | ||
6392 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
6393 | ||
6394 | ||
6395 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6396 | @code{glEvalPoint2} generate @var{s}, @var{t}, and @var{r} texture | |
f37e7e3d | 6397 | coordinates. See @code{glMap2}. |
8925f36f AW |
6398 | |
6399 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
6400 | ||
6401 | ||
6402 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6403 | @code{glEvalPoint2} generate @var{s}, @var{t}, @var{r}, and @var{q} | |
f37e7e3d | 6404 | texture coordinates. See @code{glMap2}. |
8925f36f AW |
6405 | |
6406 | @item @code{GL_MAP2_VERTEX_3} | |
6407 | ||
6408 | ||
6409 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6410 | @code{glEvalPoint2} generate @var{x}, @var{y}, and @var{z} vertex | |
f37e7e3d | 6411 | coordinates. See @code{glMap2}. |
8925f36f AW |
6412 | |
6413 | @item @code{GL_MAP2_VERTEX_4} | |
6414 | ||
6415 | ||
6416 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6417 | @code{glEvalPoint2} generate homogeneous @var{x}, @var{y}, @var{z}, and | |
f37e7e3d | 6418 | @var{w} vertex coordinates. See @code{glMap2}. |
8925f36f AW |
6419 | |
6420 | @item @code{GL_MINMAX} | |
6421 | ||
6422 | ||
6423 | If enabled, compute the minimum and maximum values of incoming RGBA | |
f37e7e3d | 6424 | color values. See @code{glMinmax}. |
8925f36f AW |
6425 | |
6426 | @item @code{GL_MULTISAMPLE} | |
6427 | ||
6428 | ||
6429 | If enabled, use multiple fragment samples in computing the final color | |
f37e7e3d | 6430 | of a pixel. See @code{glSampleCoverage}. |
8925f36f AW |
6431 | |
6432 | @item @code{GL_NORMALIZE} | |
6433 | ||
6434 | ||
6435 | If enabled and no vertex shader is active, normal vectors are normalized | |
f37e7e3d DH |
6436 | to unit length after transformation and before lighting. This method is |
6437 | generally less efficient than @code{GL_RESCALE_NORMAL}. See | |
8925f36f AW |
6438 | @code{glNormal} and @code{glNormalPointer}. |
6439 | ||
6440 | @item @code{GL_POINT_SMOOTH} | |
6441 | ||
6442 | ||
f37e7e3d DH |
6443 | If enabled, draw points with proper filtering. Otherwise, draw aliased |
6444 | points. See @code{glPointSize}. | |
8925f36f AW |
6445 | |
6446 | @item @code{GL_POINT_SPRITE} | |
6447 | ||
6448 | ||
6449 | If enabled, calculate texture coordinates for points based on texture | |
f37e7e3d | 6450 | environment and point parameter settings. Otherwise texture coordinates |
8925f36f AW |
6451 | are constant across points. |
6452 | ||
6453 | @item @code{GL_POLYGON_OFFSET_FILL} | |
6454 | ||
6455 | ||
6456 | If enabled, and if the polygon is rendered in @code{GL_FILL} mode, an | |
6457 | offset is added to depth values of a polygon's fragments before the | |
f37e7e3d | 6458 | depth comparison is performed. See @code{glPolygonOffset}. |
8925f36f AW |
6459 | |
6460 | @item @code{GL_POLYGON_OFFSET_LINE} | |
6461 | ||
6462 | ||
6463 | If enabled, and if the polygon is rendered in @code{GL_LINE} mode, an | |
6464 | offset is added to depth values of a polygon's fragments before the | |
f37e7e3d | 6465 | depth comparison is performed. See @code{glPolygonOffset}. |
8925f36f AW |
6466 | |
6467 | @item @code{GL_POLYGON_OFFSET_POINT} | |
6468 | ||
6469 | ||
6470 | If enabled, an offset is added to depth values of a polygon's fragments | |
6471 | before the depth comparison is performed, if the polygon is rendered in | |
f37e7e3d | 6472 | @code{GL_POINT} mode. See @code{glPolygonOffset}. |
8925f36f AW |
6473 | |
6474 | @item @code{GL_POLYGON_SMOOTH} | |
6475 | ||
6476 | ||
f37e7e3d DH |
6477 | If enabled, draw polygons with proper filtering. Otherwise, draw aliased |
6478 | polygons. For correct antialiased polygons, an alpha buffer is needed | |
6479 | and the polygons must be sorted front to back. | |
8925f36f AW |
6480 | |
6481 | @item @code{GL_POLYGON_STIPPLE} | |
6482 | ||
6483 | ||
6484 | If enabled, use the current polygon stipple pattern when rendering | |
f37e7e3d | 6485 | polygons. See @code{glPolygonStipple}. |
8925f36f AW |
6486 | |
6487 | @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} | |
6488 | ||
6489 | ||
6490 | If enabled, perform a color table lookup on RGBA color values after | |
f37e7e3d | 6491 | color matrix transformation. See @code{glColorTable}. |
8925f36f AW |
6492 | |
6493 | @item @code{GL_POST_CONVOLUTION_COLOR_TABLE} | |
6494 | ||
6495 | ||
6496 | If enabled, perform a color table lookup on RGBA color values after | |
f37e7e3d | 6497 | convolution. See @code{glColorTable}. |
8925f36f AW |
6498 | |
6499 | @item @code{GL_RESCALE_NORMAL} | |
6500 | ||
6501 | ||
6502 | If enabled and no vertex shader is active, normal vectors are scaled | |
6503 | after transformation and before lighting by a factor computed from the | |
f37e7e3d DH |
6504 | modelview matrix. If the modelview matrix scales space uniformly, this |
6505 | has the effect of restoring the transformed normal to unit length. This | |
6506 | method is generally more efficient than @code{GL_NORMALIZE}. See | |
8925f36f AW |
6507 | @code{glNormal} and @code{glNormalPointer}. |
6508 | ||
6509 | @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE} | |
6510 | ||
6511 | ||
6512 | If enabled, compute a temporary coverage value where each bit is | |
f37e7e3d | 6513 | determined by the alpha value at the corresponding sample location. The |
8925f36f AW |
6514 | temporary coverage value is then ANDed with the fragment coverage value. |
6515 | ||
6516 | @item @code{GL_SAMPLE_ALPHA_TO_ONE} | |
6517 | ||
6518 | ||
6519 | If enabled, each sample alpha value is replaced by the maximum | |
6520 | representable alpha value. | |
6521 | ||
6522 | @item @code{GL_SAMPLE_COVERAGE} | |
6523 | ||
6524 | ||
6525 | If enabled, the fragment's coverage is ANDed with the temporary coverage | |
f37e7e3d DH |
6526 | value. If @code{GL_SAMPLE_COVERAGE_INVERT} is set to @code{GL_TRUE}, |
6527 | invert the coverage value. See @code{glSampleCoverage}. | |
8925f36f AW |
6528 | |
6529 | @item @code{GL_SEPARABLE_2D} | |
6530 | ||
6531 | ||
6532 | If enabled, perform a two-dimensional convolution operation using a | |
f37e7e3d | 6533 | separable convolution filter on incoming RGBA color values. See |
8925f36f AW |
6534 | @code{glSeparableFilter2D}. |
6535 | ||
6536 | @item @code{GL_SCISSOR_TEST} | |
6537 | ||
6538 | ||
6539 | If enabled, discard fragments that are outside the scissor rectangle. | |
6540 | See @code{glScissor}. | |
6541 | ||
6542 | @item @code{GL_STENCIL_TEST} | |
6543 | ||
6544 | ||
f37e7e3d | 6545 | If enabled, do stencil testing and update the stencil buffer. See |
8925f36f AW |
6546 | @code{glStencilFunc} and @code{glStencilOp}. |
6547 | ||
6548 | @item @code{GL_TEXTURE_1D} | |
6549 | ||
6550 | ||
6551 | If enabled and no fragment shader is active, one-dimensional texturing | |
6552 | is performed (unless two- or three-dimensional or cube-mapped texturing | |
f37e7e3d | 6553 | is also enabled). See @code{glTexImage1D}. |
8925f36f AW |
6554 | |
6555 | @item @code{GL_TEXTURE_2D} | |
6556 | ||
6557 | ||
6558 | If enabled and no fragment shader is active, two-dimensional texturing | |
6559 | is performed (unless three-dimensional or cube-mapped texturing is also | |
f37e7e3d | 6560 | enabled). See @code{glTexImage2D}. |
8925f36f AW |
6561 | |
6562 | @item @code{GL_TEXTURE_3D} | |
6563 | ||
6564 | ||
6565 | If enabled and no fragment shader is active, three-dimensional texturing | |
f37e7e3d | 6566 | is performed (unless cube-mapped texturing is also enabled). See |
8925f36f AW |
6567 | @code{glTexImage3D}. |
6568 | ||
6569 | @item @code{GL_TEXTURE_CUBE_MAP} | |
6570 | ||
6571 | ||
6572 | If enabled and no fragment shader is active, cube-mapped texturing is | |
f37e7e3d | 6573 | performed. See @code{glTexImage2D}. |
8925f36f AW |
6574 | |
6575 | @item @code{GL_TEXTURE_GEN_Q} | |
6576 | ||
6577 | ||
6578 | If enabled and no vertex shader is active, the @var{q} texture | |
6579 | coordinate is computed using the texture generation function defined | |
f37e7e3d DH |
6580 | with @code{glTexGen}. Otherwise, the current @var{q} texture coordinate |
6581 | is used. See @code{glTexGen}. | |
8925f36f AW |
6582 | |
6583 | @item @code{GL_TEXTURE_GEN_R} | |
6584 | ||
6585 | ||
6586 | If enabled and no vertex shader is active, the @var{r} texture | |
6587 | coordinate is computed using the texture generation function defined | |
f37e7e3d DH |
6588 | with @code{glTexGen}. Otherwise, the current @var{r} texture coordinate |
6589 | is used. See @code{glTexGen}. | |
8925f36f AW |
6590 | |
6591 | @item @code{GL_TEXTURE_GEN_S} | |
6592 | ||
6593 | ||
6594 | If enabled and no vertex shader is active, the @var{s} texture | |
6595 | coordinate is computed using the texture generation function defined | |
f37e7e3d DH |
6596 | with @code{glTexGen}. Otherwise, the current @var{s} texture coordinate |
6597 | is used. See @code{glTexGen}. | |
8925f36f AW |
6598 | |
6599 | @item @code{GL_TEXTURE_GEN_T} | |
6600 | ||
6601 | ||
6602 | If enabled and no vertex shader is active, the @var{t} texture | |
6603 | coordinate is computed using the texture generation function defined | |
f37e7e3d DH |
6604 | with @code{glTexGen}. Otherwise, the current @var{t} texture coordinate |
6605 | is used. See @code{glTexGen}. | |
8925f36f AW |
6606 | |
6607 | @item @code{GL_VERTEX_PROGRAM_POINT_SIZE} | |
6608 | ||
6609 | ||
6610 | If enabled and a vertex shader is active, then the derived point size is | |
6611 | taken from the (potentially clipped) shader builtin @code{gl_PointSize} | |
6612 | and clamped to the implementation-dependent point size range. | |
6613 | ||
6614 | @item @code{GL_VERTEX_PROGRAM_TWO_SIDE} | |
6615 | ||
6616 | ||
6617 | If enabled and a vertex shader is active, it specifies that the GL will | |
6618 | choose between front and back colors based on the polygon's face | |
f37e7e3d | 6619 | direction of which the vertex being shaded is a part. It has no effect |
8925f36f AW |
6620 | on points or lines. |
6621 | ||
6622 | @end table | |
6623 | ||
8925f36f AW |
6624 | @code{GL_INVALID_ENUM} is generated if @var{cap} is not one of the |
6625 | values listed previously. | |
6626 | ||
6627 | @code{GL_INVALID_OPERATION} is generated if @code{glEnable} or | |
6628 | @code{glDisable} is executed between the execution of @code{glBegin} and | |
6629 | the corresponding execution of @code{glEnd}. | |
6630 | ||
bb894c9d | 6631 | @end deftypefun |
8925f36f | 6632 | |
ca09631c | 6633 | @deftypefun void glEvalCoord1f u |
d172eed9 | 6634 | @deftypefunx void glEvalCoord1d u |
ca09631c | 6635 | @deftypefunx void glEvalCoord2f u v |
d172eed9 AW |
6636 | @deftypefunx void glEvalCoord2d u v |
6637 | @deftypefunx void glEvalCoord1fv u | |
6638 | @deftypefunx void glEvalCoord1dv u | |
6639 | @deftypefunx void glEvalCoord2fv u | |
6640 | @deftypefunx void glEvalCoord2dv u | |
3c9b6116 AW |
6641 | Evaluate enabled one- and two-dimensional maps. |
6642 | ||
8925f36f AW |
6643 | @table @asis |
6644 | @item @var{u} | |
3c9b6116 AW |
6645 | Specifies a value that is the domain coordinate @r{@var{u}} to the basis |
6646 | function defined in a previous @code{glMap1} or @code{glMap2} command. | |
8925f36f AW |
6647 | |
6648 | @item @var{v} | |
3c9b6116 | 6649 | Specifies a value that is the domain coordinate @r{@var{v}} to the basis |
f37e7e3d | 6650 | function defined in a previous @code{glMap2} command. This argument is |
3c9b6116 | 6651 | not present in a @code{glEvalCoord1} command. |
8925f36f AW |
6652 | |
6653 | @end table | |
6654 | ||
8925f36f | 6655 | @code{glEvalCoord1} evaluates enabled one-dimensional maps at argument |
f37e7e3d DH |
6656 | @var{u}. @code{glEvalCoord2} does the same for two-dimensional maps |
6657 | using two domain values, @var{u} and @var{v}. To define a map, call | |
8925f36f AW |
6658 | @code{glMap1} and @code{glMap2}; to enable and disable it, call |
6659 | @code{glEnable} and @code{glDisable}. | |
6660 | ||
6661 | When one of the @code{glEvalCoord} commands is issued, all currently | |
f37e7e3d | 6662 | enabled maps of the indicated dimension are evaluated. Then, for each |
8925f36f | 6663 | enabled map, it is as if the corresponding GL command had been issued |
f37e7e3d | 6664 | with the computed value. That is, if @code{GL_MAP1_INDEX} or |
8925f36f AW |
6665 | @code{GL_MAP2_INDEX} is enabled, a @code{glIndex} command is simulated. |
6666 | If @code{GL_MAP1_COLOR_4} or @code{GL_MAP2_COLOR_4} is enabled, a | |
f37e7e3d | 6667 | @code{glColor} command is simulated. If @code{GL_MAP1_NORMAL} or |
8925f36f AW |
6668 | @code{GL_MAP2_NORMAL} is enabled, a normal vector is produced, and if |
6669 | any of @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2}, | |
6670 | @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4}, | |
6671 | @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2}, | |
6672 | @code{GL_MAP2_TEXTURE_COORD_3}, or @code{GL_MAP2_TEXTURE_COORD_4} is | |
6673 | enabled, then an appropriate @code{glTexCoord} command is simulated. | |
6674 | ||
6675 | For color, color index, normal, and texture coordinates the GL uses | |
6676 | evaluated values instead of current values for those evaluations that | |
6677 | are enabled, and current values otherwise, However, the evaluated values | |
f37e7e3d | 6678 | do not update the current values. Thus, if @code{glVertex} commands are |
8925f36f AW |
6679 | interspersed with @code{glEvalCoord} commands, the color, normal, and |
6680 | texture coordinates associated with the @code{glVertex} commands are not | |
6681 | affected by the values generated by the @code{glEvalCoord} commands, but | |
6682 | only by the most recent @code{glColor}, @code{glIndex}, @code{glNormal}, | |
6683 | and @code{glTexCoord} commands. | |
6684 | ||
f37e7e3d | 6685 | No commands are issued for maps that are not enabled. If more than one |
8925f36f AW |
6686 | texture evaluation is enabled for a particular dimension (for example, |
6687 | @code{GL_MAP2_TEXTURE_COORD_1} and @code{GL_MAP2_TEXTURE_COORD_2}), then | |
6688 | only the evaluation of the map that produces the larger number of | |
6689 | coordinates (in this case, @code{GL_MAP2_TEXTURE_COORD_2}) is carried | |
f37e7e3d | 6690 | out. @code{GL_MAP1_VERTEX_4} overrides @code{GL_MAP1_VERTEX_3}, and |
8925f36f | 6691 | @code{GL_MAP2_VERTEX_4} overrides @code{GL_MAP2_VERTEX_3}, in the same |
f37e7e3d | 6692 | manner. If neither a three- nor a four-component vertex map is enabled |
8925f36f AW |
6693 | for the specified dimension, the @code{glEvalCoord} command is ignored. |
6694 | ||
6695 | If you have enabled automatic normal generation, by calling | |
6696 | @code{glEnable} with argument @code{GL_AUTO_NORMAL}, @code{glEvalCoord2} | |
6697 | generates surface normals analytically, regardless of the contents or | |
f37e7e3d | 6698 | enabling of the @code{GL_MAP2_NORMAL} map. Let |
8925f36f | 6699 | |
3c9b6116 | 6700 | @r{@code{m}=∂@code{p},/∂@var{u},,×∂@code{p},/∂@var{v},,} |
8925f36f | 6701 | |
3c9b6116 AW |
6702 | Then the generated normal @r{@code{n}} is |
6703 | @r{@code{n}=@code{m}/∥@code{m},∥,} | |
8925f36f AW |
6704 | |
6705 | If automatic normal generation is disabled, the corresponding normal map | |
f37e7e3d | 6706 | @code{GL_MAP2_NORMAL}, if enabled, is used to produce a normal. If |
8925f36f AW |
6707 | neither automatic normal generation nor a normal map is enabled, no |
6708 | normal is generated for @code{glEvalCoord2} commands. | |
6709 | ||
bb894c9d | 6710 | @end deftypefun |
8925f36f | 6711 | |
bb894c9d AW |
6712 | @deftypefun void glEvalMesh1 mode i1 i2 |
6713 | @deftypefunx void glEvalMesh2 mode i1 i2 j1 j2 | |
3c9b6116 AW |
6714 | Compute a one- or two-dimensional grid of points or lines. |
6715 | ||
8925f36f AW |
6716 | @table @asis |
6717 | @item @var{mode} | |
6718 | In @code{glEvalMesh1}, specifies whether to compute a one-dimensional | |
f37e7e3d | 6719 | mesh of points or lines. Symbolic constants @code{GL_POINT} and |
8925f36f AW |
6720 | @code{GL_LINE} are accepted. |
6721 | ||
6722 | @item @var{i1} | |
6723 | @itemx @var{i2} | |
6724 | Specify the first and last integer values for grid domain variable | |
3c9b6116 | 6725 | @r{@var{i}}. |
8925f36f AW |
6726 | |
6727 | @end table | |
6728 | ||
8925f36f AW |
6729 | @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently |
6730 | generate and evaluate a series of evenly-spaced map domain values. | |
6731 | @code{glEvalMesh} steps through the integer domain of a one- or | |
6732 | two-dimensional grid, whose range is the domain of the evaluation maps | |
f37e7e3d | 6733 | specified by @code{glMap1} and @code{glMap2}. @var{mode} determines |
8925f36f AW |
6734 | whether the resulting vertices are connected as points, lines, or filled |
6735 | polygons. | |
6736 | ||
6737 | In the one-dimensional case, @code{glEvalMesh1}, the mesh is generated | |
6738 | as if the following code fragment were executed: | |
6739 | ||
6740 | where | |
6741 | ||
6742 | @example | |
6743 | ||
6744 | glBegin( @var{type} ); | |
6745 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) | |
3c9b6116 | 6746 | glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} ); |
8925f36f AW |
6747 | glEnd(); |
6748 | @end example | |
6749 | ||
3c9b6116 | 6750 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}} |
8925f36f | 6751 | |
3c9b6116 | 6752 | and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to |
f37e7e3d | 6753 | the most recent @code{glMapGrid1} command. @var{type} is |
8925f36f AW |
6754 | @code{GL_POINTS} if @var{mode} is @code{GL_POINT}, or @code{GL_LINES} if |
6755 | @var{mode} is @code{GL_LINE}. | |
6756 | ||
3c9b6116 AW |
6757 | The one absolute numeric requirement is that if @r{@var{i}=@var{n}}, |
6758 | then the value computed from @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly | |
6759 | @r{@var{u}_2}. | |
8925f36f AW |
6760 | |
6761 | In the two-dimensional case, @code{glEvalMesh2}, let .cp | |
3c9b6116 | 6762 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}} |
8925f36f | 6763 | |
3c9b6116 | 6764 | @r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}} |
8925f36f | 6765 | |
3c9b6116 AW |
6766 | where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}}, |
6767 | @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent | |
f37e7e3d | 6768 | @code{glMapGrid2} command. Then, if @var{mode} is @code{GL_FILL}, the |
3c9b6116 | 6769 | @code{glEvalMesh2} command is equivalent to: |
8925f36f AW |
6770 | |
6771 | ||
6772 | ||
6773 | @example | |
6774 | ||
6775 | for ( j = @var{j1}; j < @var{j2}; j += 1 ) @{ | |
6776 | glBegin( GL_QUAD_STRIP ); | |
6777 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{ | |
3c9b6116 AW |
6778 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
6779 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,(j+1,)·Δ@var{v}+@var{v}_1} ); | |
8925f36f AW |
6780 | @} |
6781 | glEnd(); | |
6782 | @} | |
6783 | @end example | |
6784 | ||
6785 | If @var{mode} is @code{GL_LINE}, then a call to @code{glEvalMesh2} is | |
6786 | equivalent to: | |
6787 | ||
6788 | ||
6789 | ||
6790 | @example | |
6791 | ||
6792 | for ( j = @var{j1}; j <= @var{j2}; j += 1 ) @{ | |
6793 | glBegin( GL_LINE_STRIP ); | |
6794 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) | |
3c9b6116 | 6795 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6796 | glEnd(); |
6797 | @} | |
6798 | ||
6799 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{ | |
6800 | glBegin( GL_LINE_STRIP ); | |
6801 | for ( j = @var{j1}; j <= @var{j1}; j += 1 ) | |
3c9b6116 | 6802 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6803 | glEnd(); |
6804 | @} | |
6805 | @end example | |
6806 | ||
6807 | And finally, if @var{mode} is @code{GL_POINT}, then a call to | |
6808 | @code{glEvalMesh2} is equivalent to: | |
6809 | ||
6810 | ||
6811 | ||
6812 | @example | |
6813 | ||
6814 | glBegin( GL_POINTS ); | |
6815 | for ( j = @var{j1}; j <= @var{j2}; j += 1 ) | |
6816 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) | |
3c9b6116 | 6817 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6818 | glEnd(); |
6819 | @end example | |
6820 | ||
6821 | In all three cases, the only absolute numeric requirements are that if | |
3c9b6116 AW |
6822 | @r{@var{i}=@var{n}}, then the value computed from |
6823 | @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if | |
6824 | @r{@var{j}=@var{m}}, then the value computed from | |
6825 | @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}. | |
8925f36f | 6826 | |
8925f36f AW |
6827 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
6828 | value. | |
6829 | ||
6830 | @code{GL_INVALID_OPERATION} is generated if @code{glEvalMesh} is | |
6831 | executed between the execution of @code{glBegin} and the corresponding | |
6832 | execution of @code{glEnd}. | |
6833 | ||
bb894c9d | 6834 | @end deftypefun |
8925f36f | 6835 | |
bb894c9d AW |
6836 | @deftypefun void glEvalPoint1 i |
6837 | @deftypefunx void glEvalPoint2 i j | |
3c9b6116 AW |
6838 | Generate and evaluate a single point in a mesh. |
6839 | ||
8925f36f AW |
6840 | @table @asis |
6841 | @item @var{i} | |
3c9b6116 | 6842 | Specifies the integer value for grid domain variable @r{@var{i}}. |
8925f36f AW |
6843 | |
6844 | @item @var{j} | |
3c9b6116 | 6845 | Specifies the integer value for grid domain variable @r{@var{j}} |
8925f36f AW |
6846 | (@code{glEvalPoint2} only). |
6847 | ||
6848 | @end table | |
6849 | ||
8925f36f AW |
6850 | @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently |
6851 | generate and evaluate a series of evenly spaced map domain values. | |
6852 | @code{glEvalPoint} can be used to evaluate a single grid point in the | |
f37e7e3d | 6853 | same gridspace that is traversed by @code{glEvalMesh}. Calling |
8925f36f | 6854 | @code{glEvalPoint1} is equivalent to calling where |
3c9b6116 | 6855 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}} |
8925f36f AW |
6856 | |
6857 | @example | |
6858 | ||
3c9b6116 | 6859 | glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} ); |
8925f36f AW |
6860 | @end example |
6861 | ||
3c9b6116 | 6862 | and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to |
f37e7e3d | 6863 | the most recent @code{glMapGrid1} command. The one absolute numeric |
3c9b6116 AW |
6864 | requirement is that if @r{@var{i}=@var{n}}, then the value computed from |
6865 | @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}. | |
8925f36f AW |
6866 | |
6867 | In the two-dimensional case, @code{glEvalPoint2}, let | |
6868 | ||
3c9b6116 | 6869 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}@r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}} |
8925f36f | 6870 | |
3c9b6116 AW |
6871 | where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}}, |
6872 | @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent | |
f37e7e3d | 6873 | @code{glMapGrid2} command. Then the @code{glEvalPoint2} command is |
3c9b6116 AW |
6874 | equivalent to calling The only absolute numeric requirements are that if |
6875 | @r{@var{i}=@var{n}}, then the value computed from | |
6876 | @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if | |
6877 | @r{@var{j}=@var{m}}, then the value computed from | |
6878 | @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}. | |
8925f36f AW |
6879 | |
6880 | @example | |
6881 | ||
3c9b6116 | 6882 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6883 | @end example |
6884 | ||
bb894c9d | 6885 | @end deftypefun |
8925f36f | 6886 | |
bb894c9d | 6887 | @deftypefun void glFeedbackBuffer size type buffer |
3c9b6116 AW |
6888 | Controls feedback mode. |
6889 | ||
8925f36f AW |
6890 | @table @asis |
6891 | @item @var{size} | |
6892 | Specifies the maximum number of values that can be written into | |
6893 | @var{buffer}. | |
6894 | ||
6895 | @item @var{type} | |
6896 | Specifies a symbolic constant that describes the information that will | |
f37e7e3d | 6897 | be returned for each vertex. @code{GL_2D}, @code{GL_3D}, |
8925f36f AW |
6898 | @code{GL_3D_COLOR}, @code{GL_3D_COLOR_TEXTURE}, and |
6899 | @code{GL_4D_COLOR_TEXTURE} are accepted. | |
6900 | ||
6901 | @item @var{buffer} | |
6902 | Returns the feedback data. | |
6903 | ||
6904 | @end table | |
6905 | ||
f37e7e3d DH |
6906 | The @code{glFeedbackBuffer} function controls feedback. Feedback, like |
6907 | selection, is a GL mode. The mode is selected by calling | |
6908 | @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback | |
6909 | mode, no pixels are produced by rasterization. Instead, information | |
8925f36f AW |
6910 | about primitives that would have been rasterized is fed back to the |
6911 | application using the GL. | |
6912 | ||
6913 | @code{glFeedbackBuffer} has three arguments: @var{buffer} is a pointer | |
6914 | to an array of floating-point values into which feedback information is | |
f37e7e3d | 6915 | placed. @var{size} indicates the size of the array. @var{type} is a |
8925f36f | 6916 | symbolic constant describing the information that is fed back for each |
f37e7e3d | 6917 | vertex. @code{glFeedbackBuffer} must be issued before feedback mode is |
8925f36f | 6918 | enabled (by calling @code{glRenderMode} with argument |
f37e7e3d DH |
6919 | @code{GL_FEEDBACK}). Setting @code{GL_FEEDBACK} without establishing the |
6920 | feedback buffer, or calling @code{glFeedbackBuffer} while the GL is in | |
6921 | feedback mode, is an error. | |
8925f36f AW |
6922 | |
6923 | When @code{glRenderMode} is called while in feedback mode, it returns | |
6924 | the number of entries placed in the feedback array and resets the | |
f37e7e3d DH |
6925 | feedback array pointer to the base of the feedback buffer. The returned |
6926 | value never exceeds @var{size}. If the feedback data required more room | |
8925f36f | 6927 | than was available in @var{buffer}, @code{glRenderMode} returns a |
f37e7e3d | 6928 | negative value. To take the GL out of feedback mode, call |
8925f36f AW |
6929 | @code{glRenderMode} with a parameter value other than |
6930 | @code{GL_FEEDBACK}. | |
6931 | ||
6932 | While in feedback mode, each primitive, bitmap, or pixel rectangle that | |
6933 | would be rasterized generates a block of values that are copied into the | |
f37e7e3d | 6934 | feedback array. If doing so would cause the number of entries to exceed |
8925f36f | 6935 | the maximum, the block is partially written so as to fill the array (if |
f37e7e3d | 6936 | there is any room left at all), and an overflow flag is set. Each block |
8925f36f | 6937 | begins with a code indicating the primitive type, followed by values |
f37e7e3d DH |
6938 | that describe the primitive's vertices and associated data. Entries are |
6939 | also written for bitmaps and pixel rectangles. Feedback occurs after | |
8925f36f AW |
6940 | polygon culling and @code{glPolygonMode} interpretation of polygons has |
6941 | taken place, so polygons that are culled are not returned in the | |
f37e7e3d | 6942 | feedback buffer. It can also occur after polygons with more than three |
8925f36f AW |
6943 | edges are broken up into triangles, if the GL implementation renders |
6944 | polygons by performing this decomposition. | |
6945 | ||
6946 | The @code{glPassThrough} command can be used to insert a marker into the | |
f37e7e3d | 6947 | feedback buffer. See @code{glPassThrough}. |
8925f36f AW |
6948 | |
6949 | Following is the grammar for the blocks of values written into the | |
f37e7e3d DH |
6950 | feedback buffer. Each primitive is indicated with a unique identifying |
6951 | value followed by some number of vertices. Polygon entries include an | |
6952 | integer value indicating how many vertices follow. A vertex is fed back | |
8925f36f AW |
6953 | as some number of floating-point values, as determined by @var{type}. |
6954 | Colors are fed back as four values in RGBA mode and one value in color | |
6955 | index mode. | |
6956 | ||
3c9b6116 AW |
6957 | feedbackList @r{←} feedbackItem feedbackList | feedbackItem feedbackItem |
6958 | @r{←} point | lineSegment | polygon | bitmap | pixelRectangle | passThru | |
6959 | point @r{←}@code{GL_POINT_TOKEN} vertex lineSegment | |
6960 | @r{←}@code{GL_LINE_TOKEN} vertex vertex | @code{GL_LINE_RESET_TOKEN} | |
6961 | vertex vertex polygon @r{←}@code{GL_POLYGON_TOKEN} n polySpec polySpec | |
6962 | @r{←} polySpec vertex | vertex vertex vertex bitmap | |
6963 | @r{←}@code{GL_BITMAP_TOKEN} vertex pixelRectangle | |
6964 | @r{←}@code{GL_DRAW_PIXEL_TOKEN} vertex | @code{GL_COPY_PIXEL_TOKEN} | |
6965 | vertex passThru @r{←}@code{GL_PASS_THROUGH_TOKEN} value vertex @r{←} 2d | |
6966 | | 3d | 3dColor | 3dColorTexture | 4dColorTexture 2d @r{←} value value 3d | |
6967 | @r{←} value value value 3dColor @r{←} value value value color | |
6968 | 3dColorTexture @r{←} value value value color tex 4dColorTexture @r{←} | |
6969 | value value value value color tex color @r{←} rgba | index rgba @r{←} | |
6970 | value value value value index @r{←} value tex @r{←} value value value | |
6971 | value | |
8925f36f AW |
6972 | |
6973 | @var{value} is a floating-point number, and @var{n} is a floating-point | |
6974 | integer giving the number of vertices in the polygon. | |
6975 | @code{GL_POINT_TOKEN}, @code{GL_LINE_TOKEN}, @code{GL_LINE_RESET_TOKEN}, | |
6976 | @code{GL_POLYGON_TOKEN}, @code{GL_BITMAP_TOKEN}, | |
6977 | @code{GL_DRAW_PIXEL_TOKEN}, @code{GL_COPY_PIXEL_TOKEN} and | |
6978 | @code{GL_PASS_THROUGH_TOKEN} are symbolic floating-point constants. | |
6979 | @code{GL_LINE_RESET_TOKEN} is returned whenever the line stipple pattern | |
f37e7e3d | 6980 | is reset. The data returned as a vertex depends on the feedback |
8925f36f AW |
6981 | @var{type}. |
6982 | ||
6983 | The following table gives the correspondence between @var{type} and the | |
f37e7e3d | 6984 | number of values per vertex. @var{k} is 1 in color index mode and 4 in |
8925f36f AW |
6985 | RGBA mode. |
6986 | ||
6987 | ||
6988 | ||
6989 | @table @asis | |
6990 | @item @strong{Type} | |
6991 | @strong{Coordinates}, @strong{Color}, @strong{Texture}, @strong{Total | |
6992 | Number of Values} | |
6993 | ||
6994 | @item @code{GL_2D} | |
6995 | @var{x}, @var{y}, , , 2 | |
6996 | ||
6997 | @item @code{GL_3D} | |
6998 | @var{x}, @var{y}, @var{z}, , , 3 | |
6999 | ||
7000 | @item @code{GL_3D_COLOR} | |
3c9b6116 | 7001 | @var{x}, @var{y}, @var{z}, @r{@var{k}}, , @r{3+@var{k}} |
8925f36f AW |
7002 | |
7003 | @item @code{GL_3D_COLOR_TEXTURE} | |
3c9b6116 | 7004 | @var{x}, @var{y}, @var{z}, @r{@var{k}}, 4 , @r{7+@var{k}} |
8925f36f AW |
7005 | |
7006 | @item @code{GL_4D_COLOR_TEXTURE} | |
3c9b6116 | 7007 | @var{x}, @var{y}, @var{z}, @var{w}, @r{@var{k}}, 4 , @r{8+@var{k}} |
8925f36f AW |
7008 | |
7009 | @end table | |
7010 | ||
7011 | Feedback vertex coordinates are in window coordinates, except @var{w}, | |
f37e7e3d DH |
7012 | which is in clip coordinates. Feedback colors are lighted, if lighting |
7013 | is enabled. Feedback texture coordinates are generated, if texture | |
7014 | coordinate generation is enabled. They are always transformed by the | |
8925f36f AW |
7015 | texture matrix. |
7016 | ||
8925f36f AW |
7017 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
7018 | value. | |
7019 | ||
7020 | @code{GL_INVALID_VALUE} is generated if @var{size} is negative. | |
7021 | ||
7022 | @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is | |
7023 | called while the render mode is @code{GL_FEEDBACK}, or if | |
7024 | @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before | |
7025 | @code{glFeedbackBuffer} is called at least once. | |
7026 | ||
7027 | @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is | |
7028 | executed between the execution of @code{glBegin} and the corresponding | |
7029 | execution of @code{glEnd}. | |
7030 | ||
bb894c9d | 7031 | @end deftypefun |
8925f36f | 7032 | |
bb894c9d | 7033 | @deftypefun void glFinish |
3c9b6116 AW |
7034 | Block until all GL execution is complete. |
7035 | ||
8925f36f | 7036 | @code{glFinish} does not return until the effects of all previously |
f37e7e3d | 7037 | called GL commands are complete. Such effects include all changes to GL |
8925f36f AW |
7038 | state, all changes to connection state, and all changes to the frame |
7039 | buffer contents. | |
7040 | ||
8925f36f AW |
7041 | @code{GL_INVALID_OPERATION} is generated if @code{glFinish} is executed |
7042 | between the execution of @code{glBegin} and the corresponding execution | |
7043 | of @code{glEnd}. | |
7044 | ||
bb894c9d | 7045 | @end deftypefun |
8925f36f | 7046 | |
bb894c9d | 7047 | @deftypefun void glFlush |
3c9b6116 AW |
7048 | Force execution of GL commands in finite time. |
7049 | ||
8925f36f AW |
7050 | Different GL implementations buffer commands in several different |
7051 | locations, including network buffers and the graphics accelerator | |
f37e7e3d | 7052 | itself. @code{glFlush} empties all of these buffers, causing all issued |
8925f36f | 7053 | commands to be executed as quickly as they are accepted by the actual |
f37e7e3d | 7054 | rendering engine. Though this execution may not be completed in any |
8925f36f AW |
7055 | particular time period, it does complete in finite time. |
7056 | ||
7057 | Because any GL program might be executed over a network, or on an | |
7058 | accelerator that buffers commands, all programs should call | |
7059 | @code{glFlush} whenever they count on having all of their previously | |
f37e7e3d | 7060 | issued commands completed. For example, call @code{glFlush} before |
8925f36f AW |
7061 | waiting for user input that depends on the generated image. |
7062 | ||
8925f36f AW |
7063 | @code{GL_INVALID_OPERATION} is generated if @code{glFlush} is executed |
7064 | between the execution of @code{glBegin} and the corresponding execution | |
7065 | of @code{glEnd}. | |
7066 | ||
bb894c9d | 7067 | @end deftypefun |
8925f36f | 7068 | |
bb894c9d | 7069 | @deftypefun void glFogCoordPointer type stride pointer |
3c9b6116 AW |
7070 | Define an array of fog coordinates. |
7071 | ||
8925f36f AW |
7072 | @table @asis |
7073 | @item @var{type} | |
f37e7e3d DH |
7074 | Specifies the data type of each fog coordinate. Symbolic constants |
7075 | @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is | |
8925f36f AW |
7076 | @code{GL_FLOAT}. |
7077 | ||
7078 | @item @var{stride} | |
f37e7e3d | 7079 | Specifies the byte offset between consecutive fog coordinates. If |
8925f36f | 7080 | @var{stride} is 0, the array elements are understood to be tightly |
f37e7e3d | 7081 | packed. The initial value is 0. |
8925f36f AW |
7082 | |
7083 | @item @var{pointer} | |
7084 | Specifies a pointer to the first coordinate of the first fog coordinate | |
f37e7e3d | 7085 | in the array. The initial value is 0. |
8925f36f AW |
7086 | |
7087 | @end table | |
7088 | ||
8925f36f | 7089 | @code{glFogCoordPointer} specifies the location and data format of an |
f37e7e3d DH |
7090 | array of fog coordinates to use when rendering. @var{type} specifies the |
7091 | data type of each fog coordinate, and @var{stride} specifies the byte | |
7092 | stride from one fog coordinate to the next, allowing vertices and | |
8925f36f AW |
7093 | attributes to be packed into a single array or stored in separate |
7094 | arrays. | |
7095 | ||
7096 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
7097 | target (see @code{glBindBuffer}) while a fog coordinate array is | |
7098 | specified, @var{pointer} is treated as a byte offset into the buffer | |
f37e7e3d | 7099 | object's data store. Also, the buffer object binding |
8925f36f AW |
7100 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as fog coordinate vertex array |
7101 | client-side state (@code{GL_FOG_COORD_ARRAY_BUFFER_BINDING}). | |
7102 | ||
7103 | When a fog coordinate array is specified, @var{type}, @var{stride}, and | |
7104 | @var{pointer} are saved as client-side state, in addition to the current | |
7105 | vertex array buffer object binding. | |
7106 | ||
7107 | To enable and disable the fog coordinate array, call | |
7108 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
f37e7e3d DH |
7109 | argument @code{GL_FOG_COORD_ARRAY}. If enabled, the fog coordinate array |
7110 | is used when @code{glDrawArrays}, @code{glMultiDrawArrays}, | |
8925f36f AW |
7111 | @code{glDrawElements}, @code{glMultiDrawElements}, |
7112 | @code{glDrawRangeElements}, or @code{glArrayElement} is called. | |
7113 | ||
8925f36f AW |
7114 | @code{GL_INVALID_ENUM} is generated if @var{type} is not either |
7115 | @code{GL_FLOAT} or @code{GL_DOUBLE}. | |
7116 | ||
7117 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
7118 | ||
bb894c9d | 7119 | @end deftypefun |
8925f36f | 7120 | |
d172eed9 AW |
7121 | @deftypefun void glFogCoordd coord |
7122 | @deftypefunx void glFogCoordf coord | |
7123 | @deftypefunx void glFogCoorddv coord | |
7124 | @deftypefunx void glFogCoordfv coord | |
3c9b6116 AW |
7125 | Set the current fog coordinates. |
7126 | ||
8925f36f AW |
7127 | @table @asis |
7128 | @item @var{coord} | |
7129 | Specify the fog distance. | |
7130 | ||
7131 | @end table | |
7132 | ||
8925f36f | 7133 | @code{glFogCoord} specifies the fog coordinate that is associated with |
f37e7e3d | 7134 | each vertex and the current raster position. The value specified is |
8925f36f AW |
7135 | interpolated and used in computing the fog color (see @code{glFog}). |
7136 | ||
bb894c9d | 7137 | @end deftypefun |
8925f36f | 7138 | |
bb894c9d AW |
7139 | @deftypefun void glFogf pname param |
7140 | @deftypefunx void glFogi pname param | |
d172eed9 AW |
7141 | @deftypefunx void glFogfv pname params |
7142 | @deftypefunx void glFogiv pname params | |
3c9b6116 AW |
7143 | Specify fog parameters. |
7144 | ||
8925f36f AW |
7145 | @table @asis |
7146 | @item @var{pname} | |
f37e7e3d | 7147 | Specifies a single-valued fog parameter. @code{GL_FOG_MODE}, |
8925f36f AW |
7148 | @code{GL_FOG_DENSITY}, @code{GL_FOG_START}, @code{GL_FOG_END}, |
7149 | @code{GL_FOG_INDEX}, and @code{GL_FOG_COORD_SRC} are accepted. | |
7150 | ||
7151 | @item @var{param} | |
7152 | Specifies the value that @var{pname} will be set to. | |
7153 | ||
7154 | @end table | |
7155 | ||
f37e7e3d DH |
7156 | Fog is initially disabled. While enabled, fog affects rasterized |
7157 | geometry, bitmaps, and pixel blocks, but not buffer clear operations. To | |
8925f36f AW |
7158 | enable and disable fog, call @code{glEnable} and @code{glDisable} with |
7159 | argument @code{GL_FOG}. | |
7160 | ||
7161 | @code{glFog} assigns the value or values in @var{params} to the fog | |
f37e7e3d | 7162 | parameter specified by @var{pname}. The following values are accepted |
8925f36f AW |
7163 | for @var{pname}: |
7164 | ||
7165 | @table @asis | |
7166 | @item @code{GL_FOG_MODE} | |
7167 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 | 7168 | the equation to be used to compute the fog blend factor, @r{@var{f}}. |
8925f36f | 7169 | Three symbolic constants are accepted: @code{GL_LINEAR}, @code{GL_EXP}, |
f37e7e3d DH |
7170 | and @code{GL_EXP2}. The equations corresponding to these symbolic |
7171 | constants are defined below. The initial fog mode is @code{GL_EXP}. | |
8925f36f AW |
7172 | |
7173 | @item @code{GL_FOG_DENSITY} | |
7174 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 | 7175 | @r{@var{density}}, the fog density used in both exponential fog |
f37e7e3d | 7176 | equations. Only nonnegative densities are accepted. The initial fog |
8925f36f AW |
7177 | density is 1. |
7178 | ||
7179 | @item @code{GL_FOG_START} | |
7180 | @var{params} is a single integer or floating-point value that specifies | |
f37e7e3d | 7181 | @r{@var{start}}, the near distance used in the linear fog equation. The |
3c9b6116 | 7182 | initial near distance is 0. |
8925f36f AW |
7183 | |
7184 | @item @code{GL_FOG_END} | |
7185 | @var{params} is a single integer or floating-point value that specifies | |
f37e7e3d | 7186 | @r{@var{end}}, the far distance used in the linear fog equation. The |
8925f36f AW |
7187 | initial far distance is 1. |
7188 | ||
7189 | @item @code{GL_FOG_INDEX} | |
7190 | @var{params} is a single integer or floating-point value that specifies | |
f37e7e3d | 7191 | @r{@var{i}_@var{f}}, the fog color index. The initial fog index is 0. |
8925f36f AW |
7192 | |
7193 | @item @code{GL_FOG_COLOR} | |
7194 | @var{params} contains four integer or floating-point values that specify | |
f37e7e3d | 7195 | @r{@var{C}_@var{f}}, the fog color. Integer values are mapped linearly |
3c9b6116 | 7196 | such that the most positive representable value maps to 1.0, and the |
f37e7e3d DH |
7197 | most negative representable value maps to @r{-1.0}. Floating-point |
7198 | values are mapped directly. After conversion, all color components are | |
7199 | clamped to the range @r{[0,1]}. The initial fog color is (0, 0, 0, 0). | |
8925f36f AW |
7200 | |
7201 | @item @code{GL_FOG_COORD_SRC} | |
7202 | @var{params} contains either of the following symbolic constants: | |
f37e7e3d | 7203 | @code{GL_FOG_COORD} or @code{GL_FRAGMENT_DEPTH}. @code{GL_FOG_COORD} |
8925f36f | 7204 | specifies that the current fog coordinate should be used as distance |
f37e7e3d | 7205 | value in the fog color computation. @code{GL_FRAGMENT_DEPTH} specifies |
8925f36f AW |
7206 | that the current fragment depth should be used as distance value in the |
7207 | fog computation. | |
7208 | ||
7209 | @end table | |
7210 | ||
7211 | Fog blends a fog color with each rasterized pixel fragment's | |
f37e7e3d | 7212 | post-texturing color using a blending factor @r{@var{f}}. Factor |
3c9b6116 AW |
7213 | @r{@var{f}} is computed in one of three ways, depending on the fog mode. |
7214 | Let @r{@var{c}} be either the distance in eye coordinate from the origin | |
7215 | (in the case that the @code{GL_FOG_COORD_SRC} is | |
8925f36f | 7216 | @code{GL_FRAGMENT_DEPTH}) or the current fog coordinate (in the case |
f37e7e3d | 7217 | that @code{GL_FOG_COORD_SRC} is @code{GL_FOG_COORD}). The equation for |
8925f36f | 7218 | @code{GL_LINEAR} fog is |
3c9b6116 | 7219 | @r{@var{f}=@var{end}-@var{c},/@var{end}-@var{start},} |
8925f36f AW |
7220 | |
7221 | The equation for @code{GL_EXP} fog is | |
3c9b6116 | 7222 | @r{@var{f}=@var{e}^-(@var{density}·@var{c},),} |
8925f36f AW |
7223 | |
7224 | The equation for @code{GL_EXP2} fog is | |
3c9b6116 | 7225 | @r{@var{f}=@var{e}^-(@var{density}·@var{c},),^2} |
8925f36f | 7226 | |
3c9b6116 | 7227 | Regardless of the fog mode, @r{@var{f}} is clamped to the range |
f37e7e3d | 7228 | @r{[0,1]} after it is computed. Then, if the GL is in RGBA color mode, |
3c9b6116 AW |
7229 | the fragment's red, green, and blue colors, represented by |
7230 | @r{@var{C}_@var{r}}, are replaced by | |
8925f36f | 7231 | |
3c9b6116 | 7232 | @r{@var{C}_@var{r},^″=@var{f}×@var{C}_@var{r}+(1-@var{f},)×@var{C}_@var{f}} |
8925f36f AW |
7233 | |
7234 | Fog does not affect a fragment's alpha component. | |
7235 | ||
3c9b6116 AW |
7236 | In color index mode, the fragment's color index @r{@var{i}_@var{r}} is |
7237 | replaced by | |
8925f36f | 7238 | |
3c9b6116 | 7239 | @r{@var{i}_@var{r},^″=@var{i}_@var{r}+(1-@var{f},)×@var{i}_@var{f}} |
8925f36f AW |
7240 | |
7241 | ||
7242 | ||
8925f36f AW |
7243 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
7244 | value, or if @var{pname} is @code{GL_FOG_MODE} and @var{params} is not | |
7245 | an accepted value. | |
7246 | ||
7247 | @code{GL_INVALID_VALUE} is generated if @var{pname} is | |
7248 | @code{GL_FOG_DENSITY} and @var{params} is negative. | |
7249 | ||
7250 | @code{GL_INVALID_OPERATION} is generated if @code{glFog} is executed | |
7251 | between the execution of @code{glBegin} and the corresponding execution | |
7252 | of @code{glEnd}. | |
7253 | ||
bb894c9d | 7254 | @end deftypefun |
8925f36f | 7255 | |
bb894c9d | 7256 | @deftypefun void glFrontFace mode |
3c9b6116 AW |
7257 | Define front- and back-facing polygons. |
7258 | ||
8925f36f AW |
7259 | @table @asis |
7260 | @item @var{mode} | |
f37e7e3d DH |
7261 | Specifies the orientation of front-facing polygons. @code{GL_CW} and |
7262 | @code{GL_CCW} are accepted. The initial value is @code{GL_CCW}. | |
8925f36f AW |
7263 | |
7264 | @end table | |
7265 | ||
8925f36f | 7266 | In a scene composed entirely of opaque closed surfaces, back-facing |
f37e7e3d DH |
7267 | polygons are never visible. Eliminating these invisible polygons has the |
7268 | obvious benefit of speeding up the rendering of the image. To enable and | |
7269 | disable elimination of back-facing polygons, call @code{glEnable} and | |
7270 | @code{glDisable} with argument @code{GL_CULL_FACE}. | |
8925f36f AW |
7271 | |
7272 | The projection of a polygon to window coordinates is said to have | |
7273 | clockwise winding if an imaginary object following the path from its | |
7274 | first vertex, its second vertex, and so on, to its last vertex, and | |
7275 | finally back to its first vertex, moves in a clockwise direction about | |
f37e7e3d | 7276 | the interior of the polygon. The polygon's winding is said to be |
8925f36f AW |
7277 | counterclockwise if the imaginary object following the same path moves |
7278 | in a counterclockwise direction about the interior of the polygon. | |
7279 | @code{glFrontFace} specifies whether polygons with clockwise winding in | |
7280 | window coordinates, or counterclockwise winding in window coordinates, | |
f37e7e3d | 7281 | are taken to be front-facing. Passing @code{GL_CCW} to @var{mode} |
8925f36f | 7282 | selects counterclockwise polygons as front-facing; @code{GL_CW} selects |
f37e7e3d | 7283 | clockwise polygons as front-facing. By default, counterclockwise |
8925f36f AW |
7284 | polygons are taken to be front-facing. |
7285 | ||
8925f36f AW |
7286 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
7287 | value. | |
7288 | ||
7289 | @code{GL_INVALID_OPERATION} is generated if @code{glFrontFace} is | |
7290 | executed between the execution of @code{glBegin} and the corresponding | |
7291 | execution of @code{glEnd}. | |
7292 | ||
bb894c9d | 7293 | @end deftypefun |
8925f36f | 7294 | |
bb894c9d | 7295 | @deftypefun void glFrustum left right bottom top nearVal farVal |
3c9b6116 AW |
7296 | Multiply the current matrix by a perspective matrix. |
7297 | ||
8925f36f AW |
7298 | @table @asis |
7299 | @item @var{left} | |
7300 | @itemx @var{right} | |
7301 | Specify the coordinates for the left and right vertical clipping planes. | |
7302 | ||
7303 | @item @var{bottom} | |
7304 | @itemx @var{top} | |
7305 | Specify the coordinates for the bottom and top horizontal clipping | |
7306 | planes. | |
7307 | ||
7308 | @item @var{nearVal} | |
7309 | @itemx @var{farVal} | |
f37e7e3d | 7310 | Specify the distances to the near and far depth clipping planes. Both |
8925f36f AW |
7311 | distances must be positive. |
7312 | ||
7313 | @end table | |
7314 | ||
8925f36f | 7315 | @code{glFrustum} describes a perspective matrix that produces a |
f37e7e3d | 7316 | perspective projection. The current matrix (see @code{glMatrixMode}) is |
8925f36f AW |
7317 | multiplied by this matrix and the result replaces the current matrix, as |
7318 | if @code{glMultMatrix} were called with the following matrix as its | |
7319 | argument: | |
7320 | ||
7321 | ||
7322 | ||
3c9b6116 | 7323 | @r{[(2@var{nearVal},/@var{right}-@var{left},, 0 @var{A} 0), (0 |
8925f36f AW |
7324 | 2@var{nearVal},/@var{top}-@var{bottom},, @var{B} 0), (0 0 @var{C} |
7325 | @var{D}), (0 0 -1 0),]} | |
7326 | ||
3c9b6116 | 7327 | @r{@var{A}=@var{right}+@var{left},/@var{right}-@var{left},} |
8925f36f | 7328 | |
3c9b6116 | 7329 | @r{@var{B}=@var{top}+@var{bottom},/@var{top}-@var{bottom},} |
8925f36f | 7330 | |
3c9b6116 | 7331 | @r{@var{C}=-@var{farVal}+@var{nearVal},/@var{farVal}-@var{nearVal},,} |
8925f36f | 7332 | |
3c9b6116 | 7333 | @r{@var{D}=-2@var{farVal}@var{nearVal},/@var{farVal}-@var{nearVal},,} |
8925f36f AW |
7334 | |
7335 | ||
7336 | ||
7337 | Typically, the matrix mode is @code{GL_PROJECTION}, and | |
3c9b6116 AW |
7338 | @r{(@var{left},@var{bottom}-@var{nearVal})} and |
7339 | @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near | |
7340 | clipping plane that are mapped to the lower left and upper right corners | |
7341 | of the window, assuming that the eye is located at (0, 0, 0). | |
f37e7e3d | 7342 | @r{-@var{farVal}} specifies the location of the far clipping plane. Both |
3c9b6116 | 7343 | @var{nearVal} and @var{farVal} must be positive. |
8925f36f AW |
7344 | |
7345 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
7346 | current matrix stack. | |
7347 | ||
8925f36f AW |
7348 | @code{GL_INVALID_VALUE} is generated if @var{nearVal} or @var{farVal} is |
7349 | not positive, or if @var{left} = @var{right}, or @var{bottom} = | |
7350 | @var{top}, or @var{near} = @var{far}. | |
7351 | ||
7352 | @code{GL_INVALID_OPERATION} is generated if @code{glFrustum} is executed | |
7353 | between the execution of @code{glBegin} and the corresponding execution | |
7354 | of @code{glEnd}. | |
7355 | ||
bb894c9d | 7356 | @end deftypefun |
8925f36f | 7357 | |
bb894c9d | 7358 | @deftypefun void glGenBuffers n buffers |
3c9b6116 AW |
7359 | Generate buffer object names. |
7360 | ||
8925f36f AW |
7361 | @table @asis |
7362 | @item @var{n} | |
7363 | Specifies the number of buffer object names to be generated. | |
7364 | ||
7365 | @item @var{buffers} | |
7366 | Specifies an array in which the generated buffer object names are | |
7367 | stored. | |
7368 | ||
7369 | @end table | |
7370 | ||
8925f36f | 7371 | @code{glGenBuffers} returns @var{n} buffer object names in |
f37e7e3d | 7372 | @var{buffers}. There is no guarantee that the names form a contiguous |
8925f36f AW |
7373 | set of integers; however, it is guaranteed that none of the returned |
7374 | names was in use immediately before the call to @code{glGenBuffers}. | |
7375 | ||
7376 | Buffer object names returned by a call to @code{glGenBuffers} are not | |
7377 | returned by subsequent calls, unless they are first deleted with | |
7378 | @code{glDeleteBuffers}. | |
7379 | ||
7380 | No buffer objects are associated with the returned buffer object names | |
7381 | until they are first bound by calling @code{glBindBuffer}. | |
7382 | ||
8925f36f AW |
7383 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
7384 | ||
7385 | @code{GL_INVALID_OPERATION} is generated if @code{glGenBuffers} is | |
7386 | executed between the execution of @code{glBegin} and the corresponding | |
7387 | execution of @code{glEnd}. | |
7388 | ||
bb894c9d | 7389 | @end deftypefun |
8925f36f | 7390 | |
bb894c9d | 7391 | @deftypefun GLuint glGenLists range |
3c9b6116 AW |
7392 | Generate a contiguous set of empty display lists. |
7393 | ||
8925f36f AW |
7394 | @table @asis |
7395 | @item @var{range} | |
7396 | Specifies the number of contiguous empty display lists to be generated. | |
7397 | ||
7398 | @end table | |
7399 | ||
f37e7e3d | 7400 | @code{glGenLists} has one argument, @var{range}. It returns an integer |
8925f36f | 7401 | @var{n} such that @var{range} contiguous empty display lists, named |
3c9b6116 | 7402 | @r{@var{n}}, @r{@var{n}+1}, @r{@var{...}}, @r{@var{n}+@var{range}-1}, |
f37e7e3d | 7403 | are created. If @var{range} is 0, if there is no group of @var{range} |
3c9b6116 AW |
7404 | contiguous names available, or if any error is generated, no display |
7405 | lists are generated, and 0 is returned. | |
8925f36f | 7406 | |
8925f36f AW |
7407 | @code{GL_INVALID_VALUE} is generated if @var{range} is negative. |
7408 | ||
7409 | @code{GL_INVALID_OPERATION} is generated if @code{glGenLists} is | |
7410 | executed between the execution of @code{glBegin} and the corresponding | |
7411 | execution of @code{glEnd}. | |
7412 | ||
bb894c9d | 7413 | @end deftypefun |
8925f36f | 7414 | |
bb894c9d | 7415 | @deftypefun void glGenQueries n ids |
3c9b6116 AW |
7416 | Generate query object names. |
7417 | ||
8925f36f AW |
7418 | @table @asis |
7419 | @item @var{n} | |
7420 | Specifies the number of query object names to be generated. | |
7421 | ||
7422 | @item @var{ids} | |
7423 | Specifies an array in which the generated query object names are stored. | |
7424 | ||
7425 | @end table | |
7426 | ||
8925f36f AW |
7427 | @code{glGenQueries} returns @var{n} query object names in @var{ids}. |
7428 | There is no guarantee that the names form a contiguous set of integers; | |
7429 | however, it is guaranteed that none of the returned names was in use | |
7430 | immediately before the call to @code{glGenQueries}. | |
7431 | ||
7432 | Query object names returned by a call to @code{glGenQueries} are not | |
7433 | returned by subsequent calls, unless they are first deleted with | |
7434 | @code{glDeleteQueries}. | |
7435 | ||
7436 | No query objects are associated with the returned query object names | |
7437 | until they are first used by calling @code{glBeginQuery}. | |
7438 | ||
8925f36f AW |
7439 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
7440 | ||
7441 | @code{GL_INVALID_OPERATION} is generated if @code{glGenQueries} is | |
7442 | executed between the execution of @code{glBegin} and the corresponding | |
7443 | execution of @code{glEnd}. | |
7444 | ||
bb894c9d | 7445 | @end deftypefun |
8925f36f | 7446 | |
bb894c9d | 7447 | @deftypefun void glGenTextures n textures |
3c9b6116 AW |
7448 | Generate texture names. |
7449 | ||
8925f36f AW |
7450 | @table @asis |
7451 | @item @var{n} | |
7452 | Specifies the number of texture names to be generated. | |
7453 | ||
7454 | @item @var{textures} | |
7455 | Specifies an array in which the generated texture names are stored. | |
7456 | ||
7457 | @end table | |
7458 | ||
8925f36f AW |
7459 | @code{glGenTextures} returns @var{n} texture names in @var{textures}. |
7460 | There is no guarantee that the names form a contiguous set of integers; | |
7461 | however, it is guaranteed that none of the returned names was in use | |
7462 | immediately before the call to @code{glGenTextures}. | |
7463 | ||
7464 | The generated textures have no dimensionality; they assume the | |
7465 | dimensionality of the texture target to which they are first bound (see | |
7466 | @code{glBindTexture}). | |
7467 | ||
7468 | Texture names returned by a call to @code{glGenTextures} are not | |
7469 | returned by subsequent calls, unless they are first deleted with | |
7470 | @code{glDeleteTextures}. | |
7471 | ||
8925f36f AW |
7472 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
7473 | ||
7474 | @code{GL_INVALID_OPERATION} is generated if @code{glGenTextures} is | |
7475 | executed between the execution of @code{glBegin} and the corresponding | |
7476 | execution of @code{glEnd}. | |
7477 | ||
bb894c9d | 7478 | @end deftypefun |
8925f36f | 7479 | |
bb894c9d | 7480 | @deftypefun void glGetActiveAttrib program index bufSize length size type name |
3c9b6116 AW |
7481 | Returns information about an active attribute variable for the specified |
7482 | program object. | |
7483 | ||
8925f36f AW |
7484 | @table @asis |
7485 | @item @var{program} | |
7486 | Specifies the program object to be queried. | |
7487 | ||
7488 | @item @var{index} | |
7489 | Specifies the index of the attribute variable to be queried. | |
7490 | ||
7491 | @item @var{bufSize} | |
7492 | Specifies the maximum number of characters OpenGL is allowed to write in | |
7493 | the character buffer indicated by @var{name}. | |
7494 | ||
7495 | @item @var{length} | |
7496 | Returns the number of characters actually written by OpenGL in the | |
7497 | string indicated by @var{name} (excluding the null terminator) if a | |
7498 | value other than @code{NULL} is passed. | |
7499 | ||
7500 | @item @var{size} | |
7501 | Returns the size of the attribute variable. | |
7502 | ||
7503 | @item @var{type} | |
7504 | Returns the data type of the attribute variable. | |
7505 | ||
7506 | @item @var{name} | |
7507 | Returns a null terminated string containing the name of the attribute | |
7508 | variable. | |
7509 | ||
7510 | @end table | |
7511 | ||
8925f36f | 7512 | @code{glGetActiveAttrib} returns information about an active attribute |
f37e7e3d DH |
7513 | variable in the program object specified by @var{program}. The number of |
7514 | active attributes can be obtained by calling @code{glGetProgram} with | |
7515 | the value @code{GL_ACTIVE_ATTRIBUTES}. A value of 0 for @var{index} | |
7516 | selects the first active attribute variable. Permissible values for | |
8925f36f AW |
7517 | @var{index} range from 0 to the number of active attribute variables |
7518 | minus 1. | |
7519 | ||
7520 | A vertex shader may use either built-in attribute variables, | |
f37e7e3d | 7521 | user-defined attribute variables, or both. Built-in attribute variables |
8925f36f AW |
7522 | have a prefix of "gl_" and reference conventional OpenGL vertex |
7523 | attribtes (e.g., @var{gl_Vertex}, @var{gl_Normal}, etc., see the OpenGL | |
7524 | Shading Language specification for a complete list.) User-defined | |
7525 | attribute variables have arbitrary names and obtain their values through | |
f37e7e3d | 7526 | numbered generic vertex attributes. An attribute variable (either |
8925f36f AW |
7527 | built-in or user-defined) is considered active if it is determined |
7528 | during the link operation that it may be accessed during program | |
f37e7e3d | 7529 | execution. Therefore, @var{program} should have previously been the |
8925f36f AW |
7530 | target of a call to @code{glLinkProgram}, but it is not necessary for it |
7531 | to have been linked successfully. | |
7532 | ||
7533 | The size of the character buffer required to store the longest attribute | |
7534 | variable name in @var{program} can be obtained by calling | |
7535 | @code{glGetProgram} with the value | |
f37e7e3d | 7536 | @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}. This value should be used to |
8925f36f | 7537 | allocate a buffer of sufficient size to store the returned attribute |
f37e7e3d | 7538 | name. The size of this character buffer is passed in @var{bufSize}, and |
8925f36f AW |
7539 | a pointer to this character buffer is passed in @var{name}. |
7540 | ||
7541 | @code{glGetActiveAttrib} returns the name of the attribute variable | |
7542 | indicated by @var{index}, storing it in the character buffer specified | |
f37e7e3d | 7543 | by @var{name}. The string returned will be null terminated. The actual |
8925f36f AW |
7544 | number of characters written into this buffer is returned in |
7545 | @var{length}, and this count does not include the null termination | |
f37e7e3d DH |
7546 | character. If the length of the returned string is not required, a value |
7547 | of @code{NULL} can be passed in the @var{length} argument. | |
8925f36f AW |
7548 | |
7549 | The @var{type} argument will return a pointer to the attribute | |
f37e7e3d | 7550 | variable's data type. The symbolic constants @code{GL_FLOAT}, |
8925f36f AW |
7551 | @code{GL_FLOAT_VEC2}, @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4}, |
7552 | @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3}, @code{GL_FLOAT_MAT4}, | |
7553 | @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4}, @code{GL_FLOAT_MAT3x2}, | |
7554 | @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2}, or | |
f37e7e3d | 7555 | @code{GL_FLOAT_MAT4x3} may be returned. The @var{size} argument will |
8925f36f AW |
7556 | return the size of the attribute, in units of the type returned in |
7557 | @var{type}. | |
7558 | ||
7559 | The list of active attribute variables may include both built-in | |
7560 | attribute variables (which begin with the prefix "gl_") as well as | |
7561 | user-defined attribute variable names. | |
7562 | ||
7563 | This function will return as much information as it can about the | |
f37e7e3d DH |
7564 | specified active attribute variable. If no information is available, |
7565 | @var{length} will be 0, and @var{name} will be an empty string. This | |
8925f36f | 7566 | situation could occur if this function is called after a link operation |
f37e7e3d | 7567 | that failed. If an error occurs, the return values @var{length}, |
8925f36f AW |
7568 | @var{size}, @var{type}, and @var{name} will be unmodified. |
7569 | ||
8925f36f AW |
7570 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
7571 | generated by OpenGL. | |
7572 | ||
7573 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7574 | program object. | |
7575 | ||
7576 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
7577 | equal to the number of active attribute variables in @var{program}. | |
7578 | ||
7579 | @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveAttrib} is | |
7580 | executed between the execution of @code{glBegin} and the corresponding | |
7581 | execution of @code{glEnd}. | |
7582 | ||
7583 | @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0. | |
7584 | ||
bb894c9d | 7585 | @end deftypefun |
8925f36f | 7586 | |
bb894c9d | 7587 | @deftypefun void glGetActiveUniform program index bufSize length size type name |
3c9b6116 AW |
7588 | Returns information about an active uniform variable for the specified |
7589 | program object. | |
7590 | ||
8925f36f AW |
7591 | @table @asis |
7592 | @item @var{program} | |
7593 | Specifies the program object to be queried. | |
7594 | ||
7595 | @item @var{index} | |
7596 | Specifies the index of the uniform variable to be queried. | |
7597 | ||
7598 | @item @var{bufSize} | |
7599 | Specifies the maximum number of characters OpenGL is allowed to write in | |
7600 | the character buffer indicated by @var{name}. | |
7601 | ||
7602 | @item @var{length} | |
7603 | Returns the number of characters actually written by OpenGL in the | |
7604 | string indicated by @var{name} (excluding the null terminator) if a | |
7605 | value other than @code{NULL} is passed. | |
7606 | ||
7607 | @item @var{size} | |
7608 | Returns the size of the uniform variable. | |
7609 | ||
7610 | @item @var{type} | |
7611 | Returns the data type of the uniform variable. | |
7612 | ||
7613 | @item @var{name} | |
7614 | Returns a null terminated string containing the name of the uniform | |
7615 | variable. | |
7616 | ||
7617 | @end table | |
7618 | ||
8925f36f | 7619 | @code{glGetActiveUniform} returns information about an active uniform |
f37e7e3d DH |
7620 | variable in the program object specified by @var{program}. The number of |
7621 | active uniform variables can be obtained by calling @code{glGetProgram} | |
7622 | with the value @code{GL_ACTIVE_UNIFORMS}. A value of 0 for @var{index} | |
7623 | selects the first active uniform variable. Permissible values for | |
7624 | @var{index} range from 0 to the number of active uniform variables minus | |
7625 | 1. | |
8925f36f AW |
7626 | |
7627 | Shaders may use either built-in uniform variables, user-defined uniform | |
f37e7e3d | 7628 | variables, or both. Built-in uniform variables have a prefix of "gl_" |
8925f36f AW |
7629 | and reference existing OpenGL state or values derived from such state |
7630 | (e.g., @var{gl_Fog}, @var{gl_ModelViewMatrix}, etc., see the OpenGL | |
7631 | Shading Language specification for a complete list.) User-defined | |
7632 | uniform variables have arbitrary names and obtain their values from the | |
f37e7e3d | 7633 | application through calls to @code{glUniform}. A uniform variable |
8925f36f AW |
7634 | (either built-in or user-defined) is considered active if it is |
7635 | determined during the link operation that it may be accessed during | |
f37e7e3d | 7636 | program execution. Therefore, @var{program} should have previously been |
8925f36f AW |
7637 | the target of a call to @code{glLinkProgram}, but it is not necessary |
7638 | for it to have been linked successfully. | |
7639 | ||
7640 | The size of the character buffer required to store the longest uniform | |
7641 | variable name in @var{program} can be obtained by calling | |
7642 | @code{glGetProgram} with the value @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}. | |
7643 | This value should be used to allocate a buffer of sufficient size to | |
f37e7e3d | 7644 | store the returned uniform variable name. The size of this character |
8925f36f AW |
7645 | buffer is passed in @var{bufSize}, and a pointer to this character |
7646 | buffer is passed in @var{name.} | |
7647 | ||
7648 | @code{glGetActiveUniform} returns the name of the uniform variable | |
7649 | indicated by @var{index}, storing it in the character buffer specified | |
f37e7e3d | 7650 | by @var{name}. The string returned will be null terminated. The actual |
8925f36f AW |
7651 | number of characters written into this buffer is returned in |
7652 | @var{length}, and this count does not include the null termination | |
f37e7e3d DH |
7653 | character. If the length of the returned string is not required, a value |
7654 | of @code{NULL} can be passed in the @var{length} argument. | |
8925f36f AW |
7655 | |
7656 | The @var{type} argument will return a pointer to the uniform variable's | |
f37e7e3d DH |
7657 | data type. The symbolic constants @code{GL_FLOAT}, @code{GL_FLOAT_VEC2}, |
7658 | @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4}, @code{GL_INT}, | |
7659 | @code{GL_INT_VEC2}, @code{GL_INT_VEC3}, @code{GL_INT_VEC4}, | |
7660 | @code{GL_BOOL}, @code{GL_BOOL_VEC2}, @code{GL_BOOL_VEC3}, | |
7661 | @code{GL_BOOL_VEC4}, @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3}, | |
7662 | @code{GL_FLOAT_MAT4}, @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4}, | |
7663 | @code{GL_FLOAT_MAT3x2}, @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2}, | |
7664 | @code{GL_FLOAT_MAT4x3}, @code{GL_SAMPLER_1D}, @code{GL_SAMPLER_2D}, | |
7665 | @code{GL_SAMPLER_3D}, @code{GL_SAMPLER_CUBE}, | |
8925f36f AW |
7666 | @code{GL_SAMPLER_1D_SHADOW}, or @code{GL_SAMPLER_2D_SHADOW} may be |
7667 | returned. | |
7668 | ||
7669 | If one or more elements of an array are active, the name of the array is | |
7670 | returned in @var{name}, the type is returned in @var{type}, and the | |
7671 | @var{size} parameter returns the highest array element index used, plus | |
f37e7e3d | 7672 | one, as determined by the compiler and/or linker. Only one active |
8925f36f AW |
7673 | uniform variable will be reported for a uniform array. |
7674 | ||
7675 | Uniform variables that are declared as structures or arrays of | |
f37e7e3d DH |
7676 | structures will not be returned directly by this function. Instead, each |
7677 | of these uniform variables will be reduced to its fundamental components | |
7678 | containing the "." and "[]" operators such that each of the names is | |
7679 | valid as an argument to @code{glGetUniformLocation}. Each of these | |
7680 | reduced uniform variables is counted as one active uniform variable and | |
7681 | is assigned an index. A valid name cannot be a structure, an array of | |
7682 | structures, or a subcomponent of a vector or matrix. | |
7683 | ||
7684 | The size of the uniform variable will be returned in @var{size}. Uniform | |
7685 | variables other than arrays will have a size of 1. Structures and arrays | |
7686 | of structures will be reduced as described earlier, such that each of | |
7687 | the names returned will be a data type in the earlier list. If this | |
7688 | reduction results in an array, the size returned will be as described | |
7689 | for uniform arrays; otherwise, the size returned will be 1. | |
8925f36f AW |
7690 | |
7691 | The list of active uniform variables may include both built-in uniform | |
7692 | variables (which begin with the prefix "gl_") as well as user-defined | |
7693 | uniform variable names. | |
7694 | ||
7695 | This function will return as much information as it can about the | |
f37e7e3d DH |
7696 | specified active uniform variable. If no information is available, |
7697 | @var{length} will be 0, and @var{name} will be an empty string. This | |
8925f36f | 7698 | situation could occur if this function is called after a link operation |
f37e7e3d | 7699 | that failed. If an error occurs, the return values @var{length}, |
8925f36f AW |
7700 | @var{size}, @var{type}, and @var{name} will be unmodified. |
7701 | ||
8925f36f AW |
7702 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
7703 | generated by OpenGL. | |
7704 | ||
7705 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7706 | program object. | |
7707 | ||
7708 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
7709 | equal to the number of active uniform variables in @var{program}. | |
7710 | ||
7711 | @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveUniform} is | |
7712 | executed between the execution of @code{glBegin} and the corresponding | |
7713 | execution of @code{glEnd}. | |
7714 | ||
7715 | @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0. | |
7716 | ||
bb894c9d | 7717 | @end deftypefun |
8925f36f | 7718 | |
bb894c9d | 7719 | @deftypefun void glGetAttachedShaders program maxCount count shaders |
3c9b6116 AW |
7720 | Returns the handles of the shader objects attached to a program object. |
7721 | ||
8925f36f AW |
7722 | @table @asis |
7723 | @item @var{program} | |
7724 | Specifies the program object to be queried. | |
7725 | ||
7726 | @item @var{maxCount} | |
7727 | Specifies the size of the array for storing the returned object names. | |
7728 | ||
7729 | @item @var{count} | |
7730 | Returns the number of names actually returned in @var{objects}. | |
7731 | ||
7732 | @item @var{shaders} | |
7733 | Specifies an array that is used to return the names of attached shader | |
7734 | objects. | |
7735 | ||
7736 | @end table | |
7737 | ||
8925f36f | 7738 | @code{glGetAttachedShaders} returns the names of the shader objects |
f37e7e3d DH |
7739 | attached to @var{program}. The names of shader objects that are attached |
7740 | to @var{program} will be returned in @var{shaders.} The actual number of | |
7741 | shader names written into @var{shaders} is returned in @var{count.} If | |
7742 | no shader objects are attached to @var{program}, @var{count} is set to | |
7743 | 0. The maximum number of shader names that may be returned in | |
7744 | @var{shaders} is specified by @var{maxCount}. | |
8925f36f AW |
7745 | |
7746 | If the number of names actually returned is not required (for instance, | |
7747 | if it has just been obtained by calling @code{glGetProgram}), a value of | |
f37e7e3d DH |
7748 | @code{NULL} may be passed for count. If no shader objects are attached |
7749 | to @var{program}, a value of 0 will be returned in @var{count}. The | |
8925f36f AW |
7750 | actual number of attached shaders can be obtained by calling |
7751 | @code{glGetProgram} with the value @code{GL_ATTACHED_SHADERS}. | |
7752 | ||
8925f36f AW |
7753 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
7754 | generated by OpenGL. | |
7755 | ||
7756 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7757 | program object. | |
7758 | ||
7759 | @code{GL_INVALID_VALUE} is generated if @var{maxCount} is less than 0. | |
7760 | ||
7761 | @code{GL_INVALID_OPERATION} is generated if @code{glGetAttachedShaders} | |
7762 | is executed between the execution of @code{glBegin} and the | |
7763 | corresponding execution of @code{glEnd}. | |
7764 | ||
bb894c9d | 7765 | @end deftypefun |
8925f36f | 7766 | |
bb894c9d | 7767 | @deftypefun GLint glGetAttribLocation program name |
3c9b6116 AW |
7768 | Returns the location of an attribute variable. |
7769 | ||
8925f36f AW |
7770 | @table @asis |
7771 | @item @var{program} | |
7772 | Specifies the program object to be queried. | |
7773 | ||
7774 | @item @var{name} | |
7775 | Points to a null terminated string containing the name of the attribute | |
7776 | variable whose location is to be queried. | |
7777 | ||
7778 | @end table | |
7779 | ||
8925f36f AW |
7780 | @code{glGetAttribLocation} queries the previously linked program object |
7781 | specified by @var{program} for the attribute variable specified by | |
7782 | @var{name} and returns the index of the generic vertex attribute that is | |
f37e7e3d DH |
7783 | bound to that attribute variable. If @var{name} is a matrix attribute |
7784 | variable, the index of the first column of the matrix is returned. If | |
8925f36f AW |
7785 | the named attribute variable is not an active attribute in the specified |
7786 | program object or if @var{name} starts with the reserved prefix "gl_", a | |
7787 | value of -1 is returned. | |
7788 | ||
7789 | The association between an attribute variable name and a generic | |
7790 | attribute index can be specified at any time by calling | |
f37e7e3d DH |
7791 | @code{glBindAttribLocation}. Attribute bindings do not go into effect |
7792 | until @code{glLinkProgram} is called. After a program object has been | |
8925f36f | 7793 | linked successfully, the index values for attribute variables remain |
f37e7e3d | 7794 | fixed until the next link command occurs. The attribute values can only |
8925f36f AW |
7795 | be queried after a link if the link was successful. |
7796 | @code{glGetAttribLocation} returns the binding that actually went into | |
7797 | effect the last time @code{glLinkProgram} was called for the specified | |
f37e7e3d | 7798 | program object. Attribute bindings that have been specified since the |
8925f36f AW |
7799 | last link operation are not returned by @code{glGetAttribLocation}. |
7800 | ||
8925f36f AW |
7801 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a value |
7802 | generated by OpenGL. | |
7803 | ||
7804 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7805 | program object. | |
7806 | ||
7807 | @code{GL_INVALID_OPERATION} is generated if @var{program} has not been | |
7808 | successfully linked. | |
7809 | ||
7810 | @code{GL_INVALID_OPERATION} is generated if @code{glGetAttribLocation} | |
7811 | is executed between the execution of @code{glBegin} and the | |
7812 | corresponding execution of @code{glEnd}. | |
7813 | ||
bb894c9d | 7814 | @end deftypefun |
8925f36f | 7815 | |
b002944d AW |
7816 | @deftypefun void glGetBufferParameteriv target value data |
7817 | Return parameters of a buffer object. | |
7818 | ||
7819 | @table @asis | |
7820 | @item @var{target} | |
f37e7e3d | 7821 | Specifies the target buffer object. The symbolic constant must be |
b002944d AW |
7822 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
7823 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7824 | ||
7825 | @item @var{value} | |
f37e7e3d | 7826 | Specifies the symbolic name of a buffer object parameter. Accepted |
b002944d AW |
7827 | values are @code{GL_BUFFER_ACCESS}, @code{GL_BUFFER_MAPPED}, |
7828 | @code{GL_BUFFER_SIZE}, or @code{GL_BUFFER_USAGE}. | |
7829 | ||
7830 | @item @var{data} | |
7831 | Returns the requested parameter. | |
7832 | ||
7833 | @end table | |
7834 | ||
7835 | @code{glGetBufferParameteriv} returns in @var{data} a selected parameter | |
7836 | of the buffer object specified by @var{target}. | |
7837 | ||
7838 | @var{value} names a specific buffer object parameter, as follows: | |
7839 | ||
7840 | @table @asis | |
7841 | @item @code{GL_BUFFER_ACCESS} | |
7842 | @var{params} returns the access policy set while mapping the buffer | |
f37e7e3d | 7843 | object. The initial value is @code{GL_READ_WRITE}. |
b002944d AW |
7844 | |
7845 | @item @code{GL_BUFFER_MAPPED} | |
7846 | @var{params} returns a flag indicating whether the buffer object is | |
f37e7e3d | 7847 | currently mapped. The initial value is @code{GL_FALSE}. |
b002944d AW |
7848 | |
7849 | @item @code{GL_BUFFER_SIZE} | |
7850 | @var{params} returns the size of the buffer object, measured in bytes. | |
7851 | The initial value is 0. | |
7852 | ||
7853 | @item @code{GL_BUFFER_USAGE} | |
f37e7e3d | 7854 | @var{params} returns the buffer object's usage pattern. The initial |
b002944d AW |
7855 | value is @code{GL_STATIC_DRAW}. |
7856 | ||
7857 | @end table | |
7858 | ||
7859 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{value} is | |
7860 | not an accepted value. | |
7861 | ||
7862 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
7863 | name 0 is bound to @var{target}. | |
7864 | ||
7865 | @code{GL_INVALID_OPERATION} is generated if | |
7866 | @code{glGetBufferParameteriv} is executed between the execution of | |
7867 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
7868 | ||
7869 | @end deftypefun | |
7870 | ||
7871 | @deftypefun void glGetBufferPointerv target pname params | |
7872 | Return the pointer to a mapped buffer object's data store. | |
7873 | ||
7874 | @table @asis | |
7875 | @item @var{target} | |
f37e7e3d | 7876 | Specifies the target buffer object. The symbolic constant must be |
b002944d AW |
7877 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
7878 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7879 | ||
7880 | @item @var{pname} | |
f37e7e3d | 7881 | Specifies the pointer to be returned. The symbolic constant must be |
b002944d AW |
7882 | @code{GL_BUFFER_MAP_POINTER}. |
7883 | ||
7884 | @item @var{params} | |
7885 | Returns the pointer value specified by @var{pname}. | |
7886 | ||
7887 | @end table | |
7888 | ||
f37e7e3d DH |
7889 | @code{glGetBufferPointerv} returns pointer information. @var{pname} is a |
7890 | symbolic constant indicating the pointer to be returned, which must be | |
b002944d | 7891 | @code{GL_BUFFER_MAP_POINTER}, the pointer to which the buffer object's |
f37e7e3d DH |
7892 | data store is mapped. If the data store is not currently mapped, |
7893 | @code{NULL} is returned. @var{params} is a pointer to a location in | |
b002944d AW |
7894 | which to place the returned pointer value. |
7895 | ||
7896 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
7897 | not an accepted value. | |
7898 | ||
7899 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
7900 | name 0 is bound to @var{target}. | |
7901 | ||
7902 | @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferPointerv} | |
7903 | is executed between the execution of @code{glBegin} and the | |
7904 | corresponding execution of @code{glEnd}. | |
7905 | ||
7906 | @end deftypefun | |
7907 | ||
bb894c9d | 7908 | @deftypefun void glGetBufferSubData target offset size data |
3c9b6116 AW |
7909 | Returns a subset of a buffer object's data store. |
7910 | ||
8925f36f AW |
7911 | @table @asis |
7912 | @item @var{target} | |
f37e7e3d | 7913 | Specifies the target buffer object. The symbolic constant must be |
8925f36f AW |
7914 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
7915 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7916 | ||
7917 | @item @var{offset} | |
7918 | Specifies the offset into the buffer object's data store from which data | |
7919 | will be returned, measured in bytes. | |
7920 | ||
7921 | @item @var{size} | |
7922 | Specifies the size in bytes of the data store region being returned. | |
7923 | ||
7924 | @item @var{data} | |
7925 | Specifies a pointer to the location where buffer object data is | |
7926 | returned. | |
7927 | ||
7928 | @end table | |
7929 | ||
8925f36f | 7930 | @code{glGetBufferSubData} returns some or all of the data from the |
f37e7e3d | 7931 | buffer object currently bound to @var{target}. Data starting at byte |
8925f36f | 7932 | offset @var{offset} and extending for @var{size} bytes is copied from |
f37e7e3d | 7933 | the data store to the memory pointed to by @var{data}. An error is |
8925f36f AW |
7934 | thrown if the buffer object is currently mapped, or if @var{offset} and |
7935 | @var{size} together define a range beyond the bounds of the buffer | |
7936 | object's data store. | |
7937 | ||
8925f36f AW |
7938 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
7939 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
7940 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7941 | ||
7942 | @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is | |
7943 | negative, or if together they define a region of memory that extends | |
7944 | beyond the buffer object's allocated data store. | |
7945 | ||
7946 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
7947 | name 0 is bound to @var{target}. | |
7948 | ||
7949 | @code{GL_INVALID_OPERATION} is generated if the buffer object being | |
7950 | queried is mapped. | |
7951 | ||
7952 | @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferSubData} is | |
7953 | executed between the execution of @code{glBegin} and the corresponding | |
7954 | execution of @code{glEnd}. | |
7955 | ||
bb894c9d | 7956 | @end deftypefun |
8925f36f | 7957 | |
bb894c9d | 7958 | @deftypefun void glGetClipPlane plane equation |
3c9b6116 AW |
7959 | Return the coefficients of the specified clipping plane. |
7960 | ||
8925f36f AW |
7961 | @table @asis |
7962 | @item @var{plane} | |
f37e7e3d DH |
7963 | Specifies a clipping plane. The number of clipping planes depends on the |
7964 | implementation, but at least six clipping planes are supported. They are | |
7965 | identified by symbolic names of the form @code{GL_CLIP_PLANE}@r{@var{i}} | |
7966 | where i ranges from 0 to the value of @code{GL_MAX_CLIP_PLANES} - 1. | |
8925f36f AW |
7967 | |
7968 | @item @var{equation} | |
7969 | Returns four double-precision values that are the coefficients of the | |
f37e7e3d | 7970 | plane equation of @var{plane} in eye coordinates. The initial value is |
8925f36f AW |
7971 | (0, 0, 0, 0). |
7972 | ||
7973 | @end table | |
7974 | ||
8925f36f AW |
7975 | @code{glGetClipPlane} returns in @var{equation} the four coefficients of |
7976 | the plane equation for @var{plane}. | |
7977 | ||
8925f36f AW |
7978 | @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted |
7979 | value. | |
7980 | ||
7981 | @code{GL_INVALID_OPERATION} is generated if @code{glGetClipPlane} is | |
7982 | executed between the execution of @code{glBegin} and the corresponding | |
7983 | execution of @code{glEnd}. | |
7984 | ||
bb894c9d | 7985 | @end deftypefun |
8925f36f | 7986 | |
b002944d AW |
7987 | @deftypefun void glGetColorTableParameterfv target pname params |
7988 | @deftypefunx void glGetColorTableParameteriv target pname params | |
7989 | Get color lookup table parameters. | |
7990 | ||
7991 | @table @asis | |
7992 | @item @var{target} | |
f37e7e3d | 7993 | The target color table. Must be @code{GL_COLOR_TABLE}, |
b002944d AW |
7994 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, |
7995 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE}, | |
7996 | @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or | |
7997 | @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}. | |
7998 | ||
7999 | @item @var{pname} | |
f37e7e3d | 8000 | The symbolic name of a color lookup table parameter. Must be one of |
b002944d AW |
8001 | @code{GL_COLOR_TABLE_BIAS}, @code{GL_COLOR_TABLE_SCALE}, |
8002 | @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH}, | |
8003 | @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE}, | |
8004 | @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE}, | |
8005 | @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, or | |
8006 | @code{GL_COLOR_TABLE_INTENSITY_SIZE}. | |
8007 | ||
8008 | @item @var{params} | |
8009 | A pointer to an array where the values of the parameter will be stored. | |
8010 | ||
8011 | @end table | |
8012 | ||
8013 | Returns parameters specific to color table @var{target}. | |
8014 | ||
8015 | When @var{pname} is set to @code{GL_COLOR_TABLE_SCALE} or | |
8016 | @code{GL_COLOR_TABLE_BIAS}, @code{glGetColorTableParameter} returns the | |
8017 | color table scale or bias parameters for the table specified by | |
f37e7e3d | 8018 | @var{target}. For these queries, @var{target} must be set to |
b002944d AW |
8019 | @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or |
8020 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} and @var{params} points to an | |
8021 | array of four elements, which receive the scale or bias factors for red, | |
8022 | green, blue, and alpha, in that order. | |
8023 | ||
8024 | @code{glGetColorTableParameter} can also be used to retrieve the format | |
f37e7e3d | 8025 | and size parameters for a color table. For these queries, set |
b002944d | 8026 | @var{target} to either the color table target or the proxy color table |
f37e7e3d | 8027 | target. The format and size parameters are set by @code{glColorTable}. |
b002944d AW |
8028 | |
8029 | The following table lists the format and size parameters that may be | |
f37e7e3d | 8030 | queried. For each symbolic constant listed below for @var{pname}, |
b002944d AW |
8031 | @var{params} must point to an array of the given length and receive the |
8032 | values indicated. | |
8033 | ||
8034 | ||
8035 | ||
8036 | @table @asis | |
8037 | @item @strong{Parameter} | |
8038 | @strong{N}, @strong{Meaning} | |
8039 | ||
8040 | @item @code{GL_COLOR_TABLE_FORMAT} | |
8041 | 1 , Internal format (e.g., @code{GL_RGBA}) | |
8042 | ||
8043 | @item @code{GL_COLOR_TABLE_WIDTH} | |
8044 | 1 , Number of elements in table | |
8045 | ||
8046 | @item @code{GL_COLOR_TABLE_RED_SIZE} | |
8047 | 1 , Size of red component, in bits | |
8048 | ||
8049 | @item @code{GL_COLOR_TABLE_GREEN_SIZE} | |
8050 | 1 , Size of green component | |
8051 | ||
8052 | @item @code{GL_COLOR_TABLE_BLUE_SIZE} | |
8053 | 1 , Size of blue component | |
8054 | ||
8055 | @item @code{GL_COLOR_TABLE_ALPHA_SIZE} | |
8056 | 1 , Size of alpha component | |
8057 | ||
8058 | @item @code{GL_COLOR_TABLE_LUMINANCE_SIZE} | |
8059 | 1 , Size of luminance component | |
8060 | ||
8061 | @item @code{GL_COLOR_TABLE_INTENSITY_SIZE} | |
8062 | 1 , Size of intensity component | |
8063 | ||
8064 | @end table | |
8065 | ||
8066 | ||
8067 | ||
8068 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
8069 | not an acceptable value. | |
8070 | ||
8071 | @code{GL_INVALID_OPERATION} is generated if | |
8072 | @code{glGetColorTableParameter} is executed between the execution of | |
8073 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8074 | ||
8075 | @end deftypefun | |
8076 | ||
bb894c9d | 8077 | @deftypefun void glGetColorTable target format type table |
3c9b6116 AW |
8078 | Retrieve contents of a color lookup table. |
8079 | ||
8925f36f AW |
8080 | @table @asis |
8081 | @item @var{target} | |
8082 | Must be @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE}, | |
8083 | or @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
8084 | ||
8085 | @item @var{format} | |
f37e7e3d | 8086 | The format of the pixel data in @var{table}. The possible values are |
8925f36f AW |
8087 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
8088 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, | |
8089 | @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}. | |
8090 | ||
8091 | @item @var{type} | |
f37e7e3d | 8092 | The type of the pixel data in @var{table}. Symbolic constants |
8925f36f AW |
8093 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
8094 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8095 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8096 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8097 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8098 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8099 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8100 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8101 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8102 | ||
8103 | @item @var{table} | |
8104 | Pointer to a one-dimensional array of pixel data containing the contents | |
8105 | of the color table. | |
8106 | ||
8107 | @end table | |
8108 | ||
8925f36f | 8109 | @code{glGetColorTable} returns in @var{table} the contents of the color |
f37e7e3d | 8110 | table specified by @var{target}. No pixel transfer operations are |
8925f36f AW |
8111 | performed, but pixel storage modes that are applicable to |
8112 | @code{glReadPixels} are performed. | |
8113 | ||
8114 | If a non-zero named buffer object is bound to the | |
8115 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8116 | histogram table is requested, @var{table} is treated as a byte offset | |
8117 | into the buffer object's data store. | |
8118 | ||
8119 | Color components that are requested in the specified @var{format}, but | |
8120 | which are not included in the internal format of the color lookup table, | |
f37e7e3d | 8121 | are returned as zero. The assignments of internal color components to |
8925f36f AW |
8122 | the components requested by @var{format} are |
8123 | ||
8124 | @table @asis | |
8125 | @item @strong{Internal Component} | |
8126 | @strong{Resulting Component} | |
8127 | ||
8128 | @item | |
8129 | Red | |
8130 | Red | |
8131 | ||
8132 | @item | |
8133 | Green | |
8134 | Green | |
8135 | ||
8136 | @item | |
8137 | Blue | |
8138 | Blue | |
8139 | ||
8140 | @item | |
8141 | Alpha | |
8142 | Alpha | |
8143 | ||
8144 | @item | |
8145 | Luminance | |
8146 | Red | |
8147 | ||
8148 | @item | |
8149 | Intensity | |
8150 | Red | |
8151 | ||
8152 | @end table | |
8153 | ||
8154 | ||
8155 | ||
8925f36f AW |
8156 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
8157 | allowable values. | |
8158 | ||
8159 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8160 | allowable values. | |
8161 | ||
8162 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
8163 | allowable values. | |
8164 | ||
8165 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8166 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8167 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8168 | and @var{format} is not @code{GL_RGB}. | |
8169 | ||
8170 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8171 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8172 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8173 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8174 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8175 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8176 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8177 | ||
8178 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8179 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8180 | object's data store is currently mapped. | |
8181 | ||
8182 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8183 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8184 | would be packed to the buffer object such that the memory writes | |
8185 | required would exceed the data store size. | |
8186 | ||
8187 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8188 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{table} | |
8189 | is not evenly divisible into the number of bytes needed to store in | |
8190 | memory a datum indicated by @var{type}. | |
8191 | ||
8192 | @code{GL_INVALID_OPERATION} is generated if @code{glGetColorTable} is | |
8193 | executed between the execution of @code{glBegin} and the corresponding | |
8194 | execution of @code{glEnd}. | |
8195 | ||
bb894c9d | 8196 | @end deftypefun |
8925f36f | 8197 | |
bb894c9d | 8198 | @deftypefun void glGetCompressedTexImage target lod img |
3c9b6116 AW |
8199 | Return a compressed texture image. |
8200 | ||
8925f36f AW |
8201 | @table @asis |
8202 | @item @var{target} | |
f37e7e3d | 8203 | Specifies which texture is to be obtained. @code{GL_TEXTURE_1D}, |
8925f36f AW |
8204 | @code{GL_TEXTURE_2D}, and |
8205 | @code{GL_TEXTURE_3D}@code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
8206 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
8207 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
8208 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
8209 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and | |
8210 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted. | |
8211 | ||
8212 | @item @var{lod} | |
f37e7e3d DH |
8213 | Specifies the level-of-detail number of the desired image. Level 0 is |
8214 | the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap | |
3c9b6116 | 8215 | reduction image. |
8925f36f AW |
8216 | |
8217 | @item @var{img} | |
8218 | Returns the compressed texture image. | |
8219 | ||
8220 | @end table | |
8221 | ||
8925f36f | 8222 | @code{glGetCompressedTexImage} returns the compressed texture image |
f37e7e3d | 8223 | associated with @var{target} and @var{lod} into @var{img}. @var{img} |
8925f36f AW |
8224 | should be an array of @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} bytes. |
8225 | @var{target} specifies whether the desired texture image was one | |
8226 | specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}), | |
8227 | @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of | |
8228 | @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D} | |
f37e7e3d | 8229 | (@code{GL_TEXTURE_3D}). @var{lod} specifies the level-of-detail number |
8925f36f AW |
8230 | of the desired image. |
8231 | ||
8232 | If a non-zero named buffer object is bound to the | |
8233 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8234 | texture image is requested, @var{img} is treated as a byte offset into | |
8235 | the buffer object's data store. | |
8236 | ||
8237 | To minimize errors, first verify that the texture is compressed by | |
8238 | calling @code{glGetTexLevelParameter} with argument | |
f37e7e3d | 8239 | @code{GL_TEXTURE_COMPRESSED}. If the texture is compressed, then |
8925f36f AW |
8240 | determine the amount of memory required to store the compressed texture |
8241 | by calling @code{glGetTexLevelParameter} with argument | |
f37e7e3d | 8242 | @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE}. Finally, retrieve the internal |
8925f36f | 8243 | format of the texture by calling @code{glGetTexLevelParameter} with |
f37e7e3d | 8244 | argument @code{GL_TEXTURE_INTERNAL_FORMAT}. To store the texture for |
8925f36f | 8245 | later use, associate the internal format and size with the retrieved |
f37e7e3d | 8246 | texture image. These data can be used by the respective texture or |
8925f36f AW |
8247 | subtexture loading routine used for loading @var{target} textures. |
8248 | ||
8925f36f AW |
8249 | @code{GL_INVALID_VALUE} is generated if @var{lod} is less than zero or |
8250 | greater than the maximum number of LODs permitted by the implementation. | |
8251 | ||
8252 | @code{GL_INVALID_OPERATION} is generated if | |
8253 | @code{glGetCompressedTexImage} is used to retrieve a texture that is in | |
8254 | an uncompressed internal format. | |
8255 | ||
8256 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8257 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8258 | object's data store is currently mapped. | |
8259 | ||
8260 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8261 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8262 | would be packed to the buffer object such that the memory writes | |
8263 | required would exceed the data store size. | |
8264 | ||
8265 | @code{GL_INVALID_OPERATION} is generated if | |
8266 | @code{glGetCompressedTexImage} is executed between the execution of | |
8267 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8268 | ||
bb894c9d | 8269 | @end deftypefun |
8925f36f | 8270 | |
bb894c9d | 8271 | @deftypefun void glGetConvolutionFilter target format type image |
3c9b6116 AW |
8272 | Get current 1D or 2D convolution filter kernel. |
8273 | ||
8925f36f AW |
8274 | @table @asis |
8275 | @item @var{target} | |
f37e7e3d | 8276 | The filter to be retrieved. Must be one of @code{GL_CONVOLUTION_1D} or |
8925f36f AW |
8277 | @code{GL_CONVOLUTION_2D}. |
8278 | ||
8279 | @item @var{format} | |
f37e7e3d | 8280 | Format of the output image. Must be one of @code{GL_RED}, |
8925f36f AW |
8281 | @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, |
8282 | @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or | |
8283 | @code{GL_LUMINANCE_ALPHA}. | |
8284 | ||
8285 | @item @var{type} | |
f37e7e3d | 8286 | Data type of components in the output image. Symbolic constants |
8925f36f AW |
8287 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
8288 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8289 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8290 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8291 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8292 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8293 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8294 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8295 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8296 | ||
8297 | @item @var{image} | |
8298 | Pointer to storage for the output image. | |
8299 | ||
8300 | @end table | |
8301 | ||
8925f36f | 8302 | @code{glGetConvolutionFilter} returns the current 1D or 2D convolution |
f37e7e3d | 8303 | filter kernel as an image. The one- or two-dimensional image is placed |
8925f36f | 8304 | in @var{image} according to the specifications in @var{format} and |
f37e7e3d | 8305 | @var{type}. No pixel transfer operations are performed on this image, |
8925f36f AW |
8306 | but the relevant pixel storage modes are applied. |
8307 | ||
8308 | If a non-zero named buffer object is bound to the | |
8309 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8310 | convolution filter is requested, @var{image} is treated as a byte offset | |
8311 | into the buffer object's data store. | |
8312 | ||
8313 | Color components that are present in @var{format} but not included in | |
f37e7e3d | 8314 | the internal format of the filter are returned as zero. The assignments |
8925f36f AW |
8315 | of internal color components to the components of @var{format} are as |
8316 | follows. | |
8317 | ||
8318 | @table @asis | |
8319 | @item @strong{Internal Component} | |
8320 | @strong{Resulting Component} | |
8321 | ||
8322 | @item | |
8323 | Red | |
8324 | Red | |
8325 | ||
8326 | @item | |
8327 | Green | |
8328 | Green | |
8329 | ||
8330 | @item | |
8331 | Blue | |
8332 | Blue | |
8333 | ||
8334 | @item | |
8335 | Alpha | |
8336 | Alpha | |
8337 | ||
8338 | @item | |
8339 | Luminance | |
8340 | Red | |
8341 | ||
8342 | @item | |
8343 | Intensity | |
8344 | Red | |
8345 | ||
8346 | @end table | |
8347 | ||
8348 | ||
8349 | ||
8925f36f AW |
8350 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
8351 | allowable values. | |
8352 | ||
8353 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8354 | allowable values. | |
8355 | ||
8356 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
8357 | allowable values. | |
8358 | ||
8359 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8360 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8361 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8362 | and @var{format} is not @code{GL_RGB}. | |
8363 | ||
8364 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8365 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8366 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8367 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8368 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8369 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8370 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8371 | ||
8372 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8373 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8374 | object's data store is currently mapped. | |
8375 | ||
8376 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8377 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8378 | would be packed to the buffer object such that the memory writes | |
8379 | required would exceed the data store size. | |
8380 | ||
8381 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8382 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{image} | |
8383 | is not evenly divisible into the number of bytes needed to store in | |
8384 | memory a datum indicated by @var{type}. | |
8385 | ||
8386 | @code{GL_INVALID_OPERATION} is generated if | |
8387 | @code{glGetConvolutionFilter} is executed between the execution of | |
8388 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8389 | ||
bb894c9d | 8390 | @end deftypefun |
8925f36f | 8391 | |
b002944d AW |
8392 | @deftypefun void glGetConvolutionParameterfv target pname params |
8393 | @deftypefunx void glGetConvolutionParameteriv target pname params | |
8394 | Get convolution parameters. | |
8395 | ||
8396 | @table @asis | |
8397 | @item @var{target} | |
f37e7e3d | 8398 | The filter whose parameters are to be retrieved. Must be one of |
b002944d AW |
8399 | @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or |
8400 | @code{GL_SEPARABLE_2D}. | |
8401 | ||
8402 | @item @var{pname} | |
f37e7e3d | 8403 | The parameter to be retrieved. Must be one of |
b002944d AW |
8404 | @code{GL_CONVOLUTION_BORDER_MODE}, @code{GL_CONVOLUTION_BORDER_COLOR}, |
8405 | @code{GL_CONVOLUTION_FILTER_SCALE}, @code{GL_CONVOLUTION_FILTER_BIAS}, | |
8406 | @code{GL_CONVOLUTION_FORMAT}, @code{GL_CONVOLUTION_WIDTH}, | |
8407 | @code{GL_CONVOLUTION_HEIGHT}, @code{GL_MAX_CONVOLUTION_WIDTH}, or | |
8408 | @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
8409 | ||
8410 | @item @var{params} | |
8411 | Pointer to storage for the parameters to be retrieved. | |
8412 | ||
8413 | @end table | |
8414 | ||
8415 | @code{glGetConvolutionParameter} retrieves convolution parameters. | |
f37e7e3d | 8416 | @var{target} determines which convolution filter is queried. @var{pname} |
b002944d AW |
8417 | determines which parameter is returned: |
8418 | ||
8419 | @table @asis | |
8420 | @item @code{GL_CONVOLUTION_BORDER_MODE} | |
8421 | ||
8422 | ||
f37e7e3d | 8423 | The convolution border mode. See @code{glConvolutionParameter} for a |
b002944d AW |
8424 | list of border modes. |
8425 | ||
8426 | @item @code{GL_CONVOLUTION_BORDER_COLOR} | |
8427 | ||
8428 | ||
f37e7e3d | 8429 | The current convolution border color. @var{params} must be a pointer to |
b002944d AW |
8430 | an array of four elements, which will receive the red, green, blue, and |
8431 | alpha border colors. | |
8432 | ||
8433 | @item @code{GL_CONVOLUTION_FILTER_SCALE} | |
8434 | ||
8435 | ||
f37e7e3d | 8436 | The current filter scale factors. @var{params} must be a pointer to an |
b002944d AW |
8437 | array of four elements, which will receive the red, green, blue, and |
8438 | alpha filter scale factors in that order. | |
8439 | ||
8440 | @item @code{GL_CONVOLUTION_FILTER_BIAS} | |
8441 | ||
8442 | ||
f37e7e3d | 8443 | The current filter bias factors. @var{params} must be a pointer to an |
b002944d AW |
8444 | array of four elements, which will receive the red, green, blue, and |
8445 | alpha filter bias terms in that order. | |
8446 | ||
8447 | @item @code{GL_CONVOLUTION_FORMAT} | |
8448 | ||
8449 | ||
f37e7e3d | 8450 | The current internal format. See @code{glConvolutionFilter1D}, |
b002944d AW |
8451 | @code{glConvolutionFilter2D}, and @code{glSeparableFilter2D} for lists |
8452 | of allowable formats. | |
8453 | ||
8454 | @item @code{GL_CONVOLUTION_WIDTH} | |
8455 | ||
8456 | ||
8457 | The current filter image width. | |
8458 | ||
8459 | @item @code{GL_CONVOLUTION_HEIGHT} | |
8460 | ||
8461 | ||
8462 | The current filter image height. | |
8463 | ||
8464 | @item @code{GL_MAX_CONVOLUTION_WIDTH} | |
8465 | ||
8466 | ||
8467 | The maximum acceptable filter image width. | |
8468 | ||
8469 | @item @code{GL_MAX_CONVOLUTION_HEIGHT} | |
8470 | ||
8471 | ||
8472 | The maximum acceptable filter image height. | |
8473 | ||
8474 | @end table | |
8475 | ||
8476 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the | |
8477 | allowable values. | |
8478 | ||
8479 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
8480 | allowable values. | |
8481 | ||
8482 | @code{GL_INVALID_ENUM} is generated if @var{target} is | |
8483 | @code{GL_CONVOLUTION_1D} and @var{pname} is @code{GL_CONVOLUTION_HEIGHT} | |
8484 | or @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
8485 | ||
8486 | @code{GL_INVALID_OPERATION} is generated if | |
8487 | @code{glGetConvolutionParameter} is executed between the execution of | |
8488 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8489 | ||
8490 | @end deftypefun | |
8491 | ||
bb894c9d | 8492 | @deftypefun GLenum glGetError |
3c9b6116 AW |
8493 | Return error information. |
8494 | ||
f37e7e3d DH |
8495 | @code{glGetError} returns the value of the error flag. Each detectable |
8496 | error is assigned a numeric code and symbolic name. When an error | |
8497 | occurs, the error flag is set to the appropriate error code value. No | |
8925f36f | 8498 | other errors are recorded until @code{glGetError} is called, the error |
f37e7e3d DH |
8499 | code is returned, and the flag is reset to @code{GL_NO_ERROR}. If a call |
8500 | to @code{glGetError} returns @code{GL_NO_ERROR}, there has been no | |
8925f36f AW |
8501 | detectable error since the last call to @code{glGetError}, or since the |
8502 | GL was initialized. | |
8503 | ||
8504 | To allow for distributed implementations, there may be several error | |
f37e7e3d DH |
8505 | flags. If any single error flag has recorded an error, the value of that |
8506 | flag is returned and that flag is reset to @code{GL_NO_ERROR} when | |
8507 | @code{glGetError} is called. If more than one flag has recorded an | |
8925f36f | 8508 | error, @code{glGetError} returns and clears an arbitrary error flag |
f37e7e3d | 8509 | value. Thus, @code{glGetError} should always be called in a loop, until |
8925f36f AW |
8510 | it returns @code{GL_NO_ERROR}, if all error flags are to be reset. |
8511 | ||
8512 | Initially, all error flags are set to @code{GL_NO_ERROR}. | |
8513 | ||
8514 | The following errors are currently defined: | |
8515 | ||
8516 | @table @asis | |
8517 | @item @code{GL_NO_ERROR} | |
f37e7e3d | 8518 | No error has been recorded. The value of this symbolic constant is |
8925f36f AW |
8519 | guaranteed to be 0. |
8520 | ||
8521 | @item @code{GL_INVALID_ENUM} | |
f37e7e3d | 8522 | An unacceptable value is specified for an enumerated argument. The |
8925f36f AW |
8523 | offending command is ignored and has no other side effect than to set |
8524 | the error flag. | |
8525 | ||
8526 | @item @code{GL_INVALID_VALUE} | |
f37e7e3d DH |
8527 | A numeric argument is out of range. The offending command is ignored and |
8528 | has no other side effect than to set the error flag. | |
8925f36f AW |
8529 | |
8530 | @item @code{GL_INVALID_OPERATION} | |
f37e7e3d | 8531 | The specified operation is not allowed in the current state. The |
8925f36f AW |
8532 | offending command is ignored and has no other side effect than to set |
8533 | the error flag. | |
8534 | ||
8535 | @item @code{GL_STACK_OVERFLOW} | |
f37e7e3d | 8536 | This command would cause a stack overflow. The offending command is |
8925f36f AW |
8537 | ignored and has no other side effect than to set the error flag. |
8538 | ||
8539 | @item @code{GL_STACK_UNDERFLOW} | |
f37e7e3d | 8540 | This command would cause a stack underflow. The offending command is |
8925f36f AW |
8541 | ignored and has no other side effect than to set the error flag. |
8542 | ||
8543 | @item @code{GL_OUT_OF_MEMORY} | |
f37e7e3d DH |
8544 | There is not enough memory left to execute the command. The state of the |
8545 | GL is undefined, except for the state of the error flags, after this | |
8925f36f AW |
8546 | error is recorded. |
8547 | ||
8548 | @item @code{GL_TABLE_TOO_LARGE} | |
8549 | The specified table exceeds the implementation's maximum supported table | |
f37e7e3d DH |
8550 | size. The offending command is ignored and has no other side effect than |
8551 | to set the error flag. | |
8925f36f AW |
8552 | |
8553 | @end table | |
8554 | ||
8555 | When an error flag is set, results of a GL operation are undefined only | |
f37e7e3d DH |
8556 | if @code{GL_OUT_OF_MEMORY} has occurred. In all other cases, the command |
8557 | generating the error is ignored and has no effect on the GL state or | |
8558 | frame buffer contents. If the generating command returns a value, it | |
8559 | returns 0. If @code{glGetError} itself generates an error, it returns 0. | |
8925f36f | 8560 | |
8925f36f AW |
8561 | @code{GL_INVALID_OPERATION} is generated if @code{glGetError} is |
8562 | executed between the execution of @code{glBegin} and the corresponding | |
f37e7e3d | 8563 | execution of @code{glEnd}. In this case, @code{glGetError} returns 0. |
8925f36f | 8564 | |
bb894c9d | 8565 | @end deftypefun |
8925f36f | 8566 | |
b002944d AW |
8567 | @deftypefun void glGetHistogramParameterfv target pname params |
8568 | @deftypefunx void glGetHistogramParameteriv target pname params | |
8569 | Get histogram parameters. | |
8570 | ||
8571 | @table @asis | |
8572 | @item @var{target} | |
8573 | Must be one of @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}. | |
8574 | ||
8575 | @item @var{pname} | |
f37e7e3d | 8576 | The name of the parameter to be retrieved. Must be one of |
b002944d AW |
8577 | @code{GL_HISTOGRAM_WIDTH}, @code{GL_HISTOGRAM_FORMAT}, |
8578 | @code{GL_HISTOGRAM_RED_SIZE}, @code{GL_HISTOGRAM_GREEN_SIZE}, | |
8579 | @code{GL_HISTOGRAM_BLUE_SIZE}, @code{GL_HISTOGRAM_ALPHA_SIZE}, | |
8580 | @code{GL_HISTOGRAM_LUMINANCE_SIZE}, or @code{GL_HISTOGRAM_SINK}. | |
8581 | ||
8582 | @item @var{params} | |
8583 | Pointer to storage for the returned values. | |
8584 | ||
8585 | @end table | |
8586 | ||
8587 | @code{glGetHistogramParameter} is used to query parameter values for the | |
f37e7e3d DH |
8588 | current histogram or for a proxy. The histogram state information may be |
8589 | queried by calling @code{glGetHistogramParameter} with a @var{target} of | |
8590 | @code{GL_HISTOGRAM} (to obtain information for the current histogram | |
b002944d AW |
8591 | table) or @code{GL_PROXY_HISTOGRAM} (to obtain information from the most |
8592 | recent proxy request) and one of the following values for the | |
8593 | @var{pname} argument: | |
8594 | ||
8595 | ||
8596 | ||
8597 | @table @asis | |
8598 | @item @strong{Parameter} | |
8599 | @strong{Description} | |
8600 | ||
8601 | @item @code{GL_HISTOGRAM_WIDTH} | |
8602 | Histogram table width | |
8603 | ||
8604 | @item @code{GL_HISTOGRAM_FORMAT} | |
8605 | Internal format | |
8606 | ||
8607 | @item @code{GL_HISTOGRAM_RED_SIZE} | |
8608 | Red component counter size, in bits | |
8609 | ||
8610 | @item @code{GL_HISTOGRAM_GREEN_SIZE} | |
8611 | Green component counter size, in bits | |
8612 | ||
8613 | @item @code{GL_HISTOGRAM_BLUE_SIZE} | |
8614 | Blue component counter size, in bits | |
8615 | ||
8616 | @item @code{GL_HISTOGRAM_ALPHA_SIZE} | |
8617 | Alpha component counter size, in bits | |
8618 | ||
8619 | @item @code{GL_HISTOGRAM_LUMINANCE_SIZE} | |
8620 | Luminance component counter size, in bits | |
8621 | ||
8622 | @item @code{GL_HISTOGRAM_SINK} | |
8623 | Value of the @var{sink} parameter | |
8624 | ||
8625 | @end table | |
8626 | ||
8627 | ||
8628 | ||
8629 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the | |
8630 | allowable values. | |
8631 | ||
8632 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
8633 | allowable values. | |
8634 | ||
8635 | @code{GL_INVALID_OPERATION} is generated if | |
8636 | @code{glGetHistogramParameter} is executed between the execution of | |
8637 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8638 | ||
8639 | @end deftypefun | |
8640 | ||
bb894c9d | 8641 | @deftypefun void glGetHistogram target reset format type values |
3c9b6116 AW |
8642 | Get histogram table. |
8643 | ||
8925f36f AW |
8644 | @table @asis |
8645 | @item @var{target} | |
8646 | Must be @code{GL_HISTOGRAM}. | |
8647 | ||
8648 | @item @var{reset} | |
8649 | If @code{GL_TRUE}, each component counter that is actually returned is | |
f37e7e3d DH |
8650 | reset to zero. (Other counters are unaffected.) If @code{GL_FALSE}, none |
8651 | of the counters in the histogram table is modified. | |
8925f36f AW |
8652 | |
8653 | @item @var{format} | |
f37e7e3d | 8654 | The format of values to be returned in @var{values}. Must be one of |
8925f36f AW |
8655 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
8656 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
8657 | @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}. | |
8658 | ||
8659 | @item @var{type} | |
f37e7e3d | 8660 | The type of values to be returned in @var{values}. Symbolic constants |
8925f36f AW |
8661 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
8662 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8663 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8664 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8665 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8666 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8667 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8668 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8669 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8670 | ||
8671 | @item @var{values} | |
8672 | A pointer to storage for the returned histogram table. | |
8673 | ||
8674 | @end table | |
8675 | ||
8925f36f | 8676 | @code{glGetHistogram} returns the current histogram table as a |
f37e7e3d | 8677 | one-dimensional image with the same width as the histogram. No pixel |
8925f36f AW |
8678 | transfer operations are performed on this image, but pixel storage modes |
8679 | that are applicable to 1D images are honored. | |
8680 | ||
8681 | If a non-zero named buffer object is bound to the | |
8682 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8683 | histogram table is requested, @var{values} is treated as a byte offset | |
8684 | into the buffer object's data store. | |
8685 | ||
8686 | Color components that are requested in the specified @var{format}, but | |
8687 | which are not included in the internal format of the histogram, are | |
f37e7e3d | 8688 | returned as zero. The assignments of internal color components to the |
8925f36f AW |
8689 | components requested by @var{format} are: |
8690 | ||
8691 | @table @asis | |
8692 | @item @strong{Internal Component} | |
8693 | @strong{Resulting Component} | |
8694 | ||
8695 | @item | |
8696 | Red | |
8697 | Red | |
8698 | ||
8699 | @item | |
8700 | Green | |
8701 | Green | |
8702 | ||
8703 | @item | |
8704 | Blue | |
8705 | Blue | |
8706 | ||
8707 | @item | |
8708 | Alpha | |
8709 | Alpha | |
8710 | ||
8711 | @item | |
8712 | Luminance | |
8713 | Red | |
8714 | ||
8715 | @end table | |
8716 | ||
8717 | ||
8718 | ||
8925f36f AW |
8719 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
8720 | @code{GL_HISTOGRAM}. | |
8721 | ||
8722 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8723 | allowable values. | |
8724 | ||
8725 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
8726 | allowable values. | |
8727 | ||
8728 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8729 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8730 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8731 | and @var{format} is not @code{GL_RGB}. | |
8732 | ||
8733 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8734 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8735 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8736 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8737 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8738 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8739 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8740 | ||
8741 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8742 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8743 | object's data store is currently mapped. | |
8744 | ||
8745 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8746 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8747 | would be packed to the buffer object such that the memory writes | |
8748 | required would exceed the data store size. | |
8749 | ||
8750 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8751 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values} | |
8752 | is not evenly divisible into the number of bytes needed to store in | |
8753 | memory a datum indicated by @var{type}. | |
8754 | ||
8755 | @code{GL_INVALID_OPERATION} is generated if @code{glGetHistogram} is | |
8756 | executed between the execution of @code{glBegin} and the corresponding | |
8757 | execution of @code{glEnd}. | |
8758 | ||
bb894c9d | 8759 | @end deftypefun |
8925f36f | 8760 | |
b002944d AW |
8761 | @deftypefun void glGetLightfv light pname params |
8762 | @deftypefunx void glGetLightiv light pname params | |
8763 | Return light source parameter values. | |
3c9b6116 | 8764 | |
8925f36f | 8765 | @table @asis |
b002944d | 8766 | @item @var{light} |
f37e7e3d DH |
8767 | Specifies a light source. The number of possible lights depends on the |
8768 | implementation, but at least eight lights are supported. They are | |
b002944d AW |
8769 | identified by symbolic names of the form @code{GL_LIGHT}@r{@var{i}} |
8770 | where @r{@var{i}} ranges from 0 to the value of @code{GL_MAX_LIGHTS} - | |
8771 | 1. | |
8925f36f | 8772 | |
b002944d | 8773 | @item @var{pname} |
f37e7e3d | 8774 | Specifies a light source parameter for @var{light}. Accepted symbolic |
b002944d AW |
8775 | names are @code{GL_AMBIENT}, @code{GL_DIFFUSE}, @code{GL_SPECULAR}, |
8776 | @code{GL_POSITION}, @code{GL_SPOT_DIRECTION}, @code{GL_SPOT_EXPONENT}, | |
8777 | @code{GL_SPOT_CUTOFF}, @code{GL_CONSTANT_ATTENUATION}, | |
8778 | @code{GL_LINEAR_ATTENUATION}, and @code{GL_QUADRATIC_ATTENUATION}. | |
8925f36f | 8779 | |
b002944d AW |
8780 | @item @var{params} |
8781 | Returns the requested data. | |
8925f36f | 8782 | |
b002944d | 8783 | @end table |
8925f36f | 8784 | |
b002944d | 8785 | @code{glGetLight} returns in @var{params} the value or values of a light |
f37e7e3d | 8786 | source parameter. @var{light} names the light and is a symbolic name of |
b002944d | 8787 | the form @code{GL_LIGHT}@r{@var{i}} where i ranges from 0 to the value |
f37e7e3d DH |
8788 | of @code{GL_MAX_LIGHTS} - 1. @code{GL_MAX_LIGHTS} is an implementation |
8789 | dependent constant that is greater than or equal to eight. @var{pname} | |
b002944d | 8790 | specifies one of ten light source parameters, again by symbolic name. |
8925f36f | 8791 | |
b002944d | 8792 | The following parameters are defined: |
8925f36f | 8793 | |
b002944d AW |
8794 | @table @asis |
8795 | @item @code{GL_AMBIENT} | |
8796 | @var{params} returns four integer or floating-point values representing | |
f37e7e3d | 8797 | the ambient intensity of the light source. Integer values, when |
b002944d AW |
8798 | requested, are linearly mapped from the internal floating-point |
8799 | representation such that 1.0 maps to the most positive representable | |
8800 | integer value, and @r{-1.0} maps to the most negative representable | |
f37e7e3d DH |
8801 | integer value. If the internal value is outside the range @r{[-1,1]}, |
8802 | the corresponding integer return value is undefined. The initial value | |
b002944d AW |
8803 | is (0, 0, 0, 1). |
8804 | ||
8805 | @item @code{GL_DIFFUSE} | |
8806 | @var{params} returns four integer or floating-point values representing | |
f37e7e3d | 8807 | the diffuse intensity of the light source. Integer values, when |
b002944d AW |
8808 | requested, are linearly mapped from the internal floating-point |
8809 | representation such that 1.0 maps to the most positive representable | |
8810 | integer value, and @r{-1.0} maps to the most negative representable | |
f37e7e3d DH |
8811 | integer value. If the internal value is outside the range @r{[-1,1]}, |
8812 | the corresponding integer return value is undefined. The initial value | |
b002944d AW |
8813 | for @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial |
8814 | value is (0, 0, 0, 0). | |
8815 | ||
8816 | @item @code{GL_SPECULAR} | |
8817 | @var{params} returns four integer or floating-point values representing | |
f37e7e3d | 8818 | the specular intensity of the light source. Integer values, when |
b002944d AW |
8819 | requested, are linearly mapped from the internal floating-point |
8820 | representation such that 1.0 maps to the most positive representable | |
8821 | integer value, and @r{-1.0} maps to the most negative representable | |
f37e7e3d DH |
8822 | integer value. If the internal value is outside the range @r{[-1,1]}, |
8823 | the corresponding integer return value is undefined. The initial value | |
b002944d AW |
8824 | for @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial |
8825 | value is (0, 0, 0, 0). | |
8826 | ||
8827 | @item @code{GL_POSITION} | |
8828 | @var{params} returns four integer or floating-point values representing | |
f37e7e3d | 8829 | the position of the light source. Integer values, when requested, are |
b002944d | 8830 | computed by rounding the internal floating-point values to the nearest |
f37e7e3d DH |
8831 | integer value. The returned values are those maintained in eye |
8832 | coordinates. They will not be equal to the values specified using | |
b002944d | 8833 | @code{glLight}, unless the modelview matrix was identity at the time |
f37e7e3d | 8834 | @code{glLight} was called. The initial value is (0, 0, 1, 0). |
b002944d AW |
8835 | |
8836 | @item @code{GL_SPOT_DIRECTION} | |
8837 | @var{params} returns three integer or floating-point values representing | |
f37e7e3d | 8838 | the direction of the light source. Integer values, when requested, are |
b002944d | 8839 | computed by rounding the internal floating-point values to the nearest |
f37e7e3d DH |
8840 | integer value. The returned values are those maintained in eye |
8841 | coordinates. They will not be equal to the values specified using | |
b002944d | 8842 | @code{glLight}, unless the modelview matrix was identity at the time |
f37e7e3d | 8843 | @code{glLight} was called. Although spot direction is normalized before |
b002944d | 8844 | being used in the lighting equation, the returned values are the |
f37e7e3d | 8845 | transformed versions of the specified values prior to normalization. The |
b002944d AW |
8846 | initial value is @r{(0,0-1)}. |
8847 | ||
8848 | @item @code{GL_SPOT_EXPONENT} | |
8849 | @var{params} returns a single integer or floating-point value | |
f37e7e3d | 8850 | representing the spot exponent of the light. An integer value, when |
b002944d | 8851 | requested, is computed by rounding the internal floating-point |
f37e7e3d | 8852 | representation to the nearest integer. The initial value is 0. |
b002944d AW |
8853 | |
8854 | @item @code{GL_SPOT_CUTOFF} | |
8855 | @var{params} returns a single integer or floating-point value | |
f37e7e3d | 8856 | representing the spot cutoff angle of the light. An integer value, when |
b002944d | 8857 | requested, is computed by rounding the internal floating-point |
f37e7e3d | 8858 | representation to the nearest integer. The initial value is 180. |
b002944d AW |
8859 | |
8860 | @item @code{GL_CONSTANT_ATTENUATION} | |
8861 | @var{params} returns a single integer or floating-point value | |
8862 | representing the constant (not distance-related) attenuation of the | |
f37e7e3d DH |
8863 | light. An integer value, when requested, is computed by rounding the |
8864 | internal floating-point representation to the nearest integer. The | |
b002944d AW |
8865 | initial value is 1. |
8866 | ||
8867 | @item @code{GL_LINEAR_ATTENUATION} | |
8868 | @var{params} returns a single integer or floating-point value | |
f37e7e3d DH |
8869 | representing the linear attenuation of the light. An integer value, when |
8870 | requested, is computed by rounding the internal floating-point | |
8871 | representation to the nearest integer. The initial value is 0. | |
b002944d AW |
8872 | |
8873 | @item @code{GL_QUADRATIC_ATTENUATION} | |
8874 | @var{params} returns a single integer or floating-point value | |
f37e7e3d | 8875 | representing the quadratic attenuation of the light. An integer value, |
b002944d | 8876 | when requested, is computed by rounding the internal floating-point |
f37e7e3d | 8877 | representation to the nearest integer. The initial value is 0. |
b002944d AW |
8878 | |
8879 | @end table | |
8880 | ||
8881 | @code{GL_INVALID_ENUM} is generated if @var{light} or @var{pname} is not | |
8882 | an accepted value. | |
8883 | ||
8884 | @code{GL_INVALID_OPERATION} is generated if @code{glGetLight} is | |
8885 | executed between the execution of @code{glBegin} and the corresponding | |
8886 | execution of @code{glEnd}. | |
8887 | ||
8888 | @end deftypefun | |
8889 | ||
d172eed9 AW |
8890 | @deftypefun void glGetMapdv target query v |
8891 | @deftypefunx void glGetMapfv target query v | |
b002944d AW |
8892 | @deftypefunx void glGetMapiv target query v |
8893 | Return evaluator parameters. | |
8894 | ||
8895 | @table @asis | |
8896 | @item @var{target} | |
f37e7e3d | 8897 | Specifies the symbolic name of a map. Accepted values are |
b002944d AW |
8898 | @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_INDEX}, @code{GL_MAP1_NORMAL}, |
8899 | @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2}, | |
8900 | @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4}, | |
8901 | @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4}, | |
8902 | @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_INDEX}, @code{GL_MAP2_NORMAL}, | |
8903 | @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2}, | |
8904 | @code{GL_MAP2_TEXTURE_COORD_3}, @code{GL_MAP2_TEXTURE_COORD_4}, | |
8905 | @code{GL_MAP2_VERTEX_3}, and @code{GL_MAP2_VERTEX_4}. | |
8906 | ||
8907 | @item @var{query} | |
f37e7e3d | 8908 | Specifies which parameter to return. Symbolic names @code{GL_COEFF}, |
b002944d AW |
8909 | @code{GL_ORDER}, and @code{GL_DOMAIN} are accepted. |
8910 | ||
8911 | @item @var{v} | |
8912 | Returns the requested data. | |
8913 | ||
8914 | @end table | |
8915 | ||
f37e7e3d DH |
8916 | @code{glMap1} and @code{glMap2} define evaluators. @code{glGetMap} |
8917 | returns evaluator parameters. @var{target} chooses a map, @var{query} | |
b002944d AW |
8918 | selects a specific parameter, and @var{v} points to storage where the |
8919 | values will be returned. | |
8920 | ||
8921 | The acceptable values for the @var{target} parameter are described in | |
8922 | the @code{glMap1} and @code{glMap2} reference pages. | |
8923 | ||
8924 | @var{query} can assume the following values: | |
8925 | ||
8926 | @table @asis | |
8927 | @item @code{GL_COEFF} | |
8928 | @var{v} returns the control points for the evaluator function. | |
8929 | One-dimensional evaluators return @r{@var{order}} control points, and | |
8930 | two-dimensional evaluators return @r{@var{uorder}×@var{vorder}} control | |
f37e7e3d DH |
8931 | points. Each control point consists of one, two, three, or four integer, |
8932 | single-precision floating-point, or double-precision floating-point | |
8933 | values, depending on the type of the evaluator. The GL returns | |
8934 | two-dimensional control points in row-major order, incrementing the | |
8935 | @r{@var{uorder}} index quickly and the @r{@var{vorder}} index after each | |
8936 | row. Integer values, when requested, are computed by rounding the | |
b002944d AW |
8937 | internal floating-point values to the nearest integer values. |
8938 | ||
8939 | @item @code{GL_ORDER} | |
f37e7e3d DH |
8940 | @var{v} returns the order of the evaluator function. One-dimensional |
8941 | evaluators return a single value, @r{@var{order}}. The initial value is | |
8942 | 1. Two-dimensional evaluators return two values, @r{@var{uorder}} and | |
8943 | @r{@var{vorder}}. The initial value is 1,1. | |
b002944d AW |
8944 | |
8945 | @item @code{GL_DOMAIN} | |
8946 | @var{v} returns the linear @r{@var{u}} and @r{@var{v}} mapping | |
f37e7e3d DH |
8947 | parameters. One-dimensional evaluators return two values, @r{@var{u1}} |
8948 | and @r{@var{u2}}, as specified by @code{glMap1}. Two-dimensional | |
b002944d | 8949 | evaluators return four values (@r{@var{u1}}, @r{@var{u2}}, @r{@var{v1}}, |
f37e7e3d | 8950 | and @r{@var{v2}}) as specified by @code{glMap2}. Integer values, when |
b002944d AW |
8951 | requested, are computed by rounding the internal floating-point values |
8952 | to the nearest integer values. | |
8953 | ||
8954 | @end table | |
8955 | ||
8956 | @code{GL_INVALID_ENUM} is generated if either @var{target} or | |
8957 | @var{query} is not an accepted value. | |
8958 | ||
8959 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMap} is executed | |
8960 | between the execution of @code{glBegin} and the corresponding execution | |
8961 | of @code{glEnd}. | |
8962 | ||
8963 | @end deftypefun | |
8964 | ||
8965 | @deftypefun void glGetMaterialfv face pname params | |
8966 | @deftypefunx void glGetMaterialiv face pname params | |
8967 | Return material parameters. | |
8968 | ||
8969 | @table @asis | |
8970 | @item @var{face} | |
f37e7e3d | 8971 | Specifies which of the two materials is being queried. @code{GL_FRONT} |
b002944d AW |
8972 | or @code{GL_BACK} are accepted, representing the front and back |
8973 | materials, respectively. | |
8974 | ||
8975 | @item @var{pname} | |
f37e7e3d | 8976 | Specifies the material parameter to return. @code{GL_AMBIENT}, |
b002944d AW |
8977 | @code{GL_DIFFUSE}, @code{GL_SPECULAR}, @code{GL_EMISSION}, |
8978 | @code{GL_SHININESS}, and @code{GL_COLOR_INDEXES} are accepted. | |
8979 | ||
8980 | @item @var{params} | |
8981 | Returns the requested data. | |
8982 | ||
8983 | @end table | |
8984 | ||
8985 | @code{glGetMaterial} returns in @var{params} the value or values of | |
f37e7e3d | 8986 | parameter @var{pname} of material @var{face}. Six parameters are |
b002944d AW |
8987 | defined: |
8988 | ||
8989 | @table @asis | |
8990 | @item @code{GL_AMBIENT} | |
8991 | @var{params} returns four integer or floating-point values representing | |
f37e7e3d DH |
8992 | the ambient reflectance of the material. Integer values, when requested, |
8993 | are linearly mapped from the internal floating-point representation such | |
8994 | that 1.0 maps to the most positive representable integer value, and | |
8995 | @r{-1.0} maps to the most negative representable integer value. If the | |
8996 | internal value is outside the range @r{[-1,1]}, the corresponding | |
8997 | integer return value is undefined. The initial value is (0.2, 0.2, 0.2, | |
8998 | 1.0) | |
b002944d AW |
8999 | |
9000 | @item @code{GL_DIFFUSE} | |
9001 | @var{params} returns four integer or floating-point values representing | |
f37e7e3d DH |
9002 | the diffuse reflectance of the material. Integer values, when requested, |
9003 | are linearly mapped from the internal floating-point representation such | |
9004 | that 1.0 maps to the most positive representable integer value, and | |
9005 | @r{-1.0} maps to the most negative representable integer value. If the | |
9006 | internal value is outside the range @r{[-1,1]}, the corresponding | |
9007 | integer return value is undefined. The initial value is (0.8, 0.8, 0.8, | |
9008 | 1.0). | |
b002944d AW |
9009 | |
9010 | @item @code{GL_SPECULAR} | |
9011 | @var{params} returns four integer or floating-point values representing | |
f37e7e3d | 9012 | the specular reflectance of the material. Integer values, when |
b002944d AW |
9013 | requested, are linearly mapped from the internal floating-point |
9014 | representation such that 1.0 maps to the most positive representable | |
9015 | integer value, and @r{-1.0} maps to the most negative representable | |
f37e7e3d DH |
9016 | integer value. If the internal value is outside the range @r{[-1,1]}, |
9017 | the corresponding integer return value is undefined. The initial value | |
b002944d AW |
9018 | is (0, 0, 0, 1). |
9019 | ||
9020 | @item @code{GL_EMISSION} | |
9021 | @var{params} returns four integer or floating-point values representing | |
f37e7e3d | 9022 | the emitted light intensity of the material. Integer values, when |
b002944d AW |
9023 | requested, are linearly mapped from the internal floating-point |
9024 | representation such that 1.0 maps to the most positive representable | |
9025 | integer value, and @r{-1.0} maps to the most negative representable | |
f37e7e3d DH |
9026 | integer value. If the internal value is outside the range @r{[-1,1]}, |
9027 | the corresponding integer return value is undefined. The initial value | |
b002944d AW |
9028 | is (0, 0, 0, 1). |
9029 | ||
9030 | @item @code{GL_SHININESS} | |
9031 | @var{params} returns one integer or floating-point value representing | |
f37e7e3d | 9032 | the specular exponent of the material. Integer values, when requested, |
b002944d | 9033 | are computed by rounding the internal floating-point value to the |
f37e7e3d | 9034 | nearest integer value. The initial value is 0. |
b002944d AW |
9035 | |
9036 | @item @code{GL_COLOR_INDEXES} | |
9037 | @var{params} returns three integer or floating-point values representing | |
f37e7e3d DH |
9038 | the ambient, diffuse, and specular indices of the material. These |
9039 | indices are used only for color index lighting. (All the other | |
b002944d AW |
9040 | parameters are used only for RGBA lighting.) Integer values, when |
9041 | requested, are computed by rounding the internal floating-point values | |
9042 | to the nearest integer values. | |
9043 | ||
9044 | @end table | |
9045 | ||
9046 | @code{GL_INVALID_ENUM} is generated if @var{face} or @var{pname} is not | |
9047 | an accepted value. | |
9048 | ||
9049 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMaterial} is | |
9050 | executed between the execution of @code{glBegin} and the corresponding | |
9051 | execution of @code{glEnd}. | |
9052 | ||
9053 | @end deftypefun | |
9054 | ||
9055 | @deftypefun void glGetMinmaxParameterfv target pname params | |
9056 | @deftypefunx void glGetMinmaxParameteriv target pname params | |
9057 | Get minmax parameters. | |
9058 | ||
9059 | @table @asis | |
9060 | @item @var{target} | |
9061 | Must be @code{GL_MINMAX}. | |
9062 | ||
9063 | @item @var{pname} | |
f37e7e3d DH |
9064 | The parameter to be retrieved. Must be one of @code{GL_MINMAX_FORMAT} or |
9065 | @code{GL_MINMAX_SINK}. | |
b002944d AW |
9066 | |
9067 | @item @var{params} | |
9068 | A pointer to storage for the retrieved parameters. | |
9069 | ||
9070 | @end table | |
9071 | ||
9072 | @code{glGetMinmaxParameter} retrieves parameters for the current minmax | |
9073 | table by setting @var{pname} to one of the following values: | |
9074 | ||
9075 | ||
9076 | ||
9077 | @table @asis | |
9078 | @item @strong{Parameter} | |
9079 | @strong{Description} | |
9080 | ||
9081 | @item @code{GL_MINMAX_FORMAT} | |
9082 | Internal format of minmax table | |
9083 | ||
9084 | @item @code{GL_MINMAX_SINK} | |
9085 | Value of the @var{sink} parameter | |
9086 | ||
9087 | @end table | |
9088 | ||
9089 | ||
9090 | ||
9091 | @code{GL_INVALID_ENUM} is generated if @var{target} is not | |
9092 | @code{GL_MINMAX}. | |
9093 | ||
9094 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
9095 | allowable values. | |
9096 | ||
9097 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmaxParameter} | |
9098 | is executed between the execution of @code{glBegin} and the | |
9099 | corresponding execution of @code{glEnd}. | |
9100 | ||
9101 | @end deftypefun | |
9102 | ||
9103 | @deftypefun void glGetMinmax target reset format types values | |
9104 | Get minimum and maximum pixel values. | |
9105 | ||
9106 | @table @asis | |
9107 | @item @var{target} | |
9108 | Must be @code{GL_MINMAX}. | |
9109 | ||
9110 | @item @var{reset} | |
9111 | If @code{GL_TRUE}, all entries in the minmax table that are actually | |
f37e7e3d | 9112 | returned are reset to their initial values. (Other entries are |
b002944d AW |
9113 | unaltered.) If @code{GL_FALSE}, the minmax table is unaltered. |
9114 | ||
9115 | @item @var{format} | |
f37e7e3d | 9116 | The format of the data to be returned in @var{values}. Must be one of |
b002944d AW |
9117 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
9118 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
9119 | @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}. | |
9120 | ||
9121 | @item @var{types} | |
f37e7e3d | 9122 | The type of the data to be returned in @var{values}. Symbolic constants |
b002944d AW |
9123 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
9124 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
9125 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
9126 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
9127 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
9128 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
9129 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
9130 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
9131 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
9132 | ||
9133 | @item @var{values} | |
9134 | A pointer to storage for the returned values. | |
9135 | ||
9136 | @end table | |
9137 | ||
9138 | @code{glGetMinmax} returns the accumulated minimum and maximum pixel | |
9139 | values (computed on a per-component basis) in a one-dimensional image of | |
f37e7e3d DH |
9140 | width 2. The first set of return values are the minima, and the second |
9141 | set of return values are the maxima. The format of the return values is | |
bb894c9d | 9142 | determined by @var{format}, and their type is determined by @var{types}. |
8925f36f AW |
9143 | |
9144 | If a non-zero named buffer object is bound to the | |
9145 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while | |
9146 | minimum and maximum pixel values are requested, @var{values} is treated | |
9147 | as a byte offset into the buffer object's data store. | |
9148 | ||
9149 | No pixel transfer operations are performed on the return values, but | |
9150 | pixel storage modes that are applicable to one-dimensional images are | |
f37e7e3d | 9151 | performed. Color components that are requested in the specified |
8925f36f | 9152 | @var{format}, but that are not included in the internal format of the |
f37e7e3d | 9153 | minmax table, are returned as zero. The assignment of internal color |
8925f36f AW |
9154 | components to the components requested by @var{format} are as follows: |
9155 | ||
9156 | ||
9157 | ||
9158 | @table @asis | |
9159 | @item @strong{Internal Component} | |
9160 | @strong{Resulting Component} | |
9161 | ||
9162 | @item | |
9163 | Red | |
9164 | Red | |
9165 | ||
9166 | @item | |
9167 | Green | |
9168 | Green | |
9169 | ||
9170 | @item | |
9171 | Blue | |
9172 | Blue | |
9173 | ||
9174 | @item | |
9175 | Alpha | |
9176 | Alpha | |
9177 | ||
9178 | @item | |
9179 | Luminance | |
9180 | Red | |
9181 | ||
9182 | @end table | |
9183 | ||
9184 | If @var{reset} is @code{GL_TRUE}, the minmax table entries corresponding | |
f37e7e3d | 9185 | to the return values are reset to their initial values. Minimum and |
8925f36f AW |
9186 | maximum values that are not returned are not modified, even if |
9187 | @var{reset} is @code{GL_TRUE}. | |
9188 | ||
8925f36f AW |
9189 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
9190 | @code{GL_MINMAX}. | |
9191 | ||
9192 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
9193 | allowable values. | |
9194 | ||
9195 | @code{GL_INVALID_ENUM} is generated if @var{types} is not one of the | |
9196 | allowable values. | |
9197 | ||
9198 | @code{GL_INVALID_OPERATION} is generated if @var{types} is one of | |
9199 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
9200 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
9201 | and @var{format} is not @code{GL_RGB}. | |
9202 | ||
9203 | @code{GL_INVALID_OPERATION} is generated if @var{types} is one of | |
9204 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
9205 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
9206 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
9207 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
9208 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
9209 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
9210 | ||
9211 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9212 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
9213 | object's data store is currently mapped. | |
9214 | ||
9215 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9216 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
9217 | would be packed to the buffer object such that the memory writes | |
9218 | required would exceed the data store size. | |
9219 | ||
9220 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9221 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values} | |
9222 | is not evenly divisible into the number of bytes needed to store in | |
9223 | memory a datum indicated by @var{type}. | |
9224 | ||
9225 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmax} is | |
9226 | executed between the execution of @code{glBegin} and the corresponding | |
9227 | execution of @code{glEnd}. | |
9228 | ||
bb894c9d | 9229 | @end deftypefun |
8925f36f | 9230 | |
b002944d AW |
9231 | @deftypefun void glGetPixelMapfv map data |
9232 | @deftypefunx void glGetPixelMapuiv map data | |
d172eed9 | 9233 | @deftypefunx void glGetPixelMapusv map data |
b002944d AW |
9234 | Return the specified pixel map. |
9235 | ||
9236 | @table @asis | |
9237 | @item @var{map} | |
f37e7e3d | 9238 | Specifies the name of the pixel map to return. Accepted values are |
b002944d AW |
9239 | @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S}, |
9240 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
9241 | @code{GL_PIXEL_MAP_I_TO_B}, @code{GL_PIXEL_MAP_I_TO_A}, | |
9242 | @code{GL_PIXEL_MAP_R_TO_R}, @code{GL_PIXEL_MAP_G_TO_G}, | |
9243 | @code{GL_PIXEL_MAP_B_TO_B}, and @code{GL_PIXEL_MAP_A_TO_A}. | |
9244 | ||
9245 | @item @var{data} | |
9246 | Returns the pixel map contents. | |
9247 | ||
9248 | @end table | |
9249 | ||
9250 | See the @code{glPixelMap} reference page for a description of the | |
f37e7e3d | 9251 | acceptable values for the @var{map} parameter. @code{glGetPixelMap} |
b002944d | 9252 | returns in @var{data} the contents of the pixel map specified in |
f37e7e3d | 9253 | @var{map}. Pixel maps are used during the execution of |
b002944d AW |
9254 | @code{glReadPixels}, @code{glDrawPixels}, @code{glCopyPixels}, |
9255 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
9256 | @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D}, | |
9257 | @code{glCopyTexImage1D}, @code{glCopyTexImage2D}, | |
9258 | @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, and | |
f37e7e3d DH |
9259 | @code{glCopyTexSubImage3D}. to map color indices, stencil indices, color |
9260 | components, and depth components to other values. | |
b002944d AW |
9261 | |
9262 | If a non-zero named buffer object is bound to the | |
9263 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
9264 | pixel map is requested, @var{data} is treated as a byte offset into the | |
9265 | buffer object's data store. | |
9266 | ||
9267 | Unsigned integer values, if requested, are linearly mapped from the | |
9268 | internal fixed or floating-point representation such that 1.0 maps to | |
f37e7e3d | 9269 | the largest representable integer value, and 0.0 maps to 0. Return |
b002944d AW |
9270 | unsigned integer values are undefined if the map value was not in the |
9271 | range [0,1]. | |
9272 | ||
9273 | To determine the required size of @var{map}, call @code{glGet} with the | |
9274 | appropriate symbolic constant. | |
9275 | ||
9276 | @code{GL_INVALID_ENUM} is generated if @var{map} is not an accepted | |
9277 | value. | |
9278 | ||
9279 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9280 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
9281 | object's data store is currently mapped. | |
9282 | ||
9283 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9284 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
9285 | would be packed to the buffer object such that the memory writes | |
9286 | required would exceed the data store size. | |
9287 | ||
9288 | @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapfv} if a | |
9289 | non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER} | |
9290 | target and @var{data} is not evenly divisible into the number of bytes | |
9291 | needed to store in memory a GLfloat datum. | |
9292 | ||
9293 | @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapuiv} if a | |
9294 | non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER} | |
9295 | target and @var{data} is not evenly divisible into the number of bytes | |
9296 | needed to store in memory a GLuint datum. | |
9297 | ||
9298 | @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapusv} if a | |
9299 | non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER} | |
9300 | target and @var{data} is not evenly divisible into the number of bytes | |
9301 | needed to store in memory a GLushort datum. | |
9302 | ||
9303 | @code{GL_INVALID_OPERATION} is generated if @code{glGetPixelMap} is | |
9304 | executed between the execution of @code{glBegin} and the corresponding | |
9305 | execution of @code{glEnd}. | |
9306 | ||
9307 | @end deftypefun | |
9308 | ||
9309 | @deftypefun void glGetPointerv pname params | |
9310 | Return the address of the specified pointer. | |
9311 | ||
9312 | @table @asis | |
9313 | @item @var{pname} | |
f37e7e3d DH |
9314 | Specifies the array or buffer pointer to be returned. Symbolic constants |
9315 | @code{GL_COLOR_ARRAY_POINTER}, @code{GL_EDGE_FLAG_ARRAY_POINTER}, | |
9316 | @code{GL_FOG_COORD_ARRAY_POINTER}, @code{GL_FEEDBACK_BUFFER_POINTER}, | |
9317 | @code{GL_INDEX_ARRAY_POINTER}, @code{GL_NORMAL_ARRAY_POINTER}, | |
9318 | @code{GL_SECONDARY_COLOR_ARRAY_POINTER}, | |
b002944d AW |
9319 | @code{GL_SELECTION_BUFFER_POINTER}, |
9320 | @code{GL_TEXTURE_COORD_ARRAY_POINTER}, or @code{GL_VERTEX_ARRAY_POINTER} | |
9321 | are accepted. | |
9322 | ||
9323 | @item @var{params} | |
9324 | Returns the pointer value specified by @var{pname}. | |
9325 | ||
9326 | @end table | |
9327 | ||
f37e7e3d | 9328 | @code{glGetPointerv} returns pointer information. @var{pname} is a |
b002944d AW |
9329 | symbolic constant indicating the pointer to be returned, and |
9330 | @var{params} is a pointer to a location in which to place the returned | |
9331 | data. | |
9332 | ||
9333 | For all @var{pname} arguments except @code{GL_FEEDBACK_BUFFER_POINTER} | |
9334 | and @code{GL_SELECTION_BUFFER_POINTER}, if a non-zero named buffer | |
9335 | object was bound to the @code{GL_ARRAY_BUFFER} target (see | |
9336 | @code{glBindBuffer}) when the desired pointer was previously specified, | |
9337 | the pointer returned is a byte offset into the buffer object's data | |
f37e7e3d | 9338 | store. Buffer objects are only available in OpenGL versions 1.5 and |
b002944d AW |
9339 | greater. |
9340 | ||
9341 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
9342 | value. | |
9343 | ||
9344 | @end deftypefun | |
9345 | ||
bb894c9d | 9346 | @deftypefun void glGetPolygonStipple pattern |
3c9b6116 AW |
9347 | Return the polygon stipple pattern. |
9348 | ||
8925f36f AW |
9349 | @table @asis |
9350 | @item @var{pattern} | |
f37e7e3d | 9351 | Returns the stipple pattern. The initial value is all 1's. |
8925f36f AW |
9352 | |
9353 | @end table | |
9354 | ||
3c9b6116 | 9355 | @code{glGetPolygonStipple} returns to @var{pattern} a @r{32×32} polygon |
f37e7e3d | 9356 | stipple pattern. The pattern is packed into memory as if |
8925f36f AW |
9357 | @code{glReadPixels} with both @var{height} and @var{width} of 32, |
9358 | @var{type} of @code{GL_BITMAP}, and @var{format} of | |
9359 | @code{GL_COLOR_INDEX} were called, and the stipple pattern were stored | |
f37e7e3d DH |
9360 | in an internal @r{32×32} color index buffer. Unlike @code{glReadPixels}, |
9361 | however, pixel transfer operations (shift, offset, pixel map) are not | |
9362 | applied to the returned stipple image. | |
8925f36f AW |
9363 | |
9364 | If a non-zero named buffer object is bound to the | |
9365 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
9366 | polygon stipple pattern is requested, @var{pattern} is treated as a byte | |
9367 | offset into the buffer object's data store. | |
9368 | ||
8925f36f AW |
9369 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object |
9370 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
9371 | object's data store is currently mapped. | |
9372 | ||
9373 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9374 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
9375 | would be packed to the buffer object such that the memory writes | |
9376 | required would exceed the data store size. | |
9377 | ||
9378 | @code{GL_INVALID_OPERATION} is generated if @code{glGetPolygonStipple} | |
9379 | is executed between the execution of @code{glBegin} and the | |
9380 | corresponding execution of @code{glEnd}. | |
9381 | ||
bb894c9d | 9382 | @end deftypefun |
8925f36f | 9383 | |
bb894c9d | 9384 | @deftypefun void glGetProgramInfoLog program maxLength length infoLog |
3c9b6116 AW |
9385 | Returns the information log for a program object. |
9386 | ||
8925f36f AW |
9387 | @table @asis |
9388 | @item @var{program} | |
9389 | Specifies the program object whose information log is to be queried. | |
9390 | ||
9391 | @item @var{maxLength} | |
9392 | Specifies the size of the character buffer for storing the returned | |
9393 | information log. | |
9394 | ||
9395 | @item @var{length} | |
9396 | Returns the length of the string returned in @var{infoLog} (excluding | |
9397 | the null terminator). | |
9398 | ||
9399 | @item @var{infoLog} | |
9400 | Specifies an array of characters that is used to return the information | |
9401 | log. | |
9402 | ||
9403 | @end table | |
9404 | ||
8925f36f | 9405 | @code{glGetProgramInfoLog} returns the information log for the specified |
f37e7e3d DH |
9406 | program object. The information log for a program object is modified |
9407 | when the program object is linked or validated. The string that is | |
8925f36f AW |
9408 | returned will be null terminated. |
9409 | ||
9410 | @code{glGetProgramInfoLog} returns in @var{infoLog} as much of the | |
9411 | information log as it can, up to a maximum of @var{maxLength} | |
f37e7e3d DH |
9412 | characters. The number of characters actually returned, excluding the |
9413 | null termination character, is specified by @var{length}. If the length | |
8925f36f | 9414 | of the returned string is not required, a value of @code{NULL} can be |
f37e7e3d | 9415 | passed in the @var{length} argument. The size of the buffer required to |
8925f36f AW |
9416 | store the returned information log can be obtained by calling |
9417 | @code{glGetProgram} with the value @code{GL_INFO_LOG_LENGTH}. | |
9418 | ||
9419 | The information log for a program object is either an empty string, or a | |
9420 | string containing information about the last link operation, or a string | |
f37e7e3d | 9421 | containing information about the last validation operation. It may |
8925f36f AW |
9422 | contain diagnostic messages, warning messages, and other information. |
9423 | When a program object is created, its information log will be a string | |
9424 | of length 0. | |
9425 | ||
8925f36f AW |
9426 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
9427 | generated by OpenGL. | |
9428 | ||
9429 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
9430 | program object. | |
9431 | ||
9432 | @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0. | |
9433 | ||
9434 | @code{GL_INVALID_OPERATION} is generated if @code{glGetProgramInfoLog} | |
9435 | is executed between the execution of @code{glBegin} and the | |
9436 | corresponding execution of @code{glEnd}. | |
9437 | ||
bb894c9d | 9438 | @end deftypefun |
8925f36f | 9439 | |
b002944d AW |
9440 | @deftypefun void glGetProgramiv program pname params |
9441 | Returns a parameter from a program object. | |
3c9b6116 | 9442 | |
8925f36f | 9443 | @table @asis |
b002944d AW |
9444 | @item @var{program} |
9445 | Specifies the program object to be queried. | |
8925f36f | 9446 | |
b002944d | 9447 | @item @var{pname} |
f37e7e3d | 9448 | Specifies the object parameter. Accepted symbolic names are |
b002944d AW |
9449 | @code{GL_DELETE_STATUS}, @code{GL_LINK_STATUS}, |
9450 | @code{GL_VALIDATE_STATUS}, @code{GL_INFO_LOG_LENGTH}, | |
9451 | @code{GL_ATTACHED_SHADERS}, @code{GL_ACTIVE_ATTRIBUTES}, | |
9452 | @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}, @code{GL_ACTIVE_UNIFORMS}, | |
9453 | @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}. | |
8925f36f | 9454 | |
b002944d AW |
9455 | @item @var{params} |
9456 | Returns the requested object parameter. | |
8925f36f | 9457 | |
b002944d | 9458 | @end table |
8925f36f | 9459 | |
b002944d | 9460 | @code{glGetProgram} returns in @var{params} the value of a parameter for |
f37e7e3d | 9461 | a specific program object. The following parameters are defined: |
8925f36f | 9462 | |
b002944d AW |
9463 | @table @asis |
9464 | @item @code{GL_DELETE_STATUS} | |
8925f36f | 9465 | |
8925f36f | 9466 | |
b002944d AW |
9467 | @var{params} returns @code{GL_TRUE} if @var{program} is currently |
9468 | flagged for deletion, and @code{GL_FALSE} otherwise. | |
9469 | ||
9470 | @item @code{GL_LINK_STATUS} | |
9471 | ||
9472 | ||
9473 | @var{params} returns @code{GL_TRUE} if the last link operation on | |
9474 | @var{program} was successful, and @code{GL_FALSE} otherwise. | |
9475 | ||
9476 | @item @code{GL_VALIDATE_STATUS} | |
9477 | ||
9478 | ||
9479 | @var{params} returns @code{GL_TRUE} or if the last validation operation | |
9480 | on @var{program} was successful, and @code{GL_FALSE} otherwise. | |
9481 | ||
9482 | @item @code{GL_INFO_LOG_LENGTH} | |
9483 | ||
9484 | ||
9485 | @var{params} returns the number of characters in the information log for | |
9486 | @var{program} including the null termination character (i.e., the size | |
f37e7e3d | 9487 | of the character buffer required to store the information log). If |
b002944d AW |
9488 | @var{program} has no information log, a value of 0 is returned. |
9489 | ||
9490 | @item @code{GL_ATTACHED_SHADERS} | |
9491 | ||
9492 | ||
9493 | @var{params} returns the number of shader objects attached to | |
9494 | @var{program}. | |
9495 | ||
9496 | @item @code{GL_ACTIVE_ATTRIBUTES} | |
9497 | ||
9498 | ||
9499 | @var{params} returns the number of active attribute variables for | |
9500 | @var{program}. | |
9501 | ||
9502 | @item @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH} | |
9503 | ||
9504 | ||
9505 | @var{params} returns the length of the longest active attribute name for | |
9506 | @var{program}, including the null termination character (i.e., the size | |
9507 | of the character buffer required to store the longest attribute name). | |
9508 | If no active attributes exist, 0 is returned. | |
9509 | ||
9510 | @item @code{GL_ACTIVE_UNIFORMS} | |
9511 | ||
9512 | ||
9513 | @var{params} returns the number of active uniform variables for | |
9514 | @var{program}. | |
9515 | ||
9516 | @item @code{GL_ACTIVE_UNIFORM_MAX_LENGTH} | |
9517 | ||
9518 | ||
9519 | @var{params} returns the length of the longest active uniform variable | |
9520 | name for @var{program}, including the null termination character (i.e., | |
9521 | the size of the character buffer required to store the longest uniform | |
f37e7e3d | 9522 | variable name). If no active uniform variables exist, 0 is returned. |
b002944d AW |
9523 | |
9524 | @end table | |
9525 | ||
9526 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
9527 | generated by OpenGL. | |
9528 | ||
9529 | @code{GL_INVALID_OPERATION} is generated if @var{program} does not refer | |
9530 | to a program object. | |
9531 | ||
9532 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
9533 | value. | |
9534 | ||
9535 | @code{GL_INVALID_OPERATION} is generated if @code{glGetProgram} is | |
9536 | executed between the execution of @code{glBegin} and the corresponding | |
9537 | execution of @code{glEnd}. | |
9538 | ||
9539 | @end deftypefun | |
9540 | ||
9541 | @deftypefun void glGetQueryiv target pname params | |
9542 | Return parameters of a query object target. | |
9543 | ||
9544 | @table @asis | |
9545 | @item @var{target} | |
f37e7e3d | 9546 | Specifies a query object target. Must be @code{GL_SAMPLES_PASSED}. |
b002944d AW |
9547 | |
9548 | @item @var{pname} | |
f37e7e3d | 9549 | Specifies the symbolic name of a query object target parameter. Accepted |
b002944d AW |
9550 | values are @code{GL_CURRENT_QUERY} or @code{GL_QUERY_COUNTER_BITS}. |
9551 | ||
9552 | @item @var{params} | |
9553 | Returns the requested data. | |
9554 | ||
9555 | @end table | |
9556 | ||
9557 | @code{glGetQueryiv} returns in @var{params} a selected parameter of the | |
9558 | query object target specified by @var{target}. | |
9559 | ||
f37e7e3d | 9560 | @var{pname} names a specific query object target parameter. When |
b002944d AW |
9561 | @var{target} is @code{GL_SAMPLES_PASSED}, @var{pname} can be as follows: |
9562 | ||
9563 | @table @asis | |
9564 | @item @code{GL_CURRENT_QUERY} | |
9565 | @var{params} returns the name of the currently active occlusion query | |
f37e7e3d | 9566 | object. If no occlusion query is active, 0 is returned. The initial |
b002944d AW |
9567 | value is 0. |
9568 | ||
9569 | @item @code{GL_QUERY_COUNTER_BITS} | |
9570 | @var{params} returns the number of bits in the query counter used to | |
f37e7e3d | 9571 | accumulate passing samples. If the number of bits returned is 0, the |
b002944d AW |
9572 | implementation does not support a query counter, and the results |
9573 | obtained from @code{glGetQueryObject} are useless. | |
9574 | ||
9575 | @end table | |
9576 | ||
9577 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
9578 | not an accepted value. | |
9579 | ||
9580 | @code{GL_INVALID_OPERATION} is generated if @code{glGetQueryiv} is | |
9581 | executed between the execution of @code{glBegin} and the corresponding | |
9582 | execution of @code{glEnd}. | |
9583 | ||
9584 | @end deftypefun | |
9585 | ||
9586 | @deftypefun void glGetQueryObjectiv id pname params | |
9587 | @deftypefunx void glGetQueryObjectuiv id pname params | |
9588 | Return parameters of a query object. | |
9589 | ||
9590 | @table @asis | |
9591 | @item @var{id} | |
9592 | Specifies the name of a query object. | |
9593 | ||
9594 | @item @var{pname} | |
f37e7e3d DH |
9595 | Specifies the symbolic name of a query object parameter. Accepted values |
9596 | are @code{GL_QUERY_RESULT} or @code{GL_QUERY_RESULT_AVAILABLE}. | |
b002944d AW |
9597 | |
9598 | @item @var{params} | |
9599 | Returns the requested data. | |
9600 | ||
9601 | @end table | |
9602 | ||
9603 | @code{glGetQueryObject} returns in @var{params} a selected parameter of | |
9604 | the query object specified by @var{id}. | |
9605 | ||
f37e7e3d | 9606 | @var{pname} names a specific query object parameter. @var{pname} can be |
b002944d AW |
9607 | as follows: |
9608 | ||
9609 | @table @asis | |
9610 | @item @code{GL_QUERY_RESULT} | |
9611 | @var{params} returns the value of the query object's passed samples | |
f37e7e3d | 9612 | counter. The initial value is 0. |
b002944d AW |
9613 | |
9614 | @item @code{GL_QUERY_RESULT_AVAILABLE} | |
9615 | @var{params} returns whether the passed samples counter is immediately | |
f37e7e3d DH |
9616 | available. If a delay would occur waiting for the query result, |
9617 | @code{GL_FALSE} is returned. Otherwise, @code{GL_TRUE} is returned, | |
b002944d AW |
9618 | which also indicates that the results of all previous queries are |
9619 | available as well. | |
9620 | ||
9621 | @end table | |
9622 | ||
9623 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
9624 | value. | |
9625 | ||
9626 | @code{GL_INVALID_OPERATION} is generated if @var{id} is not the name of | |
9627 | a query object. | |
9628 | ||
9629 | @code{GL_INVALID_OPERATION} is generated if @var{id} is the name of a | |
9630 | currently active query object. | |
9631 | ||
9632 | @code{GL_INVALID_OPERATION} is generated if @code{glGetQueryObject} is | |
9633 | executed between the execution of @code{glBegin} and the corresponding | |
9634 | execution of @code{glEnd}. | |
9635 | ||
9636 | @end deftypefun | |
9637 | ||
9638 | @deftypefun void glGetSeparableFilter target format type row column span | |
9639 | Get separable convolution filter kernel images. | |
9640 | ||
9641 | @table @asis | |
9642 | @item @var{target} | |
f37e7e3d | 9643 | The separable filter to be retrieved. Must be @code{GL_SEPARABLE_2D}. |
b002944d AW |
9644 | |
9645 | @item @var{format} | |
f37e7e3d | 9646 | Format of the output images. Must be one of @code{GL_RED}, |
b002944d AW |
9647 | @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, |
9648 | @code{GL_BGR}@code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or | |
9649 | @code{GL_LUMINANCE_ALPHA}. | |
9650 | ||
9651 | @item @var{type} | |
f37e7e3d | 9652 | Data type of components in the output images. Symbolic constants |
b002944d AW |
9653 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
9654 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
9655 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
9656 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
9657 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
9658 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
9659 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
9660 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
9661 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
9662 | ||
9663 | @item @var{row} | |
9664 | Pointer to storage for the row filter image. | |
9665 | ||
9666 | @item @var{column} | |
9667 | Pointer to storage for the column filter image. | |
9668 | ||
9669 | @item @var{span} | |
9670 | Pointer to storage for the span filter image (currently unused). | |
9671 | ||
9672 | @end table | |
9673 | ||
9674 | @code{glGetSeparableFilter} returns the two one-dimensional filter | |
f37e7e3d | 9675 | kernel images for the current separable 2D convolution filter. The row |
b002944d AW |
9676 | image is placed in @var{row} and the column image is placed in |
9677 | @var{column} according to the specifications in @var{format} and | |
f37e7e3d | 9678 | @var{type}. (In the current implementation, @var{span} is not affected |
b002944d AW |
9679 | in any way.) No pixel transfer operations are performed on the images, |
9680 | but the relevant pixel storage modes are applied. | |
8925f36f | 9681 | |
bb894c9d AW |
9682 | If a non-zero named buffer object is bound to the |
9683 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
9684 | separable convolution filter is requested, @var{row}, @var{column}, and | |
9685 | @var{span} are treated as a byte offset into the buffer object's data | |
9686 | store. | |
8925f36f | 9687 | |
bb894c9d | 9688 | Color components that are present in @var{format} but not included in |
f37e7e3d DH |
9689 | the internal format of the filters are returned as zero. The assignments |
9690 | of internal color components to the components of @var{format} are as | |
9691 | follows: | |
8925f36f | 9692 | |
8925f36f AW |
9693 | |
9694 | ||
bb894c9d AW |
9695 | @table @asis |
9696 | @item @strong{Internal Component} | |
9697 | @strong{Resulting Component} | |
8925f36f AW |
9698 | |
9699 | @item | |
9700 | Red | |
9701 | Red | |
9702 | ||
9703 | @item | |
9704 | Green | |
9705 | Green | |
9706 | ||
9707 | @item | |
9708 | Blue | |
9709 | Blue | |
9710 | ||
9711 | @item | |
9712 | Alpha | |
9713 | Alpha | |
9714 | ||
9715 | @item | |
9716 | Luminance | |
9717 | Red | |
9718 | ||
9719 | @item | |
9720 | Intensity | |
9721 | Red | |
9722 | ||
9723 | @end table | |
9724 | ||
9725 | ||
9726 | ||
8925f36f AW |
9727 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
9728 | @code{GL_SEPARABLE_2D}. | |
9729 | ||
9730 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
9731 | allowable values. | |
9732 | ||
9733 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
9734 | allowable values. | |
9735 | ||
9736 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
9737 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
9738 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
9739 | and @var{format} is not @code{GL_RGB}. | |
9740 | ||
9741 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
9742 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
9743 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
9744 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
9745 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
9746 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
9747 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
9748 | ||
9749 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9750 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
9751 | object's data store is currently mapped. | |
9752 | ||
9753 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9754 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
9755 | would be packed to the buffer object such that the memory writes | |
9756 | required would exceed the data store size. | |
9757 | ||
9758 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9759 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{row} or | |
9760 | @var{column} is not evenly divisible into the number of bytes needed to | |
9761 | store in memory a datum indicated by @var{type}. | |
9762 | ||
9763 | @code{GL_INVALID_OPERATION} is generated if @code{glGetSeparableFilter} | |
9764 | is executed between the execution of @code{glBegin} and the | |
9765 | corresponding execution of @code{glEnd}. | |
9766 | ||
bb894c9d | 9767 | @end deftypefun |
8925f36f | 9768 | |
bb894c9d | 9769 | @deftypefun void glGetShaderInfoLog shader maxLength length infoLog |
3c9b6116 AW |
9770 | Returns the information log for a shader object. |
9771 | ||
8925f36f AW |
9772 | @table @asis |
9773 | @item @var{shader} | |
9774 | Specifies the shader object whose information log is to be queried. | |
9775 | ||
9776 | @item @var{maxLength} | |
9777 | Specifies the size of the character buffer for storing the returned | |
9778 | information log. | |
9779 | ||
9780 | @item @var{length} | |
9781 | Returns the length of the string returned in @var{infoLog} (excluding | |
9782 | the null terminator). | |
9783 | ||
9784 | @item @var{infoLog} | |
9785 | Specifies an array of characters that is used to return the information | |
9786 | log. | |
9787 | ||
9788 | @end table | |
9789 | ||
8925f36f | 9790 | @code{glGetShaderInfoLog} returns the information log for the specified |
f37e7e3d DH |
9791 | shader object. The information log for a shader object is modified when |
9792 | the shader is compiled. The string that is returned will be null | |
8925f36f AW |
9793 | terminated. |
9794 | ||
9795 | @code{glGetShaderInfoLog} returns in @var{infoLog} as much of the | |
9796 | information log as it can, up to a maximum of @var{maxLength} | |
f37e7e3d DH |
9797 | characters. The number of characters actually returned, excluding the |
9798 | null termination character, is specified by @var{length}. If the length | |
8925f36f | 9799 | of the returned string is not required, a value of @code{NULL} can be |
f37e7e3d | 9800 | passed in the @var{length} argument. The size of the buffer required to |
8925f36f AW |
9801 | store the returned information log can be obtained by calling |
9802 | @code{glGetShader} with the value @code{GL_INFO_LOG_LENGTH}. | |
9803 | ||
9804 | The information log for a shader object is a string that may contain | |
9805 | diagnostic messages, warning messages, and other information about the | |
f37e7e3d DH |
9806 | last compile operation. When a shader object is created, its information |
9807 | log will be a string of length 0. | |
8925f36f | 9808 | |
8925f36f AW |
9809 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
9810 | generated by OpenGL. | |
9811 | ||
9812 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
9813 | object. | |
9814 | ||
9815 | @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0. | |
9816 | ||
9817 | @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderInfoLog} is | |
9818 | executed between the execution of @code{glBegin} and the corresponding | |
9819 | execution of @code{glEnd}. | |
9820 | ||
bb894c9d | 9821 | @end deftypefun |
8925f36f | 9822 | |
bb894c9d | 9823 | @deftypefun void glGetShaderSource shader bufSize length source |
3c9b6116 AW |
9824 | Returns the source code string from a shader object. |
9825 | ||
8925f36f AW |
9826 | @table @asis |
9827 | @item @var{shader} | |
9828 | Specifies the shader object to be queried. | |
9829 | ||
9830 | @item @var{bufSize} | |
9831 | Specifies the size of the character buffer for storing the returned | |
9832 | source code string. | |
9833 | ||
9834 | @item @var{length} | |
9835 | Returns the length of the string returned in @var{source} (excluding the | |
9836 | null terminator). | |
9837 | ||
9838 | @item @var{source} | |
9839 | Specifies an array of characters that is used to return the source code | |
9840 | string. | |
9841 | ||
9842 | @end table | |
9843 | ||
8925f36f | 9844 | @code{glGetShaderSource} returns the concatenation of the source code |
f37e7e3d | 9845 | strings from the shader object specified by @var{shader}. The source |
8925f36f | 9846 | code strings for a shader object are the result of a previous call to |
f37e7e3d | 9847 | @code{glShaderSource}. The string returned by the function will be null |
8925f36f AW |
9848 | terminated. |
9849 | ||
9850 | @code{glGetShaderSource} returns in @var{source} as much of the source | |
f37e7e3d | 9851 | code string as it can, up to a maximum of @var{bufSize} characters. The |
8925f36f | 9852 | number of characters actually returned, excluding the null termination |
f37e7e3d | 9853 | character, is specified by @var{length}. If the length of the returned |
8925f36f | 9854 | string is not required, a value of @code{NULL} can be passed in the |
f37e7e3d | 9855 | @var{length} argument. The size of the buffer required to store the |
8925f36f AW |
9856 | returned source code string can be obtained by calling |
9857 | @code{glGetShader} with the value @code{GL_SHADER_SOURCE_LENGTH}. | |
9858 | ||
8925f36f AW |
9859 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
9860 | generated by OpenGL. | |
9861 | ||
9862 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
9863 | object. | |
9864 | ||
9865 | @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0. | |
9866 | ||
9867 | @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderSource} is | |
9868 | executed between the execution of @code{glBegin} and the corresponding | |
9869 | execution of @code{glEnd}. | |
9870 | ||
bb894c9d | 9871 | @end deftypefun |
8925f36f | 9872 | |
b002944d AW |
9873 | @deftypefun void glGetShaderiv shader pname params |
9874 | Returns a parameter from a shader object. | |
9875 | ||
9876 | @table @asis | |
9877 | @item @var{shader} | |
9878 | Specifies the shader object to be queried. | |
9879 | ||
9880 | @item @var{pname} | |
f37e7e3d | 9881 | Specifies the object parameter. Accepted symbolic names are |
b002944d AW |
9882 | @code{GL_SHADER_TYPE}, @code{GL_DELETE_STATUS}, |
9883 | @code{GL_COMPILE_STATUS}, @code{GL_INFO_LOG_LENGTH}, | |
9884 | @code{GL_SHADER_SOURCE_LENGTH}. | |
9885 | ||
9886 | @item @var{params} | |
9887 | Returns the requested object parameter. | |
9888 | ||
9889 | @end table | |
9890 | ||
9891 | @code{glGetShader} returns in @var{params} the value of a parameter for | |
f37e7e3d | 9892 | a specific shader object. The following parameters are defined: |
b002944d AW |
9893 | |
9894 | @table @asis | |
9895 | @item @code{GL_SHADER_TYPE} | |
9896 | @var{params} returns @code{GL_VERTEX_SHADER} if @var{shader} is a vertex | |
9897 | shader object, and @code{GL_FRAGMENT_SHADER} if @var{shader} is a | |
9898 | fragment shader object. | |
9899 | ||
9900 | @item @code{GL_DELETE_STATUS} | |
9901 | @var{params} returns @code{GL_TRUE} if @var{shader} is currently flagged | |
9902 | for deletion, and @code{GL_FALSE} otherwise. | |
9903 | ||
9904 | @item @code{GL_COMPILE_STATUS} | |
9905 | @var{params} returns @code{GL_TRUE} if the last compile operation on | |
9906 | @var{shader} was successful, and @code{GL_FALSE} otherwise. | |
9907 | ||
9908 | @item @code{GL_INFO_LOG_LENGTH} | |
9909 | @var{params} returns the number of characters in the information log for | |
9910 | @var{shader} including the null termination character (i.e., the size of | |
f37e7e3d | 9911 | the character buffer required to store the information log). If |
b002944d AW |
9912 | @var{shader} has no information log, a value of 0 is returned. |
9913 | ||
9914 | @item @code{GL_SHADER_SOURCE_LENGTH} | |
9915 | @var{params} returns the length of the concatenation of the source | |
9916 | strings that make up the shader source for the @var{shader}, including | |
f37e7e3d DH |
9917 | the null termination character. (i.e., the size of the character buffer |
9918 | required to store the shader source). If no source code exists, 0 is | |
b002944d AW |
9919 | returned. |
9920 | ||
9921 | @end table | |
9922 | ||
9923 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value | |
9924 | generated by OpenGL. | |
9925 | ||
9926 | @code{GL_INVALID_OPERATION} is generated if @var{shader} does not refer | |
9927 | to a shader object. | |
9928 | ||
9929 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
9930 | value. | |
9931 | ||
9932 | @code{GL_INVALID_OPERATION} is generated if @code{glGetShader} is | |
9933 | executed between the execution of @code{glBegin} and the corresponding | |
9934 | execution of @code{glEnd}. | |
9935 | ||
9936 | @end deftypefun | |
9937 | ||
00239761 | 9938 | @deftypefun const-GLubyte* glGetString name |
3c9b6116 AW |
9939 | Return a string describing the current GL connection. |
9940 | ||
8925f36f AW |
9941 | @table @asis |
9942 | @item @var{name} | |
9943 | Specifies a symbolic constant, one of @code{GL_VENDOR}, | |
9944 | @code{GL_RENDERER}, @code{GL_VERSION}, | |
9945 | @code{GL_SHADING_LANGUAGE_VERSION}, or @code{GL_EXTENSIONS}. | |
9946 | ||
9947 | @end table | |
9948 | ||
8925f36f | 9949 | @code{glGetString} returns a pointer to a static string describing some |
f37e7e3d | 9950 | aspect of the current GL connection. @var{name} can be one of the |
8925f36f AW |
9951 | following: |
9952 | ||
9953 | @table @asis | |
9954 | @item @code{GL_VENDOR} | |
9955 | ||
9956 | ||
f37e7e3d | 9957 | Returns the company responsible for this GL implementation. This name |
8925f36f AW |
9958 | does not change from release to release. |
9959 | ||
9960 | @item @code{GL_RENDERER} | |
9961 | ||
9962 | ||
f37e7e3d DH |
9963 | Returns the name of the renderer. This name is typically specific to a |
9964 | particular configuration of a hardware platform. It does not change from | |
9965 | release to release. | |
8925f36f AW |
9966 | |
9967 | @item @code{GL_VERSION} | |
9968 | ||
9969 | ||
9970 | Returns a version or release number. | |
9971 | ||
9972 | @item @code{GL_SHADING_LANGUAGE_VERSION} | |
9973 | ||
9974 | ||
9975 | Returns a version or release number for the shading language. | |
9976 | ||
9977 | @item @code{GL_EXTENSIONS} | |
9978 | ||
9979 | ||
9980 | Returns a space-separated list of supported extensions to GL. | |
9981 | ||
9982 | @end table | |
9983 | ||
bb894c9d AW |
9984 | Because the GL does not include queries for the performance |
9985 | characteristics of an implementation, some applications are written to | |
9986 | recognize known platforms and modify their GL usage based on known | |
f37e7e3d DH |
9987 | performance characteristics of these platforms. Strings @code{GL_VENDOR} |
9988 | and @code{GL_RENDERER} together uniquely specify a platform. They do not | |
9989 | change from release to release and should be used by | |
9990 | platform-recognition algorithms. | |
8925f36f | 9991 | |
b002944d | 9992 | Some applications want to make use of features that are not part of the |
f37e7e3d DH |
9993 | standard GL. These features may be implemented as extensions to the |
9994 | standard GL. The @code{GL_EXTENSIONS} string is a space-separated list | |
9995 | of supported GL extensions. (Extension names never contain a space | |
b002944d AW |
9996 | character.) |
9997 | ||
9998 | The @code{GL_VERSION} and @code{GL_SHADING_LANGUAGE_VERSION} strings | |
f37e7e3d | 9999 | begin with a version number. The version number uses one of these forms: |
b002944d AW |
10000 | |
10001 | @var{major_number.minor_number}@var{major_number.minor_number.release_number} | |
10002 | ||
f37e7e3d | 10003 | Vendor-specific information may follow the version number. Its format |
b002944d AW |
10004 | depends on the implementation, but a space always separates the version |
10005 | number and the vendor-specific information. | |
10006 | ||
10007 | All strings are null-terminated. | |
10008 | ||
10009 | @code{GL_INVALID_ENUM} is generated if @var{name} is not an accepted | |
10010 | value. | |
10011 | ||
10012 | @code{GL_INVALID_OPERATION} is generated if @code{glGetString} is | |
10013 | executed between the execution of @code{glBegin} and the corresponding | |
10014 | execution of @code{glEnd}. | |
10015 | ||
10016 | @end deftypefun | |
10017 | ||
10018 | @deftypefun void glGetTexEnvfv target pname params | |
10019 | @deftypefunx void glGetTexEnviv target pname params | |
10020 | Return texture environment parameters. | |
10021 | ||
10022 | @table @asis | |
10023 | @item @var{target} | |
f37e7e3d | 10024 | Specifies a texture environment. May be @code{GL_TEXTURE_ENV}, |
b002944d AW |
10025 | @code{GL_TEXTURE_FILTER_CONTROL}, or @code{GL_POINT_SPRITE}. |
10026 | ||
10027 | @item @var{pname} | |
f37e7e3d | 10028 | Specifies the symbolic name of a texture environment parameter. Accepted |
b002944d AW |
10029 | values are @code{GL_TEXTURE_ENV_MODE}, @code{GL_TEXTURE_ENV_COLOR}, |
10030 | @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB}, | |
10031 | @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, | |
10032 | @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, | |
10033 | @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB}, | |
10034 | @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA}, | |
10035 | @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE}, | |
10036 | @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}. | |
10037 | ||
10038 | @item @var{params} | |
10039 | Returns the requested data. | |
10040 | ||
10041 | @end table | |
10042 | ||
10043 | @code{glGetTexEnv} returns in @var{params} selected values of a texture | |
f37e7e3d | 10044 | environment that was specified with @code{glTexEnv}. @var{target} |
b002944d AW |
10045 | specifies a texture environment. |
10046 | ||
10047 | When @var{target} is @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must | |
f37e7e3d | 10048 | be @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is |
b002944d AW |
10049 | @code{GL_POINT_SPRITE}, @var{pname} must be @code{GL_COORD_REPLACE}. |
10050 | When @var{target} is @code{GL_TEXTURE_ENV}, @var{pname} can be | |
10051 | @code{GL_TEXTURE_ENV_MODE}, @code{GL_TEXTURE_ENV_COLOR}, | |
10052 | @code{GL_COMBINE_RGB}, @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE}, | |
10053 | @code{GL_ALPHA_SCALE}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, | |
10054 | @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or | |
10055 | @code{GL_SRC2_ALPHA}. | |
10056 | ||
10057 | @var{pname} names a specific texture environment parameter, as follows: | |
10058 | ||
10059 | @table @asis | |
10060 | @item @code{GL_TEXTURE_ENV_MODE} | |
10061 | @var{params} returns the single-valued texture environment mode, a | |
f37e7e3d | 10062 | symbolic constant. The initial value is @code{GL_MODULATE}. |
b002944d AW |
10063 | |
10064 | @item @code{GL_TEXTURE_ENV_COLOR} | |
10065 | @var{params} returns four integer or floating-point values that are the | |
f37e7e3d | 10066 | texture environment color. Integer values, when requested, are linearly |
b002944d AW |
10067 | mapped from the internal floating-point representation such that 1.0 |
10068 | maps to the most positive representable integer, and @r{-1.0} maps to | |
f37e7e3d | 10069 | the most negative representable integer. The initial value is (0, 0, 0, |
b002944d AW |
10070 | 0). |
10071 | ||
10072 | @item @code{GL_TEXTURE_LOD_BIAS} | |
10073 | @var{params} returns a single floating-point value that is the texture | |
f37e7e3d | 10074 | level-of-detail bias. The initial value is 0. |
b002944d AW |
10075 | |
10076 | @item @code{GL_COMBINE_RGB} | |
10077 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10078 | current RGB combine mode. The initial value is @code{GL_MODULATE}. |
b002944d AW |
10079 | |
10080 | @item @code{GL_COMBINE_ALPHA} | |
10081 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10082 | current alpha combine mode. The initial value is @code{GL_MODULATE}. |
b002944d AW |
10083 | |
10084 | @item @code{GL_SRC0_RGB} | |
10085 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10086 | texture combiner zero's RGB source. The initial value is |
b002944d AW |
10087 | @code{GL_TEXTURE}. |
10088 | ||
10089 | @item @code{GL_SRC1_RGB} | |
10090 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10091 | texture combiner one's RGB source. The initial value is |
b002944d AW |
10092 | @code{GL_PREVIOUS}. |
10093 | ||
10094 | @item @code{GL_SRC2_RGB} | |
10095 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10096 | texture combiner two's RGB source. The initial value is |
b002944d AW |
10097 | @code{GL_CONSTANT}. |
10098 | ||
10099 | @item @code{GL_SRC0_ALPHA} | |
10100 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10101 | texture combiner zero's alpha source. The initial value is |
b002944d AW |
10102 | @code{GL_TEXTURE}. |
10103 | ||
10104 | @item @code{GL_SRC1_ALPHA} | |
10105 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10106 | texture combiner one's alpha source. The initial value is |
b002944d AW |
10107 | @code{GL_PREVIOUS}. |
10108 | ||
10109 | @item @code{GL_SRC2_ALPHA} | |
10110 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10111 | texture combiner two's alpha source. The initial value is |
b002944d AW |
10112 | @code{GL_CONSTANT}. |
10113 | ||
10114 | @item @code{GL_OPERAND0_RGB} | |
10115 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10116 | texture combiner zero's RGB operand. The initial value is |
b002944d AW |
10117 | @code{GL_SRC_COLOR}. |
10118 | ||
10119 | @item @code{GL_OPERAND1_RGB} | |
10120 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10121 | texture combiner one's RGB operand. The initial value is |
b002944d AW |
10122 | @code{GL_SRC_COLOR}. |
10123 | ||
10124 | @item @code{GL_OPERAND2_RGB} | |
10125 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10126 | texture combiner two's RGB operand. The initial value is |
b002944d AW |
10127 | @code{GL_SRC_ALPHA}. |
10128 | ||
10129 | @item @code{GL_OPERAND0_ALPHA} | |
10130 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10131 | texture combiner zero's alpha operand. The initial value is |
b002944d AW |
10132 | @code{GL_SRC_ALPHA}. |
10133 | ||
10134 | @item @code{GL_OPERAND1_ALPHA} | |
10135 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10136 | texture combiner one's alpha operand. The initial value is |
b002944d AW |
10137 | @code{GL_SRC_ALPHA}. |
10138 | ||
10139 | @item @code{GL_OPERAND2_ALPHA} | |
10140 | @var{params} returns a single symbolic constant value representing the | |
f37e7e3d | 10141 | texture combiner two's alpha operand. The initial value is |
b002944d AW |
10142 | @code{GL_SRC_ALPHA}. |
10143 | ||
10144 | @item @code{GL_RGB_SCALE} | |
10145 | @var{params} returns a single floating-point value representing the | |
f37e7e3d | 10146 | current RGB texture combiner scaling factor. The initial value is 1.0. |
b002944d AW |
10147 | |
10148 | @item @code{GL_ALPHA_SCALE} | |
10149 | @var{params} returns a single floating-point value representing the | |
f37e7e3d | 10150 | current alpha texture combiner scaling factor. The initial value is 1.0. |
b002944d AW |
10151 | |
10152 | @item @code{GL_COORD_REPLACE} | |
10153 | @var{params} returns a single boolean value representing the current | |
f37e7e3d | 10154 | point sprite texture coordinate replacement enable state. The initial |
b002944d AW |
10155 | value is @code{GL_FALSE}. |
10156 | ||
10157 | @end table | |
10158 | ||
10159 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
10160 | not an accepted value. | |
10161 | ||
10162 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexEnv} is | |
10163 | executed between the execution of @code{glBegin} and the corresponding | |
10164 | execution of @code{glEnd}. | |
10165 | ||
10166 | @end deftypefun | |
10167 | ||
d172eed9 AW |
10168 | @deftypefun void glGetTexGendv coord pname params |
10169 | @deftypefunx void glGetTexGenfv coord pname params | |
b002944d AW |
10170 | @deftypefunx void glGetTexGeniv coord pname params |
10171 | Return texture coordinate generation parameters. | |
10172 | ||
10173 | @table @asis | |
10174 | @item @var{coord} | |
f37e7e3d | 10175 | Specifies a texture coordinate. Must be @code{GL_S}, @code{GL_T}, |
b002944d AW |
10176 | @code{GL_R}, or @code{GL_Q}. |
10177 | ||
10178 | @item @var{pname} | |
f37e7e3d | 10179 | Specifies the symbolic name of the value(s) to be returned. Must be |
b002944d AW |
10180 | either @code{GL_TEXTURE_GEN_MODE} or the name of one of the texture |
10181 | generation plane equations: @code{GL_OBJECT_PLANE} or | |
10182 | @code{GL_EYE_PLANE}. | |
10183 | ||
10184 | @item @var{params} | |
10185 | Returns the requested data. | |
10186 | ||
10187 | @end table | |
10188 | ||
10189 | @code{glGetTexGen} returns in @var{params} selected parameters of a | |
10190 | texture coordinate generation function that was specified using | |
f37e7e3d | 10191 | @code{glTexGen}. @var{coord} names one of the (@var{s}, @var{t}, |
b002944d AW |
10192 | @var{r}, @var{q}) texture coordinates, using the symbolic constant |
10193 | @code{GL_S}, @code{GL_T}, @code{GL_R}, or @code{GL_Q}. | |
10194 | ||
10195 | @var{pname} specifies one of three symbolic names: | |
10196 | ||
10197 | @table @asis | |
10198 | @item @code{GL_TEXTURE_GEN_MODE} | |
10199 | @var{params} returns the single-valued texture generation function, a | |
f37e7e3d | 10200 | symbolic constant. The initial value is @code{GL_EYE_LINEAR}. |
b002944d AW |
10201 | |
10202 | @item @code{GL_OBJECT_PLANE} | |
10203 | @var{params} returns the four plane equation coefficients that specify | |
f37e7e3d DH |
10204 | object linear-coordinate generation. Integer values, when requested, are |
10205 | mapped directly from the internal floating-point representation. | |
b002944d AW |
10206 | |
10207 | @item @code{GL_EYE_PLANE} | |
10208 | @var{params} returns the four plane equation coefficients that specify | |
f37e7e3d DH |
10209 | eye linear-coordinate generation. Integer values, when requested, are |
10210 | mapped directly from the internal floating-point representation. The | |
10211 | returned values are those maintained in eye coordinates. They are not | |
b002944d AW |
10212 | equal to the values specified using @code{glTexGen}, unless the |
10213 | modelview matrix was identity when @code{glTexGen} was called. | |
10214 | ||
10215 | @end table | |
10216 | ||
10217 | @code{GL_INVALID_ENUM} is generated if @var{coord} or @var{pname} is not | |
10218 | an accepted value. | |
10219 | ||
10220 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexGen} is | |
10221 | executed between the execution of @code{glBegin} and the corresponding | |
10222 | execution of @code{glEnd}. | |
10223 | ||
10224 | @end deftypefun | |
10225 | ||
10226 | @deftypefun void glGetTexImage target level format type img | |
10227 | Return a texture image. | |
10228 | ||
10229 | @table @asis | |
10230 | @item @var{target} | |
f37e7e3d | 10231 | Specifies which texture is to be obtained. @code{GL_TEXTURE_1D}, |
b002944d AW |
10232 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, |
10233 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
10234 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
10235 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
10236 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
10237 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and | |
10238 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted. | |
10239 | ||
10240 | @item @var{level} | |
f37e7e3d DH |
10241 | Specifies the level-of-detail number of the desired image. Level 0 is |
10242 | the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap | |
b002944d AW |
10243 | reduction image. |
10244 | ||
10245 | @item @var{format} | |
f37e7e3d | 10246 | Specifies a pixel format for the returned data. The supported formats |
b002944d AW |
10247 | are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
10248 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
10249 | @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}. | |
10250 | ||
10251 | @item @var{type} | |
f37e7e3d | 10252 | Specifies a pixel type for the returned data. The supported types are |
b002944d AW |
10253 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT}, |
10254 | @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
10255 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
10256 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
10257 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
10258 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
10259 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
10260 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
10261 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
10262 | ||
10263 | @item @var{img} | |
f37e7e3d | 10264 | Returns the texture image. Should be a pointer to an array of the type |
b002944d AW |
10265 | specified by @var{type}. |
10266 | ||
10267 | @end table | |
10268 | ||
10269 | @code{glGetTexImage} returns a texture image into @var{img}. | |
10270 | @var{target} specifies whether the desired texture image is one | |
10271 | specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}), | |
10272 | @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of | |
10273 | @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D} | |
f37e7e3d DH |
10274 | (@code{GL_TEXTURE_3D}). @var{level} specifies the level-of-detail number |
10275 | of the desired image. @var{format} and @var{type} specify the format and | |
10276 | type of the desired image array. See the reference pages | |
b002944d AW |
10277 | @code{glTexImage1D} and @code{glDrawPixels} for a description of the |
10278 | acceptable values for the @var{format} and @var{type} parameters, | |
10279 | respectively. | |
10280 | ||
10281 | If a non-zero named buffer object is bound to the | |
10282 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
10283 | texture image is requested, @var{img} is treated as a byte offset into | |
10284 | the buffer object's data store. | |
10285 | ||
10286 | To understand the operation of @code{glGetTexImage}, consider the | |
10287 | selected internal four-component texture image to be an RGBA color | |
f37e7e3d | 10288 | buffer the size of the image. The semantics of @code{glGetTexImage} are |
b002944d AW |
10289 | then identical to those of @code{glReadPixels}, with the exception that |
10290 | no pixel transfer operations are performed, when called with the same | |
10291 | @var{format} and @var{type}, with @var{x} and @var{y} set to 0, | |
10292 | @var{width} set to the width of the texture image (including border if | |
10293 | one was specified), and @var{height} set to 1 for 1D images, or to the | |
10294 | height of the texture image (including border if one was specified) for | |
f37e7e3d | 10295 | 2D images. Because the internal texture image is an RGBA image, pixel |
b002944d AW |
10296 | formats @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, and |
10297 | @code{GL_DEPTH_COMPONENT} are not accepted, and pixel type | |
10298 | @code{GL_BITMAP} is not accepted. | |
10299 | ||
10300 | If the selected texture image does not contain four components, the | |
f37e7e3d DH |
10301 | following mappings are applied. Single-component textures are treated as |
10302 | RGBA buffers with red set to the single-component value, green set to 0, | |
10303 | blue set to 0, and alpha set to 1. Two-component textures are treated as | |
10304 | RGBA buffers with red set to the value of component zero, alpha set to | |
10305 | the value of component one, and green and blue set to 0. Finally, | |
10306 | three-component textures are treated as RGBA buffers with red set to | |
10307 | component zero, green set to component one, blue set to component two, | |
10308 | and alpha set to 1. | |
b002944d AW |
10309 | |
10310 | To determine the required size of @var{img}, use | |
10311 | @code{glGetTexLevelParameter} to determine the dimensions of the | |
10312 | internal texture image, then scale the required number of pixels by the | |
10313 | storage required for each pixel, based on @var{format} and @var{type}. | |
10314 | Be sure to take the pixel storage parameters into account, especially | |
10315 | @code{GL_PACK_ALIGNMENT}. | |
10316 | ||
10317 | @code{GL_INVALID_ENUM} is generated if @var{target}, @var{format}, or | |
10318 | @var{type} is not an accepted value. | |
10319 | ||
10320 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
10321 | ||
10322 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
10323 | @r{@var{log}_2(@var{max},)}, where @r{@var{max}} is the returned value | |
10324 | of @code{GL_MAX_TEXTURE_SIZE}. | |
10325 | ||
10326 | @code{GL_INVALID_OPERATION} is returned if @var{type} is one of | |
10327 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
10328 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
10329 | and @var{format} is not @code{GL_RGB}. | |
10330 | ||
10331 | @code{GL_INVALID_OPERATION} is returned if @var{type} is one of | |
10332 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
10333 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
10334 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
10335 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
10336 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}, and @var{format} is neither | |
10337 | @code{GL_RGBA} or @code{GL_BGRA}. | |
10338 | ||
10339 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
10340 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
10341 | object's data store is currently mapped. | |
10342 | ||
10343 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
10344 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
10345 | would be packed to the buffer object such that the memory writes | |
10346 | required would exceed the data store size. | |
10347 | ||
10348 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
10349 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{img} is | |
10350 | not evenly divisible into the number of bytes needed to store in memory | |
10351 | a datum indicated by @var{type}. | |
10352 | ||
10353 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexImage} is | |
10354 | executed between the execution of @code{glBegin} and the corresponding | |
10355 | execution of @code{glEnd}. | |
10356 | ||
10357 | @end deftypefun | |
10358 | ||
10359 | @deftypefun void glGetTexLevelParameterfv target level pname params | |
10360 | @deftypefunx void glGetTexLevelParameteriv target level pname params | |
10361 | Return texture parameter values for a specific level of detail. | |
10362 | ||
10363 | @table @asis | |
10364 | @item @var{target} | |
10365 | Specifies the symbolic name of the target texture, either | |
10366 | @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, | |
10367 | @code{GL_PROXY_TEXTURE_1D}, @code{GL_PROXY_TEXTURE_2D}, | |
10368 | @code{GL_PROXY_TEXTURE_3D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
10369 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
10370 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
10371 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
10372 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
10373 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
10374 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
10375 | ||
10376 | @item @var{level} | |
f37e7e3d DH |
10377 | Specifies the level-of-detail number of the desired image. Level 0 is |
10378 | the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap | |
b002944d AW |
10379 | reduction image. |
10380 | ||
10381 | @item @var{pname} | |
10382 | Specifies the symbolic name of a texture parameter. | |
10383 | @code{GL_TEXTURE_WIDTH}, @code{GL_TEXTURE_HEIGHT}, | |
10384 | @code{GL_TEXTURE_DEPTH}, @code{GL_TEXTURE_INTERNAL_FORMAT}, | |
10385 | @code{GL_TEXTURE_BORDER}, @code{GL_TEXTURE_RED_SIZE}, | |
10386 | @code{GL_TEXTURE_GREEN_SIZE}, @code{GL_TEXTURE_BLUE_SIZE}, | |
10387 | @code{GL_TEXTURE_ALPHA_SIZE}, @code{GL_TEXTURE_LUMINANCE_SIZE}, | |
10388 | @code{GL_TEXTURE_INTENSITY_SIZE}, @code{GL_TEXTURE_DEPTH_SIZE}, | |
10389 | @code{GL_TEXTURE_COMPRESSED}, and | |
10390 | @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} are accepted. | |
10391 | ||
10392 | @item @var{params} | |
10393 | Returns the requested data. | |
10394 | ||
10395 | @end table | |
10396 | ||
10397 | @code{glGetTexLevelParameter} returns in @var{params} texture parameter | |
10398 | values for a specific level-of-detail value, specified as @var{level}. | |
10399 | @var{target} defines the target texture, either @code{GL_TEXTURE_1D}, | |
10400 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, @code{GL_PROXY_TEXTURE_1D}, | |
10401 | @code{GL_PROXY_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_3D}, | |
10402 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
10403 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
10404 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
10405 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
10406 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
10407 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
10408 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
10409 | ||
10410 | @code{GL_MAX_TEXTURE_SIZE}, and @code{GL_MAX_3D_TEXTURE_SIZE} are not | |
f37e7e3d | 10411 | really descriptive enough. It has to report the largest square texture |
b002944d AW |
10412 | image that can be accommodated with mipmaps and borders, but a long |
10413 | skinny texture, or a texture without mipmaps and borders, may easily fit | |
f37e7e3d | 10414 | in texture memory. The proxy targets allow the user to more accurately |
b002944d AW |
10415 | query whether the GL can accommodate a texture of a given configuration. |
10416 | If the texture cannot be accommodated, the texture state variables, | |
10417 | which may be queried with @code{glGetTexLevelParameter}, are set to 0. | |
10418 | If the texture can be accommodated, the texture state values will be set | |
10419 | as they would be set for a non-proxy target. | |
10420 | ||
10421 | @var{pname} specifies the texture parameter whose value or values will | |
10422 | be returned. | |
10423 | ||
10424 | The accepted parameter names are as follows: | |
10425 | ||
10426 | @table @asis | |
10427 | @item @code{GL_TEXTURE_WIDTH} | |
10428 | ||
10429 | ||
10430 | @var{params} returns a single value, the width of the texture image. | |
f37e7e3d | 10431 | This value includes the border of the texture image. The initial value |
b002944d AW |
10432 | is 0. |
10433 | ||
10434 | @item @code{GL_TEXTURE_HEIGHT} | |
10435 | ||
10436 | ||
10437 | @var{params} returns a single value, the height of the texture image. | |
f37e7e3d | 10438 | This value includes the border of the texture image. The initial value |
b002944d AW |
10439 | is 0. |
10440 | ||
10441 | @item @code{GL_TEXTURE_DEPTH} | |
10442 | ||
10443 | ||
10444 | @var{params} returns a single value, the depth of the texture image. | |
f37e7e3d | 10445 | This value includes the border of the texture image. The initial value |
b002944d AW |
10446 | is 0. |
10447 | ||
10448 | @item @code{GL_TEXTURE_INTERNAL_FORMAT} | |
10449 | ||
10450 | ||
10451 | @var{params} returns a single value, the internal format of the texture | |
10452 | image. | |
10453 | ||
10454 | @item @code{GL_TEXTURE_BORDER} | |
10455 | ||
10456 | ||
10457 | @var{params} returns a single value, the width in pixels of the border | |
f37e7e3d | 10458 | of the texture image. The initial value is 0. |
b002944d AW |
10459 | |
10460 | @item @code{GL_TEXTURE_RED_SIZE}, | |
10461 | @item @code{GL_TEXTURE_GREEN_SIZE}, | |
10462 | @item @code{GL_TEXTURE_BLUE_SIZE}, | |
10463 | @item @code{GL_TEXTURE_ALPHA_SIZE}, | |
10464 | @item @code{GL_TEXTURE_LUMINANCE_SIZE}, | |
10465 | @item @code{GL_TEXTURE_INTENSITY_SIZE}, | |
10466 | @item @code{GL_TEXTURE_DEPTH_SIZE} | |
10467 | ||
10468 | ||
f37e7e3d | 10469 | The internal storage resolution of an individual component. The |
b002944d AW |
10470 | resolution chosen by the GL will be a close match for the resolution |
10471 | requested by the user with the component argument of | |
10472 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
f37e7e3d | 10473 | @code{glCopyTexImage1D}, and @code{glCopyTexImage2D}. The initial value |
b002944d AW |
10474 | is 0. |
10475 | ||
10476 | @item @code{GL_TEXTURE_COMPRESSED} | |
10477 | ||
10478 | ||
10479 | @var{params} returns a single boolean value indicating if the texture | |
f37e7e3d | 10480 | image is stored in a compressed internal format. The initiali value is |
b002944d AW |
10481 | @code{GL_FALSE}. |
10482 | ||
10483 | @item @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} | |
10484 | ||
10485 | ||
10486 | @var{params} returns a single integer value, the number of unsigned | |
10487 | bytes of the compressed texture image that would be returned from | |
10488 | @code{glGetCompressedTexImage}. | |
10489 | ||
10490 | @end table | |
10491 | ||
10492 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
10493 | not an accepted value. | |
10494 | ||
10495 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
10496 | ||
10497 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
10498 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of | |
10499 | @code{GL_MAX_TEXTURE_SIZE}. | |
10500 | ||
10501 | @code{GL_INVALID_OPERATION} is generated if | |
10502 | @code{glGetTexLevelParameter} is executed between the execution of | |
10503 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
10504 | ||
10505 | @code{GL_INVALID_OPERATION} is generated if | |
10506 | @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} is queried on texture images | |
10507 | with an uncompressed internal format or on proxy targets. | |
10508 | ||
10509 | @end deftypefun | |
10510 | ||
10511 | @deftypefun void glGetTexParameterfv target pname params | |
10512 | @deftypefunx void glGetTexParameteriv target pname params | |
10513 | Return texture parameter values. | |
10514 | ||
10515 | @table @asis | |
10516 | @item @var{target} | |
f37e7e3d | 10517 | Specifies the symbolic name of the target texture. @code{GL_TEXTURE_1D}, |
b002944d AW |
10518 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, and |
10519 | @code{GL_TEXTURE_CUBE_MAP} are accepted. | |
10520 | ||
10521 | @item @var{pname} | |
10522 | Specifies the symbolic name of a texture parameter. | |
10523 | @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_FILTER}, | |
10524 | @code{GL_TEXTURE_MIN_LOD}, @code{GL_TEXTURE_MAX_LOD}, | |
10525 | @code{GL_TEXTURE_BASE_LEVEL}, @code{GL_TEXTURE_MAX_LEVEL}, | |
10526 | @code{GL_TEXTURE_WRAP_S}, @code{GL_TEXTURE_WRAP_T}, | |
10527 | @code{GL_TEXTURE_WRAP_R}, @code{GL_TEXTURE_BORDER_COLOR}, | |
10528 | @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_RESIDENT}, | |
10529 | @code{GL_TEXTURE_COMPARE_MODE}, @code{GL_TEXTURE_COMPARE_FUNC}, | |
10530 | @code{GL_DEPTH_TEXTURE_MODE}, and @code{GL_GENERATE_MIPMAP} are | |
10531 | accepted. | |
10532 | ||
10533 | @item @var{params} | |
10534 | Returns the texture parameters. | |
10535 | ||
10536 | @end table | |
10537 | ||
10538 | @code{glGetTexParameter} returns in @var{params} the value or values of | |
f37e7e3d DH |
10539 | the texture parameter specified as @var{pname}. @var{target} defines the |
10540 | target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, | |
b002944d | 10541 | @code{GL_TEXTURE_3D}, or @code{GL_TEXTURE_CUBE_MAP}, to specify one-, |
f37e7e3d DH |
10542 | two-, or three-dimensional or cube-mapped texturing. @var{pname} accepts |
10543 | the same symbols as @code{glTexParameter}, with the same | |
b002944d AW |
10544 | interpretations: |
10545 | ||
10546 | @table @asis | |
10547 | @item @code{GL_TEXTURE_MAG_FILTER} | |
10548 | Returns the single-valued texture magnification filter, a symbolic | |
f37e7e3d | 10549 | constant. The initial value is @code{GL_LINEAR}. |
b002944d AW |
10550 | |
10551 | @item @code{GL_TEXTURE_MIN_FILTER} | |
10552 | Returns the single-valued texture minification filter, a symbolic | |
f37e7e3d | 10553 | constant. The initial value is @code{GL_NEAREST_MIPMAP_LINEAR}. |
b002944d AW |
10554 | |
10555 | @item @code{GL_TEXTURE_MIN_LOD} | |
f37e7e3d | 10556 | Returns the single-valued texture minimum level-of-detail value. The |
b002944d AW |
10557 | initial value is @r{-1000}. |
10558 | ||
10559 | @item @code{GL_TEXTURE_MAX_LOD} | |
f37e7e3d | 10560 | Returns the single-valued texture maximum level-of-detail value. The |
b002944d AW |
10561 | initial value is 1000. |
10562 | ||
10563 | @item @code{GL_TEXTURE_BASE_LEVEL} | |
f37e7e3d | 10564 | Returns the single-valued base texture mipmap level. The initial value |
b002944d AW |
10565 | is 0. |
10566 | ||
10567 | @item @code{GL_TEXTURE_MAX_LEVEL} | |
f37e7e3d | 10568 | Returns the single-valued maximum texture mipmap array level. The |
b002944d AW |
10569 | initial value is 1000. |
10570 | ||
10571 | @item @code{GL_TEXTURE_WRAP_S} | |
10572 | Returns the single-valued wrapping function for texture coordinate | |
f37e7e3d | 10573 | @r{@var{s}}, a symbolic constant. The initial value is @code{GL_REPEAT}. |
b002944d AW |
10574 | |
10575 | @item @code{GL_TEXTURE_WRAP_T} | |
10576 | Returns the single-valued wrapping function for texture coordinate | |
f37e7e3d | 10577 | @r{@var{t}}, a symbolic constant. The initial value is @code{GL_REPEAT}. |
b002944d AW |
10578 | |
10579 | @item @code{GL_TEXTURE_WRAP_R} | |
10580 | Returns the single-valued wrapping function for texture coordinate | |
f37e7e3d | 10581 | @r{@var{r}}, a symbolic constant. The initial value is @code{GL_REPEAT}. |
b002944d AW |
10582 | |
10583 | @item @code{GL_TEXTURE_BORDER_COLOR} | |
10584 | Returns four integer or floating-point numbers that comprise the RGBA | |
f37e7e3d DH |
10585 | color of the texture border. Floating-point values are returned in the |
10586 | range @r{[0,1]}. Integer values are returned as a linear mapping of the | |
b002944d AW |
10587 | internal floating-point representation such that 1.0 maps to the most |
10588 | positive representable integer and @r{-1.0} maps to the most negative | |
f37e7e3d | 10589 | representable integer. The initial value is (0, 0, 0, 0). |
b002944d AW |
10590 | |
10591 | @item @code{GL_TEXTURE_PRIORITY} | |
10592 | Returns the residence priority of the target texture (or the named | |
f37e7e3d | 10593 | texture bound to it). The initial value is 1. See |
b002944d AW |
10594 | @code{glPrioritizeTextures}. |
10595 | ||
10596 | @item @code{GL_TEXTURE_RESIDENT} | |
f37e7e3d | 10597 | Returns the residence status of the target texture. If the value |
b002944d | 10598 | returned in @var{params} is @code{GL_TRUE}, the texture is resident in |
f37e7e3d | 10599 | texture memory. See @code{glAreTexturesResident}. |
b002944d AW |
10600 | |
10601 | @item @code{GL_TEXTURE_COMPARE_MODE} | |
10602 | Returns a single-valued texture comparison mode, a symbolic constant. | |
f37e7e3d | 10603 | The initial value is @code{GL_NONE}. See @code{glTexParameter}. |
b002944d AW |
10604 | |
10605 | @item @code{GL_TEXTURE_COMPARE_FUNC} | |
10606 | Returns a single-valued texture comparison function, a symbolic | |
f37e7e3d | 10607 | constant. The initial value is @code{GL_LEQUAL}. See |
b002944d AW |
10608 | @code{glTexParameter}. |
10609 | ||
10610 | @item @code{GL_DEPTH_TEXTURE_MODE} | |
10611 | Returns a single-valued texture format indicating how the depth values | |
f37e7e3d DH |
10612 | should be converted into color components. The initial value is |
10613 | @code{GL_LUMINANCE}. See @code{glTexParameter}. | |
b002944d AW |
10614 | |
10615 | @item @code{GL_GENERATE_MIPMAP} | |
10616 | Returns a single boolean value indicating if automatic mipmap level | |
f37e7e3d | 10617 | updates are enabled. See @code{glTexParameter}. |
b002944d AW |
10618 | |
10619 | @end table | |
10620 | ||
10621 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
10622 | not an accepted value. | |
10623 | ||
10624 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexParameter} is | |
10625 | executed between the execution of @code{glBegin} and the corresponding | |
10626 | execution of @code{glEnd}. | |
10627 | ||
10628 | @end deftypefun | |
10629 | ||
10630 | @deftypefun GLint glGetUniformLocation program name | |
10631 | Returns the location of a uniform variable. | |
10632 | ||
10633 | @table @asis | |
10634 | @item @var{program} | |
10635 | Specifies the program object to be queried. | |
10636 | ||
10637 | @item @var{name} | |
10638 | Points to a null terminated string containing the name of the uniform | |
10639 | variable whose location is to be queried. | |
10640 | ||
10641 | @end table | |
10642 | ||
10643 | @code{glGetUniformLocation } returns an integer that represents the | |
10644 | location of a specific uniform variable within a program object. | |
10645 | @var{name} must be a null terminated string that contains no white | |
f37e7e3d | 10646 | space. @var{name} must be an active uniform variable name in |
b002944d | 10647 | @var{program} that is not a structure, an array of structures, or a |
f37e7e3d | 10648 | subcomponent of a vector or a matrix. This function returns -1 if |
b002944d AW |
10649 | @var{name} does not correspond to an active uniform variable in |
10650 | @var{program} or if @var{name} starts with the reserved prefix "gl_". | |
10651 | ||
10652 | Uniform variables that are structures or arrays of structures may be | |
10653 | queried by calling @code{glGetUniformLocation} for each field within the | |
f37e7e3d | 10654 | structure. The array element operator "[]" and the structure field |
b002944d | 10655 | operator "." may be used in @var{name} in order to select elements |
f37e7e3d | 10656 | within an array or fields within a structure. The result of using these |
b002944d | 10657 | operators is not allowed to be another structure, an array of |
f37e7e3d | 10658 | structures, or a subcomponent of a vector or a matrix. Except if the |
b002944d AW |
10659 | last part of @var{name} indicates a uniform variable array, the location |
10660 | of the first element of an array can be retrieved by using the name of | |
10661 | the array, or by using the name appended by "[0]". | |
10662 | ||
10663 | The actual locations assigned to uniform variables are not known until | |
f37e7e3d | 10664 | the program object is linked successfully. After linking has occurred, |
b002944d | 10665 | the command @code{glGetUniformLocation} can be used to obtain the |
f37e7e3d | 10666 | location of a uniform variable. This location value can then be passed |
b002944d AW |
10667 | to @code{glUniform} to set the value of the uniform variable or to |
10668 | @code{glGetUniform} in order to query the current value of the uniform | |
f37e7e3d DH |
10669 | variable. After a program object has been linked successfully, the index |
10670 | values for uniform variables remain fixed until the next link command | |
10671 | occurs. Uniform variable locations and values can only be queried after | |
10672 | a link if the link was successful. | |
b002944d AW |
10673 | |
10674 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
10675 | generated by OpenGL. | |
10676 | ||
10677 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
10678 | program object. | |
10679 | ||
10680 | @code{GL_INVALID_OPERATION} is generated if @var{program} has not been | |
10681 | successfully linked. | |
10682 | ||
10683 | @code{GL_INVALID_OPERATION} is generated if @code{glGetUniformLocation} | |
10684 | is executed between the execution of @code{glBegin} and the | |
10685 | corresponding execution of @code{glEnd}. | |
10686 | ||
10687 | @end deftypefun | |
10688 | ||
10689 | @deftypefun void glGetUniformfv program location params | |
10690 | @deftypefunx void glGetUniformiv program location params | |
10691 | Returns the value of a uniform variable. | |
10692 | ||
10693 | @table @asis | |
10694 | @item @var{program} | |
10695 | Specifies the program object to be queried. | |
10696 | ||
10697 | @item @var{location} | |
10698 | Specifies the location of the uniform variable to be queried. | |
10699 | ||
10700 | @item @var{params} | |
10701 | Returns the value of the specified uniform variable. | |
10702 | ||
10703 | @end table | |
10704 | ||
10705 | @code{glGetUniform} returns in @var{params} the value(s) of the | |
f37e7e3d DH |
10706 | specified uniform variable. The type of the uniform variable specified |
10707 | by @var{location} determines the number of values returned. If the | |
b002944d | 10708 | uniform variable is defined in the shader as a boolean, int, or float, a |
f37e7e3d DH |
10709 | single value will be returned. If it is defined as a vec2, ivec2, or |
10710 | bvec2, two values will be returned. If it is defined as a vec3, ivec3, | |
10711 | or bvec3, three values will be returned, and so on. To query values | |
b002944d | 10712 | stored in uniform variables declared as arrays, call @code{glGetUniform} |
f37e7e3d | 10713 | for each element of the array. To query values stored in uniform |
b002944d | 10714 | variables declared as structures, call @code{glGetUniform} for each |
f37e7e3d | 10715 | field in the structure. The values for uniform variables declared as a |
b002944d AW |
10716 | matrix will be returned in column major order. |
10717 | ||
10718 | The locations assigned to uniform variables are not known until the | |
f37e7e3d | 10719 | program object is linked. After linking has occurred, the command |
b002944d | 10720 | @code{glGetUniformLocation} can be used to obtain the location of a |
f37e7e3d | 10721 | uniform variable. This location value can then be passed to |
b002944d | 10722 | @code{glGetUniform} in order to query the current value of the uniform |
f37e7e3d DH |
10723 | variable. After a program object has been linked successfully, the index |
10724 | values for uniform variables remain fixed until the next link command | |
10725 | occurs. The uniform variable values can only be queried after a link if | |
10726 | the link was successful. | |
b002944d AW |
10727 | |
10728 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
10729 | generated by OpenGL. | |
10730 | ||
10731 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
10732 | program object. | |
10733 | ||
10734 | @code{GL_INVALID_OPERATION} is generated if @var{program} has not been | |
10735 | successfully linked. | |
10736 | ||
10737 | @code{GL_INVALID_OPERATION} is generated if @var{location} does not | |
10738 | correspond to a valid uniform variable location for the specified | |
10739 | program object. | |
10740 | ||
10741 | @code{GL_INVALID_OPERATION} is generated if @code{glGetUniform} is | |
10742 | executed between the execution of @code{glBegin} and the corresponding | |
10743 | execution of @code{glEnd}. | |
10744 | ||
10745 | @end deftypefun | |
10746 | ||
10747 | @deftypefun void glGetVertexAttribPointerv index pname pointer | |
10748 | Return the address of the specified generic vertex attribute pointer. | |
10749 | ||
10750 | @table @asis | |
10751 | @item @var{index} | |
10752 | Specifies the generic vertex attribute parameter to be returned. | |
10753 | ||
10754 | @item @var{pname} | |
10755 | Specifies the symbolic name of the generic vertex attribute parameter to | |
f37e7e3d | 10756 | be returned. Must be @code{GL_VERTEX_ATTRIB_ARRAY_POINTER}. |
b002944d AW |
10757 | |
10758 | @item @var{pointer} | |
10759 | Returns the pointer value. | |
10760 | ||
10761 | @end table | |
10762 | ||
10763 | @code{glGetVertexAttribPointerv} returns pointer information. | |
10764 | @var{index} is the generic vertex attribute to be queried, @var{pname} | |
10765 | is a symbolic constant indicating the pointer to be returned, and | |
10766 | @var{params} is a pointer to a location in which to place the returned | |
10767 | data. | |
10768 | ||
10769 | If a non-zero named buffer object was bound to the | |
10770 | @code{GL_ARRAY_BUFFER} target (see @code{glBindBuffer}) when the desired | |
10771 | pointer was previously specified, the @var{pointer} returned is a byte | |
10772 | offset into the buffer object's data store. | |
10773 | ||
10774 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
10775 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
10776 | ||
10777 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
10778 | value. | |
10779 | ||
10780 | @end deftypefun | |
10781 | ||
d172eed9 AW |
10782 | @deftypefun void glGetVertexAttribdv index pname params |
10783 | @deftypefunx void glGetVertexAttribfv index pname params | |
b002944d AW |
10784 | @deftypefunx void glGetVertexAttribiv index pname params |
10785 | Return a generic vertex attribute parameter. | |
10786 | ||
10787 | @table @asis | |
10788 | @item @var{index} | |
10789 | Specifies the generic vertex attribute parameter to be queried. | |
10790 | ||
10791 | @item @var{pname} | |
10792 | Specifies the symbolic name of the vertex attribute parameter to be | |
f37e7e3d | 10793 | queried. Accepted values are |
b002944d AW |
10794 | @code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING}, |
10795 | @code{GL_VERTEX_ATTRIB_ARRAY_ENABLED}, | |
10796 | @code{GL_VERTEX_ATTRIB_ARRAY_SIZE}, | |
10797 | @code{GL_VERTEX_ATTRIB_ARRAY_STRIDE}, | |
10798 | @code{GL_VERTEX_ATTRIB_ARRAY_TYPE}, | |
10799 | @code{GL_VERTEX_ATTRIB_ARRAY_NORMALIZED}, or | |
10800 | @code{GL_CURRENT_VERTEX_ATTRIB}. | |
10801 | ||
10802 | @item @var{params} | |
10803 | Returns the requested data. | |
10804 | ||
10805 | @end table | |
10806 | ||
10807 | @code{glGetVertexAttrib} returns in @var{params} the value of a generic | |
f37e7e3d | 10808 | vertex attribute parameter. The generic vertex attribute to be queried |
b002944d AW |
10809 | is specified by @var{index}, and the parameter to be queried is |
10810 | specified by @var{pname}. | |
10811 | ||
10812 | The accepted parameter names are as follows: | |
10813 | ||
10814 | @table @asis | |
10815 | @item @code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING} | |
10816 | ||
10817 | ||
10818 | @var{params} returns a single value, the name of the buffer object | |
10819 | currently bound to the binding point corresponding to generic vertex | |
f37e7e3d DH |
10820 | attribute array @var{index}. If no buffer object is bound, 0 is |
10821 | returned. The initial value is 0. | |
b002944d AW |
10822 | |
10823 | @item @code{GL_VERTEX_ATTRIB_ARRAY_ENABLED} | |
10824 | ||
10825 | ||
10826 | @var{params} returns a single value that is non-zero (true) if the | |
10827 | vertex attribute array for @var{index} is enabled and 0 (false) if it is | |
f37e7e3d | 10828 | disabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
10829 | |
10830 | @item @code{GL_VERTEX_ATTRIB_ARRAY_SIZE} | |
10831 | ||
10832 | ||
10833 | @var{params} returns a single value, the size of the vertex attribute | |
f37e7e3d DH |
10834 | array for @var{index}. The size is the number of values for each element |
10835 | of the vertex attribute array, and it will be 1, 2, 3, or 4. The initial | |
10836 | value is 4. | |
b002944d AW |
10837 | |
10838 | @item @code{GL_VERTEX_ATTRIB_ARRAY_STRIDE} | |
10839 | ||
10840 | ||
10841 | @var{params} returns a single value, the array stride for (number of | |
10842 | bytes between successive elements in) the vertex attribute array for | |
f37e7e3d DH |
10843 | @var{index}. A value of 0 indicates that the array elements are stored |
10844 | sequentially in memory. The initial value is 0. | |
b002944d AW |
10845 | |
10846 | @item @code{GL_VERTEX_ATTRIB_ARRAY_TYPE} | |
10847 | ||
10848 | ||
10849 | @var{params} returns a single value, a symbolic constant indicating the | |
f37e7e3d | 10850 | array type for the vertex attribute array for @var{index}. Possible |
b002944d AW |
10851 | values are @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, |
10852 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
f37e7e3d | 10853 | @code{GL_FLOAT}, and @code{GL_DOUBLE}. The initial value is |
b002944d AW |
10854 | @code{GL_FLOAT}. |
10855 | ||
10856 | @item @code{GL_VERTEX_ATTRIB_ARRAY_NORMALIZED} | |
10857 | ||
10858 | ||
10859 | @var{params} returns a single value that is non-zero (true) if | |
10860 | fixed-point data types for the vertex attribute array indicated by | |
10861 | @var{index} are normalized when they are converted to floating point, | |
f37e7e3d | 10862 | and 0 (false) otherwise. The initial value is @code{GL_FALSE}. |
b002944d AW |
10863 | |
10864 | @item @code{GL_CURRENT_VERTEX_ATTRIB} | |
10865 | ||
10866 | ||
10867 | @var{params} returns four values that represent the current value for | |
f37e7e3d | 10868 | the generic vertex attribute specified by index. Generic vertex |
b002944d | 10869 | attribute 0 is unique in that it has no current state, so an error will |
f37e7e3d | 10870 | be generated if @var{index} is 0. The initial value for all other |
b002944d AW |
10871 | generic vertex attributes is (0,0,0,1). |
10872 | ||
10873 | @end table | |
10874 | ||
10875 | All of the parameters except @code{GL_CURRENT_VERTEX_ATTRIB} represent | |
10876 | client-side state. | |
10877 | ||
10878 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
10879 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
10880 | ||
10881 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
10882 | value. | |
10883 | ||
10884 | @code{GL_INVALID_OPERATION} is generated if @var{index} is 0 and | |
10885 | @var{pname} is @code{GL_CURRENT_VERTEX_ATTRIB}. | |
10886 | ||
10887 | @end deftypefun | |
10888 | ||
10889 | @deftypefun void glGetBooleanv pname params | |
10890 | @deftypefunx void glGetDoublev pname params | |
10891 | @deftypefunx void glGetFloatv pname params | |
10892 | @deftypefunx void glGetIntegerv pname params | |
10893 | Return the value or values of a selected parameter. | |
10894 | ||
10895 | @table @asis | |
10896 | @item @var{pname} | |
f37e7e3d | 10897 | Specifies the parameter value to be returned. The symbolic constants in |
b002944d AW |
10898 | the list below are accepted. |
10899 | ||
10900 | @item @var{params} | |
10901 | Returns the value or values of the specified parameter. | |
10902 | ||
10903 | @end table | |
10904 | ||
10905 | These four commands return values for simple state variables in GL. | |
10906 | @var{pname} is a symbolic constant indicating the state variable to be | |
10907 | returned, and @var{params} is a pointer to an array of the indicated | |
10908 | type in which to place the returned data. | |
10909 | ||
10910 | Type conversion is performed if @var{params} has a different type than | |
f37e7e3d | 10911 | the state variable value being requested. If @code{glGetBooleanv} is |
b002944d | 10912 | called, a floating-point (or integer) value is converted to |
f37e7e3d DH |
10913 | @code{GL_FALSE} if and only if it is 0.0 (or 0). Otherwise, it is |
10914 | converted to @code{GL_TRUE}. If @code{glGetIntegerv} is called, boolean | |
b002944d AW |
10915 | values are returned as @code{GL_TRUE} or @code{GL_FALSE}, and most |
10916 | floating-point values are rounded to the nearest integer value. | |
10917 | Floating-point colors and normals, however, are returned with a linear | |
10918 | mapping that maps 1.0 to the most positive representable integer value | |
f37e7e3d | 10919 | and @r{-1.0} to the most negative representable integer value. If |
b002944d AW |
10920 | @code{glGetFloatv} or @code{glGetDoublev} is called, boolean values are |
10921 | returned as @code{GL_TRUE} or @code{GL_FALSE}, and integer values are | |
10922 | converted to floating-point values. | |
10923 | ||
10924 | The following symbolic constants are accepted by @var{pname}: | |
10925 | ||
10926 | @table @asis | |
10927 | @item @code{GL_ACCUM_ALPHA_BITS} | |
10928 | ||
10929 | ||
10930 | @var{params} returns one value, the number of alpha bitplanes in the | |
10931 | accumulation buffer. | |
10932 | ||
10933 | @item @code{GL_ACCUM_BLUE_BITS} | |
10934 | ||
10935 | ||
10936 | @var{params} returns one value, the number of blue bitplanes in the | |
10937 | accumulation buffer. | |
10938 | ||
10939 | @item @code{GL_ACCUM_CLEAR_VALUE} | |
10940 | ||
10941 | ||
10942 | @var{params} returns four values: the red, green, blue, and alpha values | |
f37e7e3d DH |
10943 | used to clear the accumulation buffer. Integer values, if requested, are |
10944 | linearly mapped from the internal floating-point representation such | |
b002944d | 10945 | that 1.0 returns the most positive representable integer value, and |
f37e7e3d DH |
10946 | @r{-1.0} returns the most negative representable integer value. The |
10947 | initial value is (0, 0, 0, 0). See @code{glClearAccum}. | |
b002944d AW |
10948 | |
10949 | @item @code{GL_ACCUM_GREEN_BITS} | |
10950 | ||
10951 | ||
10952 | @var{params} returns one value, the number of green bitplanes in the | |
10953 | accumulation buffer. | |
10954 | ||
10955 | @item @code{GL_ACCUM_RED_BITS} | |
10956 | ||
10957 | ||
10958 | @var{params} returns one value, the number of red bitplanes in the | |
10959 | accumulation buffer. | |
10960 | ||
10961 | @item @code{GL_ACTIVE_TEXTURE} | |
10962 | ||
10963 | ||
10964 | @var{params} returns a single value indicating the active multitexture | |
f37e7e3d | 10965 | unit. The initial value is @code{GL_TEXTURE0}. See |
b002944d AW |
10966 | @code{glActiveTexture}. |
10967 | ||
10968 | @item @code{GL_ALIASED_POINT_SIZE_RANGE} | |
10969 | ||
10970 | ||
10971 | @var{params} returns two values, the smallest and largest supported | |
10972 | sizes for aliased points. | |
10973 | ||
10974 | @item @code{GL_ALIASED_LINE_WIDTH_RANGE} | |
10975 | ||
10976 | ||
10977 | @var{params} returns two values, the smallest and largest supported | |
10978 | widths for aliased lines. | |
10979 | ||
10980 | @item @code{GL_ALPHA_BIAS} | |
10981 | ||
10982 | ||
10983 | @var{params} returns one value, the alpha bias factor used during pixel | |
f37e7e3d | 10984 | transfers. The initial value is 0. See @code{glPixelTransfer}. |
b002944d AW |
10985 | |
10986 | @item @code{GL_ALPHA_BITS} | |
10987 | ||
10988 | ||
10989 | @var{params} returns one value, the number of alpha bitplanes in each | |
10990 | color buffer. | |
10991 | ||
10992 | @item @code{GL_ALPHA_SCALE} | |
10993 | ||
10994 | ||
10995 | @var{params} returns one value, the alpha scale factor used during pixel | |
f37e7e3d | 10996 | transfers. The initial value is 1. See @code{glPixelTransfer}. |
b002944d AW |
10997 | |
10998 | @item @code{GL_ALPHA_TEST} | |
10999 | ||
11000 | ||
11001 | @var{params} returns a single boolean value indicating whether alpha | |
f37e7e3d | 11002 | testing of fragments is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
11003 | See @code{glAlphaFunc}. |
11004 | ||
11005 | @item @code{GL_ALPHA_TEST_FUNC}@var{params} returns one value, | |
11006 | ||
11007 | ||
f37e7e3d DH |
11008 | the symbolic name of the alpha test function. The initial value is |
11009 | @code{GL_ALWAYS}. See @code{glAlphaFunc}. | |
b002944d AW |
11010 | |
11011 | @item @code{GL_ALPHA_TEST_REF} | |
11012 | ||
11013 | ||
11014 | @var{params} returns one value, the reference value for the alpha test. | |
f37e7e3d | 11015 | The initial value is 0. See @code{glAlphaFunc}. An integer value, if |
b002944d AW |
11016 | requested, is linearly mapped from the internal floating-point |
11017 | representation such that 1.0 returns the most positive representable | |
11018 | integer value, and @r{-1.0} returns the most negative representable | |
11019 | integer value. | |
11020 | ||
11021 | @item @code{GL_ARRAY_BUFFER_BINDING} | |
11022 | ||
11023 | ||
11024 | @var{params} returns a single value, the name of the buffer object | |
f37e7e3d DH |
11025 | currently bound to the target @code{GL_ARRAY_BUFFER}. If no buffer |
11026 | object is bound to this target, 0 is returned. The initial value is 0. | |
b002944d AW |
11027 | See @code{glBindBuffer}. |
11028 | ||
11029 | @item @code{GL_ATTRIB_STACK_DEPTH} | |
11030 | ||
11031 | ||
f37e7e3d DH |
11032 | @var{params} returns one value, the depth of the attribute stack. If the |
11033 | stack is empty, 0 is returned. The initial value is 0. See | |
b002944d AW |
11034 | @code{glPushAttrib}. |
11035 | ||
11036 | @item @code{GL_AUTO_NORMAL} | |
11037 | ||
11038 | ||
11039 | @var{params} returns a single boolean value indicating whether 2D map | |
f37e7e3d DH |
11040 | evaluation automatically generates surface normals. The initial value is |
11041 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
11042 | |
11043 | @item @code{GL_AUX_BUFFERS} | |
11044 | ||
11045 | ||
11046 | @var{params} returns one value, the number of auxiliary color buffers | |
11047 | available. | |
11048 | ||
11049 | @item @code{GL_BLEND} | |
11050 | ||
11051 | ||
11052 | @var{params} returns a single boolean value indicating whether blending | |
f37e7e3d | 11053 | is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11054 | @code{glBlendFunc}. |
11055 | ||
11056 | @item @code{GL_BLEND_COLOR} | |
11057 | ||
11058 | ||
11059 | @var{params} returns four values, the red, green, blue, and alpha values | |
f37e7e3d | 11060 | which are the components of the blend color. See @code{glBlendColor}. |
b002944d AW |
11061 | |
11062 | @item @code{GL_BLEND_DST_ALPHA} | |
11063 | ||
11064 | ||
11065 | @var{params} returns one value, the symbolic constant identifying the | |
f37e7e3d | 11066 | alpha destination blend function. The initial value is @code{GL_ZERO}. |
b002944d AW |
11067 | See @code{glBlendFunc} and @code{glBlendFuncSeparate}. |
11068 | ||
11069 | @item @code{GL_BLEND_DST_RGB} | |
11070 | ||
11071 | ||
11072 | @var{params} returns one value, the symbolic constant identifying the | |
f37e7e3d DH |
11073 | RGB destination blend function. The initial value is @code{GL_ZERO}. See |
11074 | @code{glBlendFunc} and @code{glBlendFuncSeparate}. | |
b002944d AW |
11075 | |
11076 | @item @code{GL_BLEND_EQUATION_RGB} | |
11077 | ||
11078 | ||
11079 | @var{params} returns one value, a symbolic constant indicating whether | |
11080 | the RGB blend equation is @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, | |
f37e7e3d | 11081 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN} or @code{GL_MAX}. See |
b002944d AW |
11082 | @code{glBlendEquationSeparate}. |
11083 | ||
11084 | @item @code{GL_BLEND_EQUATION_ALPHA} | |
11085 | ||
11086 | ||
11087 | @var{params} returns one value, a symbolic constant indicating whether | |
11088 | the Alpha blend equation is @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, | |
f37e7e3d | 11089 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN} or @code{GL_MAX}. See |
b002944d AW |
11090 | @code{glBlendEquationSeparate}. |
11091 | ||
11092 | @item @code{GL_BLEND_SRC_ALPHA} | |
11093 | ||
11094 | ||
11095 | @var{params} returns one value, the symbolic constant identifying the | |
f37e7e3d | 11096 | alpha source blend function. The initial value is @code{GL_ONE}. See |
b002944d AW |
11097 | @code{glBlendFunc} and @code{glBlendFuncSeparate}. |
11098 | ||
11099 | @item @code{GL_BLEND_SRC_RGB} | |
11100 | ||
11101 | ||
11102 | @var{params} returns one value, the symbolic constant identifying the | |
f37e7e3d | 11103 | RGB source blend function. The initial value is @code{GL_ONE}. See |
b002944d AW |
11104 | @code{glBlendFunc} and @code{glBlendFuncSeparate}. |
11105 | ||
11106 | @item @code{GL_BLUE_BIAS} | |
11107 | ||
11108 | ||
11109 | @var{params} returns one value, the blue bias factor used during pixel | |
f37e7e3d | 11110 | transfers. The initial value is 0. See @code{glPixelTransfer}. |
b002944d AW |
11111 | |
11112 | @item @code{GL_BLUE_BITS} | |
11113 | ||
11114 | ||
11115 | @var{params} returns one value, the number of blue bitplanes in each | |
11116 | color buffer. | |
11117 | ||
11118 | @item @code{GL_BLUE_SCALE} | |
11119 | ||
11120 | ||
11121 | @var{params} returns one value, the blue scale factor used during pixel | |
f37e7e3d | 11122 | transfers. The initial value is 1. See @code{glPixelTransfer}. |
b002944d AW |
11123 | |
11124 | @item @code{GL_CLIENT_ACTIVE_TEXTURE} | |
11125 | ||
11126 | ||
11127 | @var{params} returns a single integer value indicating the current | |
f37e7e3d DH |
11128 | client active multitexture unit. The initial value is |
11129 | @code{GL_TEXTURE0}. See @code{glClientActiveTexture}. | |
b002944d AW |
11130 | |
11131 | @item @code{GL_CLIENT_ATTRIB_STACK_DEPTH} | |
11132 | ||
11133 | ||
11134 | @var{params} returns one value indicating the depth of the attribute | |
f37e7e3d | 11135 | stack. The initial value is 0. See @code{glPushClientAttrib}. |
b002944d AW |
11136 | |
11137 | @item @code{GL_CLIP_PLANE}@var{i} | |
11138 | ||
11139 | ||
11140 | @var{params} returns a single boolean value indicating whether the | |
f37e7e3d DH |
11141 | specified clipping plane is enabled. The initial value is |
11142 | @code{GL_FALSE}. See @code{glClipPlane}. | |
b002944d AW |
11143 | |
11144 | @item @code{GL_COLOR_ARRAY} | |
11145 | ||
11146 | ||
11147 | @var{params} returns a single boolean value indicating whether the color | |
f37e7e3d | 11148 | array is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11149 | @code{glColorPointer}. |
11150 | ||
11151 | @item @code{GL_COLOR_ARRAY_BUFFER_BINDING} | |
11152 | ||
11153 | ||
11154 | @var{params} returns a single value, the name of the buffer object | |
f37e7e3d | 11155 | associated with the color array. This buffer object would have been |
b002944d | 11156 | bound to the target @code{GL_ARRAY_BUFFER} at the time of the most |
f37e7e3d DH |
11157 | recent call to @code{glColorPointer}. If no buffer object was bound to |
11158 | this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
11159 | @code{glBindBuffer}. |
11160 | ||
11161 | @item @code{GL_COLOR_ARRAY_SIZE} | |
11162 | ||
11163 | ||
11164 | @var{params} returns one value, the number of components per color in | |
f37e7e3d | 11165 | the color array. The initial value is 4. See @code{glColorPointer}. |
b002944d AW |
11166 | |
11167 | @item @code{GL_COLOR_ARRAY_STRIDE} | |
11168 | ||
11169 | ||
11170 | @var{params} returns one value, the byte offset between consecutive | |
f37e7e3d | 11171 | colors in the color array. The initial value is 0. See |
b002944d AW |
11172 | @code{glColorPointer}. |
11173 | ||
11174 | @item @code{GL_COLOR_ARRAY_TYPE} | |
11175 | ||
11176 | ||
11177 | @var{params} returns one value, the data type of each component in the | |
f37e7e3d | 11178 | color array. The initial value is @code{GL_FLOAT}. See |
b002944d AW |
11179 | @code{glColorPointer}. |
11180 | ||
11181 | @item @code{GL_COLOR_CLEAR_VALUE} | |
11182 | ||
11183 | ||
11184 | @var{params} returns four values: the red, green, blue, and alpha values | |
f37e7e3d | 11185 | used to clear the color buffers. Integer values, if requested, are |
b002944d AW |
11186 | linearly mapped from the internal floating-point representation such |
11187 | that 1.0 returns the most positive representable integer value, and | |
f37e7e3d DH |
11188 | @r{-1.0} returns the most negative representable integer value. The |
11189 | initial value is (0, 0, 0, 0). See @code{glClearColor}. | |
b002944d AW |
11190 | |
11191 | @item @code{GL_COLOR_LOGIC_OP} | |
11192 | ||
11193 | ||
11194 | @var{params} returns a single boolean value indicating whether a | |
11195 | fragment's RGBA color values are merged into the framebuffer using a | |
f37e7e3d | 11196 | logical operation. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11197 | @code{glLogicOp}. |
11198 | ||
11199 | @item @code{GL_COLOR_MATERIAL} | |
11200 | ||
11201 | ||
11202 | @var{params} returns a single boolean value indicating whether one or | |
f37e7e3d DH |
11203 | more material parameters are tracking the current color. The initial |
11204 | value is @code{GL_FALSE}. See @code{glColorMaterial}. | |
b002944d AW |
11205 | |
11206 | @item @code{GL_COLOR_MATERIAL_FACE} | |
11207 | ||
11208 | ||
11209 | @var{params} returns one value, a symbolic constant indicating which | |
f37e7e3d DH |
11210 | materials have a parameter that is tracking the current color. The |
11211 | initial value is @code{GL_FRONT_AND_BACK}. See @code{glColorMaterial}. | |
b002944d AW |
11212 | |
11213 | @item @code{GL_COLOR_MATERIAL_PARAMETER} | |
11214 | ||
11215 | ||
11216 | @var{params} returns one value, a symbolic constant indicating which | |
f37e7e3d DH |
11217 | material parameters are tracking the current color. The initial value is |
11218 | @code{GL_AMBIENT_AND_DIFFUSE}. See @code{glColorMaterial}. | |
b002944d AW |
11219 | |
11220 | @item @code{GL_COLOR_MATRIX} | |
11221 | ||
11222 | ||
11223 | @var{params} returns sixteen values: the color matrix on the top of the | |
f37e7e3d | 11224 | color matrix stack. Initially this matrix is the identity matrix. See |
b002944d AW |
11225 | @code{glPushMatrix}. |
11226 | ||
11227 | @item @code{GL_COLOR_MATRIX_STACK_DEPTH} | |
11228 | ||
11229 | ||
11230 | @var{params} returns one value, the maximum supported depth of the | |
f37e7e3d | 11231 | projection matrix stack. The value must be at least 2. See |
b002944d AW |
11232 | @code{glPushMatrix}. |
11233 | ||
11234 | @item @code{GL_COLOR_SUM} | |
11235 | ||
11236 | ||
11237 | @var{params} returns a single boolean value indicating whether primary | |
f37e7e3d | 11238 | and secondary color sum is enabled. See @code{glSecondaryColor}. |
b002944d AW |
11239 | |
11240 | @item @code{GL_COLOR_TABLE} | |
11241 | ||
11242 | ||
11243 | @var{params} returns a single boolean value indicating whether the color | |
f37e7e3d | 11244 | table lookup is enabled. See @code{glColorTable}. |
b002944d AW |
11245 | |
11246 | @item @code{GL_COLOR_WRITEMASK} | |
11247 | ||
11248 | ||
11249 | @var{params} returns four boolean values: the red, green, blue, and | |
f37e7e3d DH |
11250 | alpha write enables for the color buffers. The initial value is |
11251 | (@code{GL_TRUE}, @code{GL_TRUE}, @code{GL_TRUE}, @code{GL_TRUE}). See | |
b002944d AW |
11252 | @code{glColorMask}. |
11253 | ||
11254 | @item @code{GL_COMPRESSED_TEXTURE_FORMATS} | |
11255 | ||
11256 | ||
11257 | @var{params} returns a list of symbolic constants of length | |
11258 | @code{GL_NUM_COMPRESSED_TEXTURE_FORMATS} indicating which compressed | |
f37e7e3d | 11259 | texture formats are available. See @code{glCompressedTexImage2D}. |
b002944d AW |
11260 | |
11261 | @item @code{GL_CONVOLUTION_1D} | |
11262 | ||
11263 | ||
11264 | @var{params} returns a single boolean value indicating whether 1D | |
f37e7e3d | 11265 | convolution is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11266 | @code{glConvolutionFilter1D}. |
11267 | ||
11268 | @item @code{GL_CONVOLUTION_2D} | |
11269 | ||
11270 | ||
11271 | @var{params} returns a single boolean value indicating whether 2D | |
f37e7e3d | 11272 | convolution is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11273 | @code{glConvolutionFilter2D}. |
11274 | ||
11275 | @item @code{GL_CULL_FACE} | |
11276 | ||
11277 | ||
11278 | @var{params} returns a single boolean value indicating whether polygon | |
f37e7e3d | 11279 | culling is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11280 | @code{glCullFace}. |
11281 | ||
11282 | @item @code{GL_CULL_FACE_MODE} | |
11283 | ||
11284 | ||
11285 | @var{params} returns one value, a symbolic constant indicating which | |
f37e7e3d DH |
11286 | polygon faces are to be culled. The initial value is @code{GL_BACK}. See |
11287 | @code{glCullFace}. | |
b002944d AW |
11288 | |
11289 | @item @code{GL_CURRENT_COLOR} | |
11290 | ||
11291 | ||
11292 | @var{params} returns four values: the red, green, blue, and alpha values | |
f37e7e3d | 11293 | of the current color. Integer values, if requested, are linearly mapped |
b002944d AW |
11294 | from the internal floating-point representation such that 1.0 returns |
11295 | the most positive representable integer value, and @r{-1.0} returns the | |
f37e7e3d DH |
11296 | most negative representable integer value. The initial value is (1, 1, |
11297 | 1, 1). See @code{glColor}. | |
b002944d AW |
11298 | |
11299 | @item @code{GL_CURRENT_FOG_COORD} | |
11300 | ||
11301 | ||
f37e7e3d DH |
11302 | @var{params} returns one value, the current fog coordinate. The initial |
11303 | value is 0. See @code{glFogCoord}. | |
b002944d AW |
11304 | |
11305 | @item @code{GL_CURRENT_INDEX} | |
11306 | ||
11307 | ||
f37e7e3d DH |
11308 | @var{params} returns one value, the current color index. The initial |
11309 | value is 1. See @code{glIndex}. | |
b002944d AW |
11310 | |
11311 | @item @code{GL_CURRENT_NORMAL} | |
11312 | ||
11313 | ||
11314 | @var{params} returns three values: the @var{x}, @var{y}, and @var{z} | |
f37e7e3d DH |
11315 | values of the current normal. Integer values, if requested, are linearly |
11316 | mapped from the internal floating-point representation such that 1.0 | |
11317 | returns the most positive representable integer value, and @r{-1.0} | |
11318 | returns the most negative representable integer value. The initial value | |
11319 | is (0, 0, 1). See @code{glNormal}. | |
b002944d AW |
11320 | |
11321 | @item @code{GL_CURRENT_PROGRAM} | |
11322 | ||
11323 | ||
11324 | @var{params} returns one value, the name of the program object that is | |
f37e7e3d | 11325 | currently active, or 0 if no program object is active. See |
b002944d AW |
11326 | @code{glUseProgram}. |
11327 | ||
11328 | @item @code{GL_CURRENT_RASTER_COLOR} | |
11329 | ||
11330 | ||
11331 | @var{params} returns four values: the red, green, blue, and alpha color | |
f37e7e3d DH |
11332 | values of the current raster position. Integer values, if requested, are |
11333 | linearly mapped from the internal floating-point representation such | |
b002944d | 11334 | that 1.0 returns the most positive representable integer value, and |
f37e7e3d DH |
11335 | @r{-1.0} returns the most negative representable integer value. The |
11336 | initial value is (1, 1, 1, 1). See @code{glRasterPos}. | |
b002944d AW |
11337 | |
11338 | @item @code{GL_CURRENT_RASTER_DISTANCE} | |
11339 | ||
11340 | ||
11341 | @var{params} returns one value, the distance from the eye to the current | |
f37e7e3d | 11342 | raster position. The initial value is 0. See @code{glRasterPos}. |
b002944d AW |
11343 | |
11344 | @item @code{GL_CURRENT_RASTER_INDEX} | |
11345 | ||
11346 | ||
11347 | @var{params} returns one value, the color index of the current raster | |
f37e7e3d | 11348 | position. The initial value is 1. See @code{glRasterPos}. |
b002944d AW |
11349 | |
11350 | @item @code{GL_CURRENT_RASTER_POSITION} | |
11351 | ||
11352 | ||
11353 | @var{params} returns four values: the @var{x}, @var{y}, @var{z}, and | |
f37e7e3d DH |
11354 | @var{w} components of the current raster position. @var{x}, @var{y}, and |
11355 | @var{z} are in window coordinates, and @var{w} is in clip coordinates. | |
11356 | The initial value is (0, 0, 0, 1). See @code{glRasterPos}. | |
b002944d AW |
11357 | |
11358 | @item @code{GL_CURRENT_RASTER_POSITION_VALID} | |
11359 | ||
11360 | ||
11361 | @var{params} returns a single boolean value indicating whether the | |
f37e7e3d | 11362 | current raster position is valid. The initial value is @code{GL_TRUE}. |
b002944d AW |
11363 | See @code{glRasterPos}. |
11364 | ||
11365 | @item @code{GL_CURRENT_RASTER_SECONDARY_COLOR} | |
11366 | ||
11367 | ||
11368 | @var{params} returns four values: the red, green, blue, and alpha | |
f37e7e3d | 11369 | secondary color values of the current raster position. Integer values, |
b002944d AW |
11370 | if requested, are linearly mapped from the internal floating-point |
11371 | representation such that 1.0 returns the most positive representable | |
11372 | integer value, and @r{-1.0} returns the most negative representable | |
f37e7e3d | 11373 | integer value. The initial value is (1, 1, 1, 1). See |
b002944d AW |
11374 | @code{glRasterPos}. |
11375 | ||
11376 | @item @code{GL_CURRENT_RASTER_TEXTURE_COORDS} | |
11377 | ||
11378 | ||
11379 | @var{params} returns four values: the @var{s}, @var{t}, @var{r}, and | |
f37e7e3d DH |
11380 | @var{q} texture coordinates of the current raster position. The initial |
11381 | value is (0, 0, 0, 1). See @code{glRasterPos} and | |
b002944d AW |
11382 | @code{glMultiTexCoord}. |
11383 | ||
11384 | @item @code{GL_CURRENT_SECONDARY_COLOR} | |
11385 | ||
11386 | ||
11387 | @var{params} returns four values: the red, green, blue, and alpha values | |
f37e7e3d | 11388 | of the current secondary color. Integer values, if requested, are |
b002944d AW |
11389 | linearly mapped from the internal floating-point representation such |
11390 | that 1.0 returns the most positive representable integer value, and | |
f37e7e3d DH |
11391 | @r{-1.0} returns the most negative representable integer value. The |
11392 | initial value is (0, 0, 0, 0). See @code{glSecondaryColor}. | |
b002944d AW |
11393 | |
11394 | @item @code{GL_CURRENT_TEXTURE_COORDS} | |
11395 | ||
11396 | ||
11397 | @var{params} returns four values: the @var{s}, @var{t}, @var{r}, and | |
f37e7e3d | 11398 | @var{q} current texture coordinates. The initial value is (0, 0, 0, 1). |
b002944d AW |
11399 | See @code{glMultiTexCoord}. |
11400 | ||
11401 | @item @code{GL_DEPTH_BIAS} | |
11402 | ||
11403 | ||
11404 | @var{params} returns one value, the depth bias factor used during pixel | |
f37e7e3d | 11405 | transfers. The initial value is 0. See @code{glPixelTransfer}. |
b002944d AW |
11406 | |
11407 | @item @code{GL_DEPTH_BITS} | |
11408 | ||
11409 | ||
11410 | @var{params} returns one value, the number of bitplanes in the depth | |
11411 | buffer. | |
11412 | ||
11413 | @item @code{GL_DEPTH_CLEAR_VALUE} | |
11414 | ||
11415 | ||
11416 | @var{params} returns one value, the value that is used to clear the | |
f37e7e3d DH |
11417 | depth buffer. Integer values, if requested, are linearly mapped from the |
11418 | internal floating-point representation such that 1.0 returns the most | |
11419 | positive representable integer value, and @r{-1.0} returns the most | |
11420 | negative representable integer value. The initial value is 1. See | |
b002944d AW |
11421 | @code{glClearDepth}. |
11422 | ||
11423 | @item @code{GL_DEPTH_FUNC} | |
11424 | ||
11425 | ||
11426 | @var{params} returns one value, the symbolic constant that indicates the | |
f37e7e3d | 11427 | depth comparison function. The initial value is @code{GL_LESS}. See |
b002944d AW |
11428 | @code{glDepthFunc}. |
11429 | ||
11430 | @item @code{GL_DEPTH_RANGE} | |
11431 | ||
11432 | ||
11433 | @var{params} returns two values: the near and far mapping limits for the | |
f37e7e3d DH |
11434 | depth buffer. Integer values, if requested, are linearly mapped from the |
11435 | internal floating-point representation such that 1.0 returns the most | |
11436 | positive representable integer value, and @r{-1.0} returns the most | |
11437 | negative representable integer value. The initial value is (0, 1). See | |
b002944d AW |
11438 | @code{glDepthRange}. |
11439 | ||
11440 | @item @code{GL_DEPTH_SCALE} | |
11441 | ||
11442 | ||
11443 | @var{params} returns one value, the depth scale factor used during pixel | |
f37e7e3d | 11444 | transfers. The initial value is 1. See @code{glPixelTransfer}. |
b002944d AW |
11445 | |
11446 | @item @code{GL_DEPTH_TEST} | |
11447 | ||
11448 | ||
11449 | @var{params} returns a single boolean value indicating whether depth | |
f37e7e3d | 11450 | testing of fragments is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
11451 | See @code{glDepthFunc} and @code{glDepthRange}. |
11452 | ||
11453 | @item @code{GL_DEPTH_WRITEMASK} | |
11454 | ||
11455 | ||
11456 | @var{params} returns a single boolean value indicating if the depth | |
f37e7e3d | 11457 | buffer is enabled for writing. The initial value is @code{GL_TRUE}. See |
b002944d AW |
11458 | @code{glDepthMask}. |
11459 | ||
11460 | @item @code{GL_DITHER} | |
11461 | ||
11462 | ||
11463 | @var{params} returns a single boolean value indicating whether dithering | |
f37e7e3d | 11464 | of fragment colors and indices is enabled. The initial value is |
b002944d AW |
11465 | @code{GL_TRUE}. |
11466 | ||
11467 | @item @code{GL_DOUBLEBUFFER} | |
11468 | ||
11469 | ||
11470 | @var{params} returns a single boolean value indicating whether double | |
11471 | buffering is supported. | |
11472 | ||
11473 | @item @code{GL_DRAW_BUFFER} | |
11474 | ||
11475 | ||
11476 | @var{params} returns one value, a symbolic constant indicating which | |
f37e7e3d | 11477 | buffers are being drawn to. See @code{glDrawBuffer}. The initial value |
b002944d AW |
11478 | is @code{GL_BACK} if there are back buffers, otherwise it is |
11479 | @code{GL_FRONT}. | |
11480 | ||
11481 | @item @code{GL_DRAW_BUFFER}@var{i} | |
11482 | ||
11483 | ||
11484 | @var{params} returns one value, a symbolic constant indicating which | |
f37e7e3d DH |
11485 | buffers are being drawn to by the corresponding output color. See |
11486 | @code{glDrawBuffers}. The initial value of @code{GL_DRAW_BUFFER0} is | |
b002944d | 11487 | @code{GL_BACK} if there are back buffers, otherwise it is |
f37e7e3d DH |
11488 | @code{GL_FRONT}. The initial values of draw buffers for all other output |
11489 | colors is @code{GL_NONE}. | |
b002944d AW |
11490 | |
11491 | @item @code{GL_EDGE_FLAG} | |
11492 | ||
11493 | ||
11494 | @var{params} returns a single boolean value indicating whether the | |
f37e7e3d DH |
11495 | current edge flag is @code{GL_TRUE} or @code{GL_FALSE}. The initial |
11496 | value is @code{GL_TRUE}. See @code{glEdgeFlag}. | |
b002944d AW |
11497 | |
11498 | @item @code{GL_EDGE_FLAG_ARRAY} | |
11499 | ||
11500 | ||
11501 | @var{params} returns a single boolean value indicating whether the edge | |
f37e7e3d | 11502 | flag array is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11503 | @code{glEdgeFlagPointer}. |
11504 | ||
11505 | @item @code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING} | |
11506 | ||
11507 | ||
11508 | @var{params} returns a single value, the name of the buffer object | |
f37e7e3d | 11509 | associated with the edge flag array. This buffer object would have been |
b002944d | 11510 | bound to the target @code{GL_ARRAY_BUFFER} at the time of the most |
f37e7e3d DH |
11511 | recent call to @code{glEdgeFlagPointer}. If no buffer object was bound |
11512 | to this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
11513 | @code{glBindBuffer}. |
11514 | ||
11515 | @item @code{GL_EDGE_FLAG_ARRAY_STRIDE} | |
11516 | ||
11517 | ||
11518 | @var{params} returns one value, the byte offset between consecutive edge | |
f37e7e3d | 11519 | flags in the edge flag array. The initial value is 0. See |
b002944d AW |
11520 | @code{glEdgeFlagPointer}. |
11521 | ||
11522 | @item @code{GL_ELEMENT_ARRAY_BUFFER_BINDING} | |
11523 | ||
11524 | ||
11525 | @var{params} returns a single value, the name of the buffer object | |
f37e7e3d DH |
11526 | currently bound to the target @code{GL_ELEMENT_ARRAY_BUFFER}. If no |
11527 | buffer object is bound to this target, 0 is returned. The initial value | |
11528 | is 0. See @code{glBindBuffer}. | |
b002944d AW |
11529 | |
11530 | @item @code{GL_FEEDBACK_BUFFER_SIZE} | |
11531 | ||
11532 | ||
f37e7e3d | 11533 | @var{params} returns one value, the size of the feedback buffer. See |
b002944d AW |
11534 | @code{glFeedbackBuffer}. |
11535 | ||
11536 | @item @code{GL_FEEDBACK_BUFFER_TYPE} | |
11537 | ||
11538 | ||
f37e7e3d | 11539 | @var{params} returns one value, the type of the feedback buffer. See |
b002944d AW |
11540 | @code{glFeedbackBuffer}. |
11541 | ||
11542 | @item @code{GL_FOG} | |
11543 | ||
11544 | ||
11545 | @var{params} returns a single boolean value indicating whether fogging | |
f37e7e3d | 11546 | is enabled. The initial value is @code{GL_FALSE}. See @code{glFog}. |
b002944d AW |
11547 | |
11548 | @item @code{GL_FOG_COORD_ARRAY} | |
11549 | ||
11550 | ||
11551 | @var{params} returns a single boolean value indicating whether the fog | |
f37e7e3d | 11552 | coordinate array is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11553 | @code{glFogCoordPointer}. |
11554 | ||
11555 | @item @code{GL_FOG_COORD_ARRAY_BUFFER_BINDING} | |
11556 | ||
11557 | ||
11558 | @var{params} returns a single value, the name of the buffer object | |
f37e7e3d | 11559 | associated with the fog coordinate array. This buffer object would have |
b002944d | 11560 | been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most |
f37e7e3d DH |
11561 | recent call to @code{glFogCoordPointer}. If no buffer object was bound |
11562 | to this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
11563 | @code{glBindBuffer}. |
11564 | ||
11565 | @item @code{GL_FOG_COORD_ARRAY_STRIDE} | |
11566 | ||
11567 | ||
11568 | @var{params} returns one value, the byte offset between consecutive fog | |
f37e7e3d | 11569 | coordinates in the fog coordinate array. The initial value is 0. See |
b002944d AW |
11570 | @code{glFogCoordPointer}. |
11571 | ||
11572 | @item @code{GL_FOG_COORD_ARRAY_TYPE} | |
11573 | ||
11574 | ||
11575 | @var{params} returns one value, the type of the fog coordinate array. | |
f37e7e3d | 11576 | The initial value is @code{GL_FLOAT}. See @code{glFogCoordPointer}. |
b002944d AW |
11577 | |
11578 | @item @code{GL_FOG_COORD_SRC} | |
11579 | ||
11580 | ||
11581 | @var{params} returns one value, a symbolic constant indicating the | |
f37e7e3d DH |
11582 | source of the fog coordinate. The initial value is |
11583 | @code{GL_FRAGMENT_DEPTH}. See @code{glFog}. | |
b002944d AW |
11584 | |
11585 | @item @code{GL_FOG_COLOR} | |
11586 | ||
11587 | ||
11588 | @var{params} returns four values: the red, green, blue, and alpha | |
f37e7e3d | 11589 | components of the fog color. Integer values, if requested, are linearly |
b002944d AW |
11590 | mapped from the internal floating-point representation such that 1.0 |
11591 | returns the most positive representable integer value, and @r{-1.0} | |
f37e7e3d DH |
11592 | returns the most negative representable integer value. The initial value |
11593 | is (0, 0, 0, 0). See @code{glFog}. | |
b002944d AW |
11594 | |
11595 | @item @code{GL_FOG_DENSITY} | |
11596 | ||
11597 | ||
f37e7e3d DH |
11598 | @var{params} returns one value, the fog density parameter. The initial |
11599 | value is 1. See @code{glFog}. | |
b002944d AW |
11600 | |
11601 | @item @code{GL_FOG_END} | |
11602 | ||
11603 | ||
11604 | @var{params} returns one value, the end factor for the linear fog | |
f37e7e3d | 11605 | equation. The initial value is 1. See @code{glFog}. |
b002944d AW |
11606 | |
11607 | @item @code{GL_FOG_HINT} | |
11608 | ||
11609 | ||
11610 | @var{params} returns one value, a symbolic constant indicating the mode | |
f37e7e3d | 11611 | of the fog hint. The initial value is @code{GL_DONT_CARE}. See |
b002944d AW |
11612 | @code{glHint}. |
11613 | ||
11614 | @item @code{GL_FOG_INDEX} | |
11615 | ||
11616 | ||
f37e7e3d DH |
11617 | @var{params} returns one value, the fog color index. The initial value |
11618 | is 0. See @code{glFog}. | |
b002944d AW |
11619 | |
11620 | @item @code{GL_FOG_MODE} | |
11621 | ||
11622 | ||
11623 | @var{params} returns one value, a symbolic constant indicating which fog | |
f37e7e3d | 11624 | equation is selected. The initial value is @code{GL_EXP}. See |
b002944d AW |
11625 | @code{glFog}. |
11626 | ||
11627 | @item @code{GL_FOG_START} | |
11628 | ||
11629 | ||
11630 | @var{params} returns one value, the start factor for the linear fog | |
f37e7e3d | 11631 | equation. The initial value is 0. See @code{glFog}. |
b002944d AW |
11632 | |
11633 | @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} | |
11634 | ||
11635 | ||
11636 | @var{params} returns one value, a symbolic constant indicating the mode | |
f37e7e3d DH |
11637 | of the derivative accuracy hint for fragment shaders. The initial value |
11638 | is @code{GL_DONT_CARE}. See @code{glHint}. | |
b002944d AW |
11639 | |
11640 | @item @code{GL_FRONT_FACE} | |
11641 | ||
11642 | ||
11643 | @var{params} returns one value, a symbolic constant indicating whether | |
11644 | clockwise or counterclockwise polygon winding is treated as | |
f37e7e3d | 11645 | front-facing. The initial value is @code{GL_CCW}. See |
b002944d AW |
11646 | @code{glFrontFace}. |
11647 | ||
11648 | @item @code{GL_GENERATE_MIPMAP_HINT} | |
11649 | ||
11650 | ||
11651 | @var{params} returns one value, a symbolic constant indicating the mode | |
f37e7e3d DH |
11652 | of the mipmap generation filtering hint. The initial value is |
11653 | @code{GL_DONT_CARE}. See @code{glHint}. | |
b002944d AW |
11654 | |
11655 | @item @code{GL_GREEN_BIAS} | |
11656 | ||
11657 | ||
11658 | @var{params} returns one value, the green bias factor used during pixel | |
f37e7e3d | 11659 | transfers. The initial value is 0. |
b002944d AW |
11660 | |
11661 | @item @code{GL_GREEN_BITS} | |
11662 | ||
11663 | ||
11664 | @var{params} returns one value, the number of green bitplanes in each | |
11665 | color buffer. | |
11666 | ||
11667 | @item @code{GL_GREEN_SCALE} | |
11668 | ||
11669 | ||
11670 | @var{params} returns one value, the green scale factor used during pixel | |
f37e7e3d | 11671 | transfers. The initial value is 1. See @code{glPixelTransfer}. |
b002944d AW |
11672 | |
11673 | @item @code{GL_HISTOGRAM} | |
11674 | ||
11675 | ||
11676 | @var{params} returns a single boolean value indicating whether histogram | |
f37e7e3d | 11677 | is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11678 | @code{glHistogram}. |
11679 | ||
11680 | @item @code{GL_INDEX_ARRAY} | |
11681 | ||
11682 | ||
11683 | @var{params} returns a single boolean value indicating whether the color | |
f37e7e3d | 11684 | index array is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11685 | @code{glIndexPointer}. |
11686 | ||
11687 | @item @code{GL_INDEX_ARRAY_BUFFER_BINDING} | |
11688 | ||
11689 | ||
11690 | @var{params} returns a single value, the name of the buffer object | |
f37e7e3d | 11691 | associated with the color index array. This buffer object would have |
b002944d | 11692 | been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most |
f37e7e3d DH |
11693 | recent call to @code{glIndexPointer}. If no buffer object was bound to |
11694 | this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
11695 | @code{glBindBuffer}. |
11696 | ||
11697 | @item @code{GL_INDEX_ARRAY_STRIDE} | |
11698 | ||
11699 | ||
11700 | @var{params} returns one value, the byte offset between consecutive | |
f37e7e3d | 11701 | color indexes in the color index array. The initial value is 0. See |
b002944d AW |
11702 | @code{glIndexPointer}. |
11703 | ||
11704 | @item @code{GL_INDEX_ARRAY_TYPE} | |
11705 | ||
11706 | ||
11707 | @var{params} returns one value, the data type of indexes in the color | |
f37e7e3d | 11708 | index array. The initial value is @code{GL_FLOAT}. See |
b002944d AW |
11709 | @code{glIndexPointer}. |
11710 | ||
11711 | @item @code{GL_INDEX_BITS} | |
11712 | ||
11713 | ||
11714 | @var{params} returns one value, the number of bitplanes in each color | |
11715 | index buffer. | |
11716 | ||
11717 | @item @code{GL_INDEX_CLEAR_VALUE} | |
11718 | ||
11719 | ||
11720 | @var{params} returns one value, the color index used to clear the color | |
f37e7e3d | 11721 | index buffers. The initial value is 0. See @code{glClearIndex}. |
b002944d AW |
11722 | |
11723 | @item @code{GL_INDEX_LOGIC_OP} | |
11724 | ||
11725 | ||
11726 | @var{params} returns a single boolean value indicating whether a | |
11727 | fragment's index values are merged into the framebuffer using a logical | |
f37e7e3d | 11728 | operation. The initial value is @code{GL_FALSE}. See @code{glLogicOp}. |
b002944d AW |
11729 | |
11730 | @item @code{GL_INDEX_MODE} | |
11731 | ||
11732 | ||
11733 | @var{params} returns a single boolean value indicating whether the GL is | |
11734 | in color index mode (@code{GL_TRUE}) or RGBA mode (@code{GL_FALSE}). | |
11735 | ||
11736 | @item @code{GL_INDEX_OFFSET} | |
11737 | ||
11738 | ||
11739 | @var{params} returns one value, the offset added to color and stencil | |
f37e7e3d | 11740 | indices during pixel transfers. The initial value is 0. See |
b002944d AW |
11741 | @code{glPixelTransfer}. |
11742 | ||
11743 | @item @code{GL_INDEX_SHIFT} | |
11744 | ||
11745 | ||
11746 | @var{params} returns one value, the amount that color and stencil | |
f37e7e3d | 11747 | indices are shifted during pixel transfers. The initial value is 0. See |
b002944d AW |
11748 | @code{glPixelTransfer}. |
11749 | ||
11750 | @item @code{GL_INDEX_WRITEMASK} | |
11751 | ||
11752 | ||
11753 | @var{params} returns one value, a mask indicating which bitplanes of | |
f37e7e3d | 11754 | each color index buffer can be written. The initial value is all 1's. |
b002944d AW |
11755 | See @code{glIndexMask}. |
11756 | ||
11757 | @item @code{GL_LIGHT}@var{i} | |
11758 | ||
11759 | ||
11760 | @var{params} returns a single boolean value indicating whether the | |
f37e7e3d | 11761 | specified light is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11762 | @code{glLight} and @code{glLightModel}. |
11763 | ||
11764 | @item @code{GL_LIGHTING} | |
11765 | ||
11766 | ||
11767 | @var{params} returns a single boolean value indicating whether lighting | |
f37e7e3d | 11768 | is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11769 | @code{glLightModel}. |
11770 | ||
11771 | @item @code{GL_LIGHT_MODEL_AMBIENT} | |
11772 | ||
11773 | ||
11774 | @var{params} returns four values: the red, green, blue, and alpha | |
f37e7e3d DH |
11775 | components of the ambient intensity of the entire scene. Integer values, |
11776 | if requested, are linearly mapped from the internal floating-point | |
11777 | representation such that 1.0 returns the most positive representable | |
11778 | integer value, and @r{-1.0} returns the most negative representable | |
11779 | integer value. The initial value is (0.2, 0.2, 0.2, 1.0). See | |
11780 | @code{glLightModel}. | |
b002944d AW |
11781 | |
11782 | @item @code{GL_LIGHT_MODEL_COLOR_CONTROL} | |
11783 | ||
11784 | ||
11785 | @var{params} returns single enumerated value indicating whether specular | |
11786 | reflection calculations are separated from normal lighting computations. | |
11787 | The initial value is @code{GL_SINGLE_COLOR}. | |
11788 | ||
11789 | @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER} | |
11790 | ||
11791 | ||
11792 | @var{params} returns a single boolean value indicating whether specular | |
11793 | reflection calculations treat the viewer as being local to the scene. | |
f37e7e3d | 11794 | The initial value is @code{GL_FALSE}. See @code{glLightModel}. |
b002944d AW |
11795 | |
11796 | @item @code{GL_LIGHT_MODEL_TWO_SIDE} | |
11797 | ||
11798 | ||
11799 | @var{params} returns a single boolean value indicating whether separate | |
11800 | materials are used to compute lighting for front- and back-facing | |
f37e7e3d | 11801 | polygons. The initial value is @code{GL_FALSE}. See @code{glLightModel}. |
b002944d AW |
11802 | |
11803 | @item @code{GL_LINE_SMOOTH} | |
11804 | ||
11805 | ||
11806 | @var{params} returns a single boolean value indicating whether | |
f37e7e3d | 11807 | antialiasing of lines is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
11808 | See @code{glLineWidth}. |
11809 | ||
11810 | @item @code{GL_LINE_SMOOTH_HINT} | |
11811 | ||
11812 | ||
11813 | @var{params} returns one value, a symbolic constant indicating the mode | |
f37e7e3d DH |
11814 | of the line antialiasing hint. The initial value is @code{GL_DONT_CARE}. |
11815 | See @code{glHint}. | |
b002944d AW |
11816 | |
11817 | @item @code{GL_LINE_STIPPLE} | |
11818 | ||
11819 | ||
11820 | @var{params} returns a single boolean value indicating whether stippling | |
f37e7e3d | 11821 | of lines is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11822 | @code{glLineStipple}. |
11823 | ||
11824 | @item @code{GL_LINE_STIPPLE_PATTERN} | |
11825 | ||
11826 | ||
f37e7e3d DH |
11827 | @var{params} returns one value, the 16-bit line stipple pattern. The |
11828 | initial value is all 1's. See @code{glLineStipple}. | |
b002944d AW |
11829 | |
11830 | @item @code{GL_LINE_STIPPLE_REPEAT} | |
11831 | ||
11832 | ||
f37e7e3d DH |
11833 | @var{params} returns one value, the line stipple repeat factor. The |
11834 | initial value is 1. See @code{glLineStipple}. | |
b002944d AW |
11835 | |
11836 | @item @code{GL_LINE_WIDTH} | |
11837 | ||
11838 | ||
11839 | @var{params} returns one value, the line width as specified with | |
f37e7e3d | 11840 | @code{glLineWidth}. The initial value is 1. |
b002944d AW |
11841 | |
11842 | @item @code{GL_LINE_WIDTH_GRANULARITY} | |
11843 | ||
11844 | ||
11845 | @var{params} returns one value, the width difference between adjacent | |
f37e7e3d | 11846 | supported widths for antialiased lines. See @code{glLineWidth}. |
b002944d AW |
11847 | |
11848 | @item @code{GL_LINE_WIDTH_RANGE} | |
11849 | ||
11850 | ||
11851 | @var{params} returns two values: the smallest and largest supported | |
f37e7e3d | 11852 | widths for antialiased lines. See @code{glLineWidth}. |
b002944d AW |
11853 | |
11854 | @item @code{GL_LIST_BASE} | |
11855 | ||
11856 | ||
11857 | @var{params} returns one value, the base offset added to all names in | |
f37e7e3d | 11858 | arrays presented to @code{glCallLists}. The initial value is 0. See |
b002944d AW |
11859 | @code{glListBase}. |
11860 | ||
11861 | @item @code{GL_LIST_INDEX} | |
11862 | ||
11863 | ||
11864 | @var{params} returns one value, the name of the display list currently | |
f37e7e3d DH |
11865 | under construction. 0 is returned if no display list is currently under |
11866 | construction. The initial value is 0. See @code{glNewList}. | |
b002944d AW |
11867 | |
11868 | @item @code{GL_LIST_MODE} | |
11869 | ||
11870 | ||
11871 | @var{params} returns one value, a symbolic constant indicating the | |
f37e7e3d DH |
11872 | construction mode of the display list currently under construction. The |
11873 | initial value is 0. See @code{glNewList}. | |
b002944d AW |
11874 | |
11875 | @item @code{GL_LOGIC_OP_MODE} | |
11876 | ||
11877 | ||
11878 | @var{params} returns one value, a symbolic constant indicating the | |
f37e7e3d | 11879 | selected logic operation mode. The initial value is @code{GL_COPY}. See |
b002944d AW |
11880 | @code{glLogicOp}. |
11881 | ||
11882 | @item @code{GL_MAP1_COLOR_4} | |
11883 | ||
11884 | ||
11885 | @var{params} returns a single boolean value indicating whether 1D | |
f37e7e3d | 11886 | evaluation generates colors. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11887 | @code{glMap1}. |
11888 | ||
11889 | @item @code{GL_MAP1_GRID_DOMAIN} | |
11890 | ||
11891 | ||
11892 | @var{params} returns two values: the endpoints of the 1D map's grid | |
f37e7e3d | 11893 | domain. The initial value is (0, 1). See @code{glMapGrid}. |
b002944d AW |
11894 | |
11895 | @item @code{GL_MAP1_GRID_SEGMENTS} | |
11896 | ||
11897 | ||
11898 | @var{params} returns one value, the number of partitions in the 1D map's | |
f37e7e3d | 11899 | grid domain. The initial value is 1. See @code{glMapGrid}. |
b002944d AW |
11900 | |
11901 | @item @code{GL_MAP1_INDEX} | |
11902 | ||
11903 | ||
11904 | @var{params} returns a single boolean value indicating whether 1D | |
f37e7e3d DH |
11905 | evaluation generates color indices. The initial value is |
11906 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11907 | |
11908 | @item @code{GL_MAP1_NORMAL} | |
11909 | ||
11910 | ||
11911 | @var{params} returns a single boolean value indicating whether 1D | |
f37e7e3d | 11912 | evaluation generates normals. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11913 | @code{glMap1}. |
11914 | ||
11915 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
11916 | ||
11917 | ||
11918 | @var{params} returns a single boolean value indicating whether 1D | |
f37e7e3d DH |
11919 | evaluation generates 1D texture coordinates. The initial value is |
11920 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11921 | |
11922 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
11923 | ||
11924 | ||
11925 | @var{params} returns a single boolean value indicating whether 1D | |
f37e7e3d DH |
11926 | evaluation generates 2D texture coordinates. The initial value is |
11927 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11928 | |
11929 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
11930 | ||
11931 | ||
11932 | @var{params} returns a single boolean value indicating whether 1D | |
f37e7e3d DH |
11933 | evaluation generates 3D texture coordinates. The initial value is |
11934 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11935 | |
11936 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
11937 | ||
11938 | ||
11939 | @var{params} returns a single boolean value indicating whether 1D | |
f37e7e3d DH |
11940 | evaluation generates 4D texture coordinates. The initial value is |
11941 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11942 | |
11943 | @item @code{GL_MAP1_VERTEX_3} | |
11944 | ||
11945 | ||
11946 | @var{params} returns a single boolean value indicating whether 1D | |
f37e7e3d DH |
11947 | evaluation generates 3D vertex coordinates. The initial value is |
11948 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11949 | |
11950 | @item @code{GL_MAP1_VERTEX_4} | |
11951 | ||
11952 | ||
11953 | @var{params} returns a single boolean value indicating whether 1D | |
f37e7e3d DH |
11954 | evaluation generates 4D vertex coordinates. The initial value is |
11955 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11956 | |
11957 | @item @code{GL_MAP2_COLOR_4} | |
11958 | ||
11959 | ||
11960 | @var{params} returns a single boolean value indicating whether 2D | |
f37e7e3d | 11961 | evaluation generates colors. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11962 | @code{glMap2}. |
11963 | ||
11964 | @item @code{GL_MAP2_GRID_DOMAIN} | |
11965 | ||
11966 | ||
11967 | @var{params} returns four values: the endpoints of the 2D map's | |
f37e7e3d DH |
11968 | @r{@var{i}} and @r{@var{j}} grid domains. The initial value is (0,1; |
11969 | 0,1). See @code{glMapGrid}. | |
b002944d AW |
11970 | |
11971 | @item @code{GL_MAP2_GRID_SEGMENTS} | |
11972 | ||
11973 | ||
11974 | @var{params} returns two values: the number of partitions in the 2D | |
f37e7e3d DH |
11975 | map's @r{@var{i}} and @r{@var{j}} grid domains. The initial value is |
11976 | (1,1). See @code{glMapGrid}. | |
b002944d AW |
11977 | |
11978 | @item @code{GL_MAP2_INDEX} | |
11979 | ||
11980 | ||
11981 | @var{params} returns a single boolean value indicating whether 2D | |
f37e7e3d DH |
11982 | evaluation generates color indices. The initial value is |
11983 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
11984 | |
11985 | @item @code{GL_MAP2_NORMAL} | |
11986 | ||
11987 | ||
11988 | @var{params} returns a single boolean value indicating whether 2D | |
f37e7e3d | 11989 | evaluation generates normals. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11990 | @code{glMap2}. |
11991 | ||
11992 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
11993 | ||
11994 | ||
11995 | @var{params} returns a single boolean value indicating whether 2D | |
f37e7e3d DH |
11996 | evaluation generates 1D texture coordinates. The initial value is |
11997 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
11998 | |
11999 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
12000 | ||
12001 | ||
12002 | @var{params} returns a single boolean value indicating whether 2D | |
f37e7e3d DH |
12003 | evaluation generates 2D texture coordinates. The initial value is |
12004 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
12005 | |
12006 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
12007 | ||
12008 | ||
12009 | @var{params} returns a single boolean value indicating whether 2D | |
f37e7e3d DH |
12010 | evaluation generates 3D texture coordinates. The initial value is |
12011 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
12012 | |
12013 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
12014 | ||
12015 | ||
12016 | @var{params} returns a single boolean value indicating whether 2D | |
f37e7e3d DH |
12017 | evaluation generates 4D texture coordinates. The initial value is |
12018 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
12019 | |
12020 | @item @code{GL_MAP2_VERTEX_3} | |
12021 | ||
12022 | ||
12023 | @var{params} returns a single boolean value indicating whether 2D | |
f37e7e3d DH |
12024 | evaluation generates 3D vertex coordinates. The initial value is |
12025 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
12026 | |
12027 | @item @code{GL_MAP2_VERTEX_4} | |
12028 | ||
12029 | ||
12030 | @var{params} returns a single boolean value indicating whether 2D | |
f37e7e3d DH |
12031 | evaluation generates 4D vertex coordinates. The initial value is |
12032 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
12033 | |
12034 | @item @code{GL_MAP_COLOR} | |
12035 | ||
12036 | ||
12037 | @var{params} returns a single boolean value indicating if colors and | |
12038 | color indices are to be replaced by table lookup during pixel transfers. | |
f37e7e3d | 12039 | The initial value is @code{GL_FALSE}. See @code{glPixelTransfer}. |
b002944d AW |
12040 | |
12041 | @item @code{GL_MAP_STENCIL} | |
12042 | ||
12043 | ||
12044 | @var{params} returns a single boolean value indicating if stencil | |
f37e7e3d DH |
12045 | indices are to be replaced by table lookup during pixel transfers. The |
12046 | initial value is @code{GL_FALSE}. See @code{glPixelTransfer}. | |
b002944d AW |
12047 | |
12048 | @item @code{GL_MATRIX_MODE} | |
12049 | ||
12050 | ||
12051 | @var{params} returns one value, a symbolic constant indicating which | |
f37e7e3d DH |
12052 | matrix stack is currently the target of all matrix operations. The |
12053 | initial value is @code{GL_MODELVIEW}. See @code{glMatrixMode}. | |
b002944d AW |
12054 | |
12055 | @item @code{GL_MAX_3D_TEXTURE_SIZE} | |
12056 | ||
12057 | ||
12058 | @var{params} returns one value, a rough estimate of the largest 3D | |
f37e7e3d DH |
12059 | texture that the GL can handle. The value must be at least 16. If the GL |
12060 | version is 1.2 or greater, use @code{GL_PROXY_TEXTURE_3D} to determine | |
12061 | if a texture is too large. See @code{glTexImage3D}. | |
b002944d AW |
12062 | |
12063 | @item @code{GL_MAX_CLIENT_ATTRIB_STACK_DEPTH} | |
12064 | ||
12065 | ||
12066 | @var{params} returns one value indicating the maximum supported depth of | |
f37e7e3d | 12067 | the client attribute stack. See @code{glPushClientAttrib}. |
b002944d AW |
12068 | |
12069 | @item @code{GL_MAX_ATTRIB_STACK_DEPTH} | |
12070 | ||
12071 | ||
12072 | @var{params} returns one value, the maximum supported depth of the | |
f37e7e3d | 12073 | attribute stack. The value must be at least 16. See @code{glPushAttrib}. |
b002944d AW |
12074 | |
12075 | @item @code{GL_MAX_CLIP_PLANES} | |
12076 | ||
12077 | ||
12078 | @var{params} returns one value, the maximum number of | |
f37e7e3d | 12079 | application-defined clipping planes. The value must be at least 6. See |
b002944d AW |
12080 | @code{glClipPlane}. |
12081 | ||
12082 | @item @code{GL_MAX_COLOR_MATRIX_STACK_DEPTH} | |
12083 | ||
12084 | ||
12085 | @var{params} returns one value, the maximum supported depth of the color | |
f37e7e3d | 12086 | matrix stack. The value must be at least 2. See @code{glPushMatrix}. |
b002944d AW |
12087 | |
12088 | @item @code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS} | |
12089 | ||
12090 | ||
12091 | @var{params} returns one value, the maximum supported texture image | |
12092 | units that can be used to access texture maps from the vertex shader and | |
f37e7e3d | 12093 | the fragment processor combined. If both the vertex shader and the |
b002944d | 12094 | fragment processing stage access the same texture image unit, then that |
f37e7e3d DH |
12095 | counts as using two texture image units against this limit. The value |
12096 | must be at least 2. See @code{glActiveTexture}. | |
b002944d AW |
12097 | |
12098 | @item @code{GL_MAX_CUBE_MAP_TEXTURE_SIZE} | |
12099 | ||
12100 | ||
f37e7e3d DH |
12101 | @var{params} returns one value. The value gives a rough estimate of the |
12102 | largest cube-map texture that the GL can handle. The value must be at | |
12103 | least 16. If the GL version is 1.3 or greater, use | |
b002944d AW |
12104 | @code{GL_PROXY_TEXTURE_CUBE_MAP} to determine if a texture is too large. |
12105 | See @code{glTexImage2D}. | |
12106 | ||
12107 | @item @code{GL_MAX_DRAW_BUFFERS} | |
12108 | ||
12109 | ||
12110 | @var{params} returns one value, the maximum number of simultaneous | |
12111 | output colors allowed from a fragment shader using the | |
f37e7e3d | 12112 | @code{gl_FragData} built-in array. The value must be at least 1. See |
b002944d AW |
12113 | @code{glDrawBuffers}. |
12114 | ||
12115 | @item @code{GL_MAX_ELEMENTS_INDICES} | |
12116 | ||
12117 | ||
12118 | @var{params} returns one value, the recommended maximum number of vertex | |
f37e7e3d | 12119 | array indices. See @code{glDrawRangeElements}. |
b002944d AW |
12120 | |
12121 | @item @code{GL_MAX_ELEMENTS_VERTICES} | |
12122 | ||
12123 | ||
12124 | @var{params} returns one value, the recommended maximum number of vertex | |
f37e7e3d | 12125 | array vertices. See @code{glDrawRangeElements}. |
b002944d AW |
12126 | |
12127 | @item @code{GL_MAX_EVAL_ORDER} | |
12128 | ||
12129 | ||
12130 | @var{params} returns one value, the maximum equation order supported by | |
f37e7e3d | 12131 | 1D and 2D evaluators. The value must be at least 8. See @code{glMap1} |
b002944d AW |
12132 | and @code{glMap2}. |
12133 | ||
12134 | @item @code{GL_MAX_FRAGMENT_UNIFORM_COMPONENTS} | |
12135 | ||
12136 | ||
12137 | @var{params} returns one value, the maximum number of individual | |
12138 | floating-point, integer, or boolean values that can be held in uniform | |
f37e7e3d | 12139 | variable storage for a fragment shader. The value must be at least 64. |
b002944d AW |
12140 | See @code{glUniform}. |
12141 | ||
12142 | @item @code{GL_MAX_LIGHTS} | |
12143 | ||
12144 | ||
f37e7e3d DH |
12145 | @var{params} returns one value, the maximum number of lights. The value |
12146 | must be at least 8. See @code{glLight}. | |
b002944d AW |
12147 | |
12148 | @item @code{GL_MAX_LIST_NESTING} | |
12149 | ||
12150 | ||
12151 | @var{params} returns one value, the maximum recursion depth allowed | |
f37e7e3d | 12152 | during display-list traversal. The value must be at least 64. See |
b002944d AW |
12153 | @code{glCallList}. |
12154 | ||
12155 | @item @code{GL_MAX_MODELVIEW_STACK_DEPTH} | |
12156 | ||
12157 | ||
12158 | @var{params} returns one value, the maximum supported depth of the | |
f37e7e3d | 12159 | modelview matrix stack. The value must be at least 32. See |
b002944d AW |
12160 | @code{glPushMatrix}. |
12161 | ||
12162 | @item @code{GL_MAX_NAME_STACK_DEPTH} | |
12163 | ||
12164 | ||
12165 | @var{params} returns one value, the maximum supported depth of the | |
f37e7e3d | 12166 | selection name stack. The value must be at least 64. See |
b002944d AW |
12167 | @code{glPushName}. |
12168 | ||
12169 | @item @code{GL_MAX_PIXEL_MAP_TABLE} | |
12170 | ||
12171 | ||
12172 | @var{params} returns one value, the maximum supported size of a | |
f37e7e3d | 12173 | @code{glPixelMap} lookup table. The value must be at least 32. See |
b002944d AW |
12174 | @code{glPixelMap}. |
12175 | ||
12176 | @item @code{GL_MAX_PROJECTION_STACK_DEPTH} | |
12177 | ||
12178 | ||
12179 | @var{params} returns one value, the maximum supported depth of the | |
f37e7e3d | 12180 | projection matrix stack. The value must be at least 2. See |
b002944d AW |
12181 | @code{glPushMatrix}. |
12182 | ||
12183 | @item @code{GL_MAX_TEXTURE_COORDS} | |
12184 | ||
12185 | ||
12186 | @var{params} returns one value, the maximum number of texture coordinate | |
f37e7e3d DH |
12187 | sets available to vertex and fragment shaders. The value must be at |
12188 | least 2. See @code{glActiveTexture} and @code{glClientActiveTexture}. | |
b002944d AW |
12189 | |
12190 | @item @code{GL_MAX_TEXTURE_IMAGE_UNITS} | |
12191 | ||
12192 | ||
12193 | @var{params} returns one value, the maximum supported texture image | |
12194 | units that can be used to access texture maps from the fragment shader. | |
f37e7e3d | 12195 | The value must be at least 2. See @code{glActiveTexture}. |
b002944d AW |
12196 | |
12197 | @item @code{GL_MAX_TEXTURE_LOD_BIAS} | |
12198 | ||
12199 | ||
12200 | @var{params} returns one value, the maximum, absolute value of the | |
f37e7e3d | 12201 | texture level-of-detail bias. The value must be at least 4. |
b002944d AW |
12202 | |
12203 | @item @code{GL_MAX_TEXTURE_SIZE} | |
12204 | ||
12205 | ||
f37e7e3d DH |
12206 | @var{params} returns one value. The value gives a rough estimate of the |
12207 | largest texture that the GL can handle. The value must be at least 64. | |
b002944d | 12208 | If the GL version is 1.1 or greater, use @code{GL_PROXY_TEXTURE_1D} or |
f37e7e3d | 12209 | @code{GL_PROXY_TEXTURE_2D} to determine if a texture is too large. See |
b002944d AW |
12210 | @code{glTexImage1D} and @code{glTexImage2D}. |
12211 | ||
12212 | @item @code{GL_MAX_TEXTURE_STACK_DEPTH} | |
12213 | ||
12214 | ||
12215 | @var{params} returns one value, the maximum supported depth of the | |
f37e7e3d | 12216 | texture matrix stack. The value must be at least 2. See |
b002944d AW |
12217 | @code{glPushMatrix}. |
12218 | ||
12219 | @item @code{GL_MAX_TEXTURE_UNITS} | |
12220 | ||
12221 | ||
12222 | @var{params} returns a single value indicating the number of | |
f37e7e3d | 12223 | conventional texture units supported. Each conventional texture unit |
b002944d AW |
12224 | includes both a texture coordinate set and a texture image unit. |
12225 | Conventional texture units may be used for fixed-function (non-shader) | |
f37e7e3d | 12226 | rendering. The value must be at least 2. Additional texture coordinate |
b002944d | 12227 | sets and texture image units may be accessed from vertex and fragment |
f37e7e3d | 12228 | shaders. See @code{glActiveTexture} and @code{glClientActiveTexture}. |
b002944d AW |
12229 | |
12230 | @item @code{GL_MAX_VARYING_FLOATS} | |
12231 | ||
12232 | ||
12233 | @var{params} returns one value, the maximum number of interpolators | |
12234 | available for processing varying variables used by vertex and fragment | |
f37e7e3d | 12235 | shaders. This value represents the number of individual floating-point |
b002944d | 12236 | values that can be interpolated; varying variables declared as vectors, |
f37e7e3d | 12237 | matrices, and arrays will all consume multiple interpolators. The value |
b002944d AW |
12238 | must be at least 32. |
12239 | ||
12240 | @item @code{GL_MAX_VERTEX_ATTRIBS} | |
12241 | ||
12242 | ||
12243 | @var{params} returns one value, the maximum number of 4-component | |
f37e7e3d DH |
12244 | generic vertex attributes accessible to a vertex shader. The value must |
12245 | be at least 16. See @code{glVertexAttrib}. | |
b002944d AW |
12246 | |
12247 | @item @code{GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS} | |
12248 | ||
12249 | ||
12250 | @var{params} returns one value, the maximum supported texture image | |
12251 | units that can be used to access texture maps from the vertex shader. | |
f37e7e3d | 12252 | The value may be 0. See @code{glActiveTexture}. |
b002944d AW |
12253 | |
12254 | @item @code{GL_MAX_VERTEX_UNIFORM_COMPONENTS} | |
12255 | ||
12256 | ||
12257 | @var{params} returns one value, the maximum number of individual | |
12258 | floating-point, integer, or boolean values that can be held in uniform | |
f37e7e3d | 12259 | variable storage for a vertex shader. The value must be at least 512. |
b002944d AW |
12260 | See @code{glUniform}. |
12261 | ||
12262 | @item @code{GL_MAX_VIEWPORT_DIMS} | |
12263 | ||
12264 | ||
12265 | @var{params} returns two values: the maximum supported width and height | |
f37e7e3d DH |
12266 | of the viewport. These must be at least as large as the visible |
12267 | dimensions of the display being rendered to. See @code{glViewport}. | |
b002944d AW |
12268 | |
12269 | @item @code{GL_MINMAX} | |
12270 | ||
12271 | ||
12272 | @var{params} returns a single boolean value indicating whether pixel | |
f37e7e3d | 12273 | minmax values are computed. The initial value is @code{GL_FALSE}. See |
b002944d AW |
12274 | @code{glMinmax}. |
12275 | ||
12276 | @item @code{GL_MODELVIEW_MATRIX} | |
12277 | ||
12278 | ||
12279 | @var{params} returns sixteen values: the modelview matrix on the top of | |
f37e7e3d DH |
12280 | the modelview matrix stack. Initially this matrix is the identity |
12281 | matrix. See @code{glPushMatrix}. | |
b002944d AW |
12282 | |
12283 | @item @code{GL_MODELVIEW_STACK_DEPTH} | |
12284 | ||
12285 | ||
12286 | @var{params} returns one value, the number of matrices on the modelview | |
f37e7e3d | 12287 | matrix stack. The initial value is 1. See @code{glPushMatrix}. |
b002944d AW |
12288 | |
12289 | @item @code{GL_NAME_STACK_DEPTH} | |
12290 | ||
12291 | ||
12292 | @var{params} returns one value, the number of names on the selection | |
f37e7e3d | 12293 | name stack. The initial value is 0. See @code{glPushName}. |
b002944d AW |
12294 | |
12295 | @item @code{GL_NORMAL_ARRAY} | |
12296 | ||
12297 | ||
12298 | @var{params} returns a single boolean value, indicating whether the | |
f37e7e3d | 12299 | normal array is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
12300 | @code{glNormalPointer}. |
12301 | ||
12302 | @item @code{GL_NORMAL_ARRAY_BUFFER_BINDING} | |
12303 | ||
12304 | ||
12305 | @var{params} returns a single value, the name of the buffer object | |
f37e7e3d | 12306 | associated with the normal array. This buffer object would have been |
b002944d | 12307 | bound to the target @code{GL_ARRAY_BUFFER} at the time of the most |
f37e7e3d DH |
12308 | recent call to @code{glNormalPointer}. If no buffer object was bound to |
12309 | this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
12310 | @code{glBindBuffer}. |
12311 | ||
12312 | @item @code{GL_NORMAL_ARRAY_STRIDE} | |
12313 | ||
12314 | ||
12315 | @var{params} returns one value, the byte offset between consecutive | |
f37e7e3d | 12316 | normals in the normal array. The initial value is 0. See |
b002944d AW |
12317 | @code{glNormalPointer}. |
12318 | ||
12319 | @item @code{GL_NORMAL_ARRAY_TYPE} | |
12320 | ||
12321 | ||
12322 | @var{params} returns one value, the data type of each coordinate in the | |
f37e7e3d | 12323 | normal array. The initial value is @code{GL_FLOAT}. See |
b002944d AW |
12324 | @code{glNormalPointer}. |
12325 | ||
12326 | @item @code{GL_NORMALIZE} | |
12327 | ||
12328 | ||
12329 | @var{params} returns a single boolean value indicating whether normals | |
12330 | are automatically scaled to unit length after they have been transformed | |
f37e7e3d | 12331 | to eye coordinates. The initial value is @code{GL_FALSE}. See |
b002944d AW |
12332 | @code{glNormal}. |
12333 | ||
12334 | @item @code{GL_NUM_COMPRESSED_TEXTURE_FORMATS} | |
12335 | ||
12336 | ||
12337 | @var{params} returns a single integer value indicating the number of | |
f37e7e3d | 12338 | available compressed texture formats. The minimum value is 0. See |
b002944d AW |
12339 | @code{glCompressedTexImage2D}. |
12340 | ||
12341 | @item @code{GL_PACK_ALIGNMENT} | |
12342 | ||
12343 | ||
12344 | @var{params} returns one value, the byte alignment used for writing | |
f37e7e3d | 12345 | pixel data to memory. The initial value is 4. See @code{glPixelStore}. |
b002944d AW |
12346 | |
12347 | @item @code{GL_PACK_IMAGE_HEIGHT} | |
12348 | ||
12349 | ||
12350 | @var{params} returns one value, the image height used for writing pixel | |
f37e7e3d | 12351 | data to memory. The initial value is 0. See @code{glPixelStore}. |
b002944d AW |
12352 | |
12353 | @item @code{GL_PACK_LSB_FIRST} | |
12354 | ||
12355 | ||
12356 | @var{params} returns a single boolean value indicating whether | |
12357 | single-bit pixels being written to memory are written first to the least | |
f37e7e3d DH |
12358 | significant bit of each unsigned byte. The initial value is |
12359 | @code{GL_FALSE}. See @code{glPixelStore}. | |
b002944d AW |
12360 | |
12361 | @item @code{GL_PACK_ROW_LENGTH} | |
12362 | ||
12363 | ||
12364 | @var{params} returns one value, the row length used for writing pixel | |
f37e7e3d | 12365 | data to memory. The initial value is 0. See @code{glPixelStore}. |
b002944d AW |
12366 | |
12367 | @item @code{GL_PACK_SKIP_IMAGES} | |
12368 | ||
12369 | ||
12370 | @var{params} returns one value, the number of pixel images skipped | |
f37e7e3d | 12371 | before the first pixel is written into memory. The initial value is 0. |
b002944d AW |
12372 | See @code{glPixelStore}. |
12373 | ||
12374 | @item @code{GL_PACK_SKIP_PIXELS} | |
12375 | ||
12376 | ||
12377 | @var{params} returns one value, the number of pixel locations skipped | |
f37e7e3d | 12378 | before the first pixel is written into memory. The initial value is 0. |
b002944d AW |
12379 | See @code{glPixelStore}. |
12380 | ||
12381 | @item @code{GL_PACK_SKIP_ROWS} | |
12382 | ||
12383 | ||
12384 | @var{params} returns one value, the number of rows of pixel locations | |
f37e7e3d DH |
12385 | skipped before the first pixel is written into memory. The initial value |
12386 | is 0. See @code{glPixelStore}. | |
b002944d AW |
12387 | |
12388 | @item @code{GL_PACK_SWAP_BYTES} | |
12389 | ||
12390 | ||
12391 | @var{params} returns a single boolean value indicating whether the bytes | |
12392 | of two-byte and four-byte pixel indices and components are swapped | |
f37e7e3d | 12393 | before being written to memory. The initial value is @code{GL_FALSE}. |
b002944d AW |
12394 | See @code{glPixelStore}. |
12395 | ||
12396 | @item @code{GL_PERSPECTIVE_CORRECTION_HINT} | |
12397 | ||
12398 | ||
12399 | @var{params} returns one value, a symbolic constant indicating the mode | |
f37e7e3d DH |
12400 | of the perspective correction hint. The initial value is |
12401 | @code{GL_DONT_CARE}. See @code{glHint}. | |
b002944d AW |
12402 | |
12403 | @item @code{GL_PIXEL_MAP_A_TO_A_SIZE} | |
12404 | ||
12405 | ||
12406 | @var{params} returns one value, the size of the alpha-to-alpha pixel | |
f37e7e3d | 12407 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12408 | |
12409 | @item @code{GL_PIXEL_MAP_B_TO_B_SIZE} | |
12410 | ||
12411 | ||
12412 | @var{params} returns one value, the size of the blue-to-blue pixel | |
f37e7e3d | 12413 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12414 | |
12415 | @item @code{GL_PIXEL_MAP_G_TO_G_SIZE} | |
12416 | ||
12417 | ||
12418 | @var{params} returns one value, the size of the green-to-green pixel | |
f37e7e3d | 12419 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12420 | |
12421 | @item @code{GL_PIXEL_MAP_I_TO_A_SIZE} | |
12422 | ||
12423 | ||
12424 | @var{params} returns one value, the size of the index-to-alpha pixel | |
f37e7e3d | 12425 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12426 | |
12427 | @item @code{GL_PIXEL_MAP_I_TO_B_SIZE} | |
12428 | ||
12429 | ||
12430 | @var{params} returns one value, the size of the index-to-blue pixel | |
f37e7e3d | 12431 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12432 | |
12433 | @item @code{GL_PIXEL_MAP_I_TO_G_SIZE} | |
12434 | ||
12435 | ||
12436 | @var{params} returns one value, the size of the index-to-green pixel | |
f37e7e3d | 12437 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12438 | |
12439 | @item @code{GL_PIXEL_MAP_I_TO_I_SIZE} | |
12440 | ||
12441 | ||
12442 | @var{params} returns one value, the size of the index-to-index pixel | |
f37e7e3d | 12443 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12444 | |
12445 | @item @code{GL_PIXEL_MAP_I_TO_R_SIZE} | |
12446 | ||
12447 | ||
12448 | @var{params} returns one value, the size of the index-to-red pixel | |
f37e7e3d | 12449 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12450 | |
12451 | @item @code{GL_PIXEL_MAP_R_TO_R_SIZE} | |
12452 | ||
12453 | ||
12454 | @var{params} returns one value, the size of the red-to-red pixel | |
f37e7e3d | 12455 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12456 | |
12457 | @item @code{GL_PIXEL_MAP_S_TO_S_SIZE} | |
12458 | ||
12459 | ||
12460 | @var{params} returns one value, the size of the stencil-to-stencil pixel | |
f37e7e3d | 12461 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12462 | |
12463 | @item @code{GL_PIXEL_PACK_BUFFER_BINDING} | |
12464 | ||
12465 | ||
12466 | @var{params} returns a single value, the name of the buffer object | |
f37e7e3d DH |
12467 | currently bound to the target @code{GL_PIXEL_PACK_BUFFER}. If no buffer |
12468 | object is bound to this target, 0 is returned. The initial value is 0. | |
b002944d AW |
12469 | See @code{glBindBuffer}. |
12470 | ||
12471 | @item @code{GL_PIXEL_UNPACK_BUFFER_BINDING} | |
12472 | ||
12473 | ||
12474 | @var{params} returns a single value, the name of the buffer object | |
f37e7e3d DH |
12475 | currently bound to the target @code{GL_PIXEL_UNPACK_BUFFER}. If no |
12476 | buffer object is bound to this target, 0 is returned. The initial value | |
12477 | is 0. See @code{glBindBuffer}. | |
b002944d AW |
12478 | |
12479 | @item @code{GL_POINT_DISTANCE_ATTENUATION} | |
12480 | ||
12481 | ||
12482 | @var{params} returns three values, the coefficients for computing the | |
f37e7e3d | 12483 | attenuation value for points. See @code{glPointParameter}. |
b002944d AW |
12484 | |
12485 | @item @code{GL_POINT_FADE_THRESHOLD_SIZE} | |
12486 | ||
12487 | ||
12488 | @var{params} returns one value, the point size threshold for determining | |
f37e7e3d | 12489 | the point size. See @code{glPointParameter}. |
b002944d AW |
12490 | |
12491 | @item @code{GL_POINT_SIZE} | |
12492 | ||
12493 | ||
12494 | @var{params} returns one value, the point size as specified by | |
f37e7e3d | 12495 | @code{glPointSize}. The initial value is 1. |
b002944d AW |
12496 | |
12497 | @item @code{GL_POINT_SIZE_GRANULARITY} | |
12498 | ||
12499 | ||
12500 | @var{params} returns one value, the size difference between adjacent | |
f37e7e3d | 12501 | supported sizes for antialiased points. See @code{glPointSize}. |
b002944d AW |
12502 | |
12503 | @item @code{GL_POINT_SIZE_MAX} | |
12504 | ||
12505 | ||
12506 | @var{params} returns one value, the upper bound for the attenuated point | |
f37e7e3d | 12507 | sizes. The initial value is 0.0. See @code{glPointParameter}. |
b002944d AW |
12508 | |
12509 | @item @code{GL_POINT_SIZE_MIN} | |
12510 | ||
12511 | ||
12512 | @var{params} returns one value, the lower bound for the attenuated point | |
f37e7e3d | 12513 | sizes. The initial value is 1.0. See @code{glPointParameter}. |
b002944d AW |
12514 | |
12515 | @item @code{GL_POINT_SIZE_RANGE} | |
12516 | ||
12517 | ||
12518 | @var{params} returns two values: the smallest and largest supported | |
f37e7e3d DH |
12519 | sizes for antialiased points. The smallest size must be at most 1, and |
12520 | the largest size must be at least 1. See @code{glPointSize}. | |
b002944d AW |
12521 | |
12522 | @item @code{GL_POINT_SMOOTH} | |
12523 | ||
12524 | ||
12525 | @var{params} returns a single boolean value indicating whether | |
f37e7e3d DH |
12526 | antialiasing of points is enabled. The initial value is @code{GL_FALSE}. |
12527 | See @code{glPointSize}. | |
b002944d AW |
12528 | |
12529 | @item @code{GL_POINT_SMOOTH_HINT} | |
12530 | ||
12531 | ||
12532 | @var{params} returns one value, a symbolic constant indicating the mode | |
f37e7e3d DH |
12533 | of the point antialiasing hint. The initial value is |
12534 | @code{GL_DONT_CARE}. See @code{glHint}. | |
b002944d AW |
12535 | |
12536 | @item @code{GL_POINT_SPRITE} | |
12537 | ||
12538 | ||
12539 | @var{params} returns a single boolean value indicating whether point | |
f37e7e3d | 12540 | sprite is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
12541 | |
12542 | @item @code{GL_POLYGON_MODE} | |
12543 | ||
12544 | ||
12545 | @var{params} returns two values: symbolic constants indicating whether | |
12546 | front-facing and back-facing polygons are rasterized as points, lines, | |
f37e7e3d | 12547 | or filled polygons. The initial value is @code{GL_FILL}. See |
b002944d AW |
12548 | @code{glPolygonMode}. |
12549 | ||
12550 | @item @code{GL_POLYGON_OFFSET_FACTOR} | |
12551 | ||
12552 | ||
12553 | @var{params} returns one value, the scaling factor used to determine the | |
12554 | variable offset that is added to the depth value of each fragment | |
f37e7e3d | 12555 | generated when a polygon is rasterized. The initial value is 0. See |
b002944d AW |
12556 | @code{glPolygonOffset}. |
12557 | ||
12558 | @item @code{GL_POLYGON_OFFSET_UNITS} | |
12559 | ||
12560 | ||
f37e7e3d | 12561 | @var{params} returns one value. This value is multiplied by an |
b002944d | 12562 | implementation-specific value and then added to the depth value of each |
f37e7e3d DH |
12563 | fragment generated when a polygon is rasterized. The initial value is 0. |
12564 | See @code{glPolygonOffset}. | |
b002944d AW |
12565 | |
12566 | @item @code{GL_POLYGON_OFFSET_FILL} | |
12567 | ||
12568 | ||
12569 | @var{params} returns a single boolean value indicating whether polygon | |
f37e7e3d DH |
12570 | offset is enabled for polygons in fill mode. The initial value is |
12571 | @code{GL_FALSE}. See @code{glPolygonOffset}. | |
b002944d AW |
12572 | |
12573 | @item @code{GL_POLYGON_OFFSET_LINE} | |
12574 | ||
12575 | ||
12576 | @var{params} returns a single boolean value indicating whether polygon | |
f37e7e3d DH |
12577 | offset is enabled for polygons in line mode. The initial value is |
12578 | @code{GL_FALSE}. See @code{glPolygonOffset}. | |
b002944d AW |
12579 | |
12580 | @item @code{GL_POLYGON_OFFSET_POINT} | |
12581 | ||
12582 | ||
12583 | @var{params} returns a single boolean value indicating whether polygon | |
f37e7e3d DH |
12584 | offset is enabled for polygons in point mode. The initial value is |
12585 | @code{GL_FALSE}. See @code{glPolygonOffset}. | |
b002944d AW |
12586 | |
12587 | @item @code{GL_POLYGON_SMOOTH} | |
12588 | ||
12589 | ||
12590 | @var{params} returns a single boolean value indicating whether | |
f37e7e3d DH |
12591 | antialiasing of polygons is enabled. The initial value is |
12592 | @code{GL_FALSE}. See @code{glPolygonMode}. | |
b002944d AW |
12593 | |
12594 | @item @code{GL_POLYGON_SMOOTH_HINT} | |
12595 | ||
12596 | ||
12597 | @var{params} returns one value, a symbolic constant indicating the mode | |
f37e7e3d DH |
12598 | of the polygon antialiasing hint. The initial value is |
12599 | @code{GL_DONT_CARE}. See @code{glHint}. | |
b002944d AW |
12600 | |
12601 | @item @code{GL_POLYGON_STIPPLE} | |
12602 | ||
12603 | ||
12604 | @var{params} returns a single boolean value indicating whether polygon | |
f37e7e3d | 12605 | stippling is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
12606 | @code{glPolygonStipple}. |
12607 | ||
12608 | @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} | |
12609 | ||
12610 | ||
12611 | @var{params} returns a single boolean value indicating whether post | |
f37e7e3d DH |
12612 | color matrix transformation lookup is enabled. The initial value is |
12613 | @code{GL_FALSE}. See @code{glColorTable}. | |
b002944d AW |
12614 | |
12615 | @item @code{GL_POST_COLOR_MATRIX_RED_BIAS} | |
12616 | ||
12617 | ||
12618 | @var{params} returns one value, the red bias factor applied to RGBA | |
f37e7e3d | 12619 | fragments after color matrix transformations. The initial value is 0. |
b002944d AW |
12620 | See @code{glPixelTransfer}. |
12621 | ||
12622 | @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS} | |
12623 | ||
12624 | ||
12625 | @var{params} returns one value, the green bias factor applied to RGBA | |
f37e7e3d | 12626 | fragments after color matrix transformations. The initial value is 0. |
b002944d AW |
12627 | See @code{glPixelTransfer} |
12628 | ||
12629 | @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS} | |
12630 | ||
12631 | ||
12632 | @var{params} returns one value, the blue bias factor applied to RGBA | |
f37e7e3d | 12633 | fragments after color matrix transformations. The initial value is 0. |
b002944d AW |
12634 | See @code{glPixelTransfer}. |
12635 | ||
12636 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS} | |
12637 | ||
12638 | ||
12639 | @var{params} returns one value, the alpha bias factor applied to RGBA | |
f37e7e3d | 12640 | fragments after color matrix transformations. The initial value is 0. |
b002944d AW |
12641 | See @code{glPixelTransfer}. |
12642 | ||
12643 | @item @code{GL_POST_COLOR_MATRIX_RED_SCALE} | |
12644 | ||
12645 | ||
12646 | @var{params} returns one value, the red scale factor applied to RGBA | |
f37e7e3d | 12647 | fragments after color matrix transformations. The initial value is 1. |
b002944d AW |
12648 | See @code{glPixelTransfer}. |
12649 | ||
12650 | @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE} | |
12651 | ||
12652 | ||
12653 | @var{params} returns one value, the green scale factor applied to RGBA | |
f37e7e3d | 12654 | fragments after color matrix transformations. The initial value is 1. |
b002944d AW |
12655 | See @code{glPixelTransfer}. |
12656 | ||
12657 | @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE} | |
12658 | ||
12659 | ||
12660 | @var{params} returns one value, the blue scale factor applied to RGBA | |
f37e7e3d | 12661 | fragments after color matrix transformations. The initial value is 1. |
b002944d AW |
12662 | See @code{glPixelTransfer}. |
12663 | ||
12664 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE} | |
12665 | ||
12666 | ||
12667 | @var{params} returns one value, the alpha scale factor applied to RGBA | |
f37e7e3d | 12668 | fragments after color matrix transformations. The initial value is 1. |
b002944d AW |
12669 | See @code{glPixelTransfer}. |
12670 | ||
12671 | @item @code{GL_POST_CONVOLUTION_COLOR_TABLE} | |
12672 | ||
12673 | ||
12674 | @var{params} returns a single boolean value indicating whether post | |
f37e7e3d DH |
12675 | convolution lookup is enabled. The initial value is @code{GL_FALSE}. See |
12676 | @code{glColorTable}. | |
b002944d AW |
12677 | |
12678 | @item @code{GL_POST_CONVOLUTION_RED_BIAS} | |
12679 | ||
12680 | ||
12681 | @var{params} returns one value, the red bias factor applied to RGBA | |
f37e7e3d | 12682 | fragments after convolution. The initial value is 0. See |
b002944d AW |
12683 | @code{glPixelTransfer}. |
12684 | ||
12685 | @item @code{GL_POST_CONVOLUTION_GREEN_BIAS} | |
12686 | ||
12687 | ||
12688 | @var{params} returns one value, the green bias factor applied to RGBA | |
f37e7e3d | 12689 | fragments after convolution. The initial value is 0. See |
b002944d AW |
12690 | @code{glPixelTransfer}. |
12691 | ||
12692 | @item @code{GL_POST_CONVOLUTION_BLUE_BIAS} | |
12693 | ||
12694 | ||
12695 | @var{params} returns one value, the blue bias factor applied to RGBA | |
f37e7e3d | 12696 | fragments after convolution. The initial value is 0. See |
b002944d AW |
12697 | @code{glPixelTransfer}. |
12698 | ||
12699 | @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS} | |
12700 | ||
12701 | ||
12702 | @var{params} returns one value, the alpha bias factor applied to RGBA | |
f37e7e3d | 12703 | fragments after convolution. The initial value is 0. See |
b002944d AW |
12704 | @code{glPixelTransfer}. |
12705 | ||
12706 | @item @code{GL_POST_CONVOLUTION_RED_SCALE} | |
12707 | ||
12708 | ||
12709 | @var{params} returns one value, the red scale factor applied to RGBA | |
f37e7e3d | 12710 | fragments after convolution. The initial value is 1. See |
b002944d AW |
12711 | @code{glPixelTransfer}. |
12712 | ||
12713 | @item @code{GL_POST_CONVOLUTION_GREEN_SCALE} | |
12714 | ||
12715 | ||
12716 | @var{params} returns one value, the green scale factor applied to RGBA | |
f37e7e3d | 12717 | fragments after convolution. The initial value is 1. See |
b002944d AW |
12718 | @code{glPixelTransfer}. |
12719 | ||
12720 | @item @code{GL_POST_CONVOLUTION_BLUE_SCALE} | |
12721 | ||
12722 | ||
12723 | @var{params} returns one value, the blue scale factor applied to RGBA | |
f37e7e3d | 12724 | fragments after convolution. The initial value is 1. See |
b002944d AW |
12725 | @code{glPixelTransfer}. |
12726 | ||
12727 | @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE} | |
12728 | ||
12729 | ||
12730 | @var{params} returns one value, the alpha scale factor applied to RGBA | |
f37e7e3d | 12731 | fragments after convolution. The initial value is 1. See |
b002944d AW |
12732 | @code{glPixelTransfer}. |
12733 | ||
12734 | @item @code{GL_PROJECTION_MATRIX} | |
12735 | ||
12736 | ||
12737 | @var{params} returns sixteen values: the projection matrix on the top of | |
f37e7e3d DH |
12738 | the projection matrix stack. Initially this matrix is the identity |
12739 | matrix. See @code{glPushMatrix}. | |
b002944d AW |
12740 | |
12741 | @item @code{GL_PROJECTION_STACK_DEPTH} | |
12742 | ||
12743 | ||
12744 | @var{params} returns one value, the number of matrices on the projection | |
f37e7e3d | 12745 | matrix stack. The initial value is 1. See @code{glPushMatrix}. |
b002944d AW |
12746 | |
12747 | @item @code{GL_READ_BUFFER} | |
12748 | ||
12749 | ||
12750 | @var{params} returns one value, a symbolic constant indicating which | |
f37e7e3d | 12751 | color buffer is selected for reading. The initial value is |
b002944d | 12752 | @code{GL_BACK} if there is a back buffer, otherwise it is |
f37e7e3d | 12753 | @code{GL_FRONT}. See @code{glReadPixels} and @code{glAccum}. |
b002944d AW |
12754 | |
12755 | @item @code{GL_RED_BIAS} | |
12756 | ||
12757 | ||
12758 | @var{params} returns one value, the red bias factor used during pixel | |
f37e7e3d | 12759 | transfers. The initial value is 0. |
b002944d AW |
12760 | |
12761 | @item @code{GL_RED_BITS} | |
12762 | ||
12763 | ||
12764 | @var{params} returns one value, the number of red bitplanes in each | |
12765 | color buffer. | |
12766 | ||
12767 | @item @code{GL_RED_SCALE} | |
12768 | ||
12769 | ||
12770 | @var{params} returns one value, the red scale factor used during pixel | |
f37e7e3d | 12771 | transfers. The initial value is 1. See @code{glPixelTransfer}. |
b002944d AW |
12772 | |
12773 | @item @code{GL_RENDER_MODE} | |
12774 | ||
12775 | ||
12776 | @var{params} returns one value, a symbolic constant indicating whether | |
f37e7e3d DH |
12777 | the GL is in render, select, or feedback mode. The initial value is |
12778 | @code{GL_RENDER}. See @code{glRenderMode}. | |
b002944d AW |
12779 | |
12780 | @item @code{GL_RESCALE_NORMAL} | |
12781 | ||
12782 | ||
12783 | @var{params} returns single boolean value indicating whether normal | |
f37e7e3d | 12784 | rescaling is enabled. See @code{glEnable}. |
b002944d AW |
12785 | |
12786 | @item @code{GL_RGBA_MODE} | |
12787 | ||
12788 | ||
12789 | @var{params} returns a single boolean value indicating whether the GL is | |
f37e7e3d | 12790 | in RGBA mode (true) or color index mode (false). See @code{glColor}. |
b002944d AW |
12791 | |
12792 | @item @code{GL_SAMPLE_BUFFERS} | |
12793 | ||
12794 | ||
12795 | @var{params} returns a single integer value indicating the number of | |
f37e7e3d | 12796 | sample buffers associated with the framebuffer. See |
b002944d AW |
12797 | @code{glSampleCoverage}. |
12798 | ||
12799 | @item @code{GL_SAMPLE_COVERAGE_VALUE} | |
12800 | ||
12801 | ||
12802 | @var{params} returns a single positive floating-point value indicating | |
f37e7e3d | 12803 | the current sample coverage value. See @code{glSampleCoverage}. |
b002944d AW |
12804 | |
12805 | @item @code{GL_SAMPLE_COVERAGE_INVERT} | |
12806 | ||
12807 | ||
12808 | @var{params} returns a single boolean value indicating if the temporary | |
f37e7e3d | 12809 | coverage value should be inverted. See @code{glSampleCoverage}. |
b002944d AW |
12810 | |
12811 | @item @code{GL_SAMPLES} | |
12812 | ||
12813 | ||
12814 | @var{params} returns a single integer value indicating the coverage mask | |
f37e7e3d | 12815 | size. See @code{glSampleCoverage}. |
b002944d AW |
12816 | |
12817 | @item @code{GL_SCISSOR_BOX} | |
12818 | ||
12819 | ||
12820 | @var{params} returns four values: the @r{@var{x}} and @r{@var{y}} window | |
12821 | coordinates of the scissor box, followed by its width and height. | |
12822 | Initially the @r{@var{x}} and @r{@var{y}} window coordinates are both 0 | |
f37e7e3d | 12823 | and the width and height are set to the size of the window. See |
b002944d AW |
12824 | @code{glScissor}. |
12825 | ||
12826 | @item @code{GL_SCISSOR_TEST} | |
12827 | ||
12828 | ||
12829 | @var{params} returns a single boolean value indicating whether | |
f37e7e3d | 12830 | scissoring is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
12831 | @code{glScissor}. |
12832 | ||
12833 | @item @code{GL_SECONDARY_COLOR_ARRAY} | |
12834 | ||
12835 | ||
12836 | @var{params} returns a single boolean value indicating whether the | |
f37e7e3d | 12837 | secondary color array is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
12838 | See @code{glSecondaryColorPointer}. |
12839 | ||
12840 | @item @code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING} | |
12841 | ||
12842 | ||
12843 | @var{params} returns a single value, the name of the buffer object | |
f37e7e3d DH |
12844 | associated with the secondary color array. This buffer object would have |
12845 | been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most | |
12846 | recent call to @code{glSecondaryColorPointer}. If no buffer object was | |
12847 | bound to this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
12848 | @code{glBindBuffer}. |
12849 | ||
12850 | @item @code{GL_SECONDARY_COLOR_ARRAY_SIZE} | |
12851 | ||
12852 | ||
12853 | @var{params} returns one value, the number of components per color in | |
f37e7e3d | 12854 | the secondary color array. The initial value is 3. See |
b002944d AW |
12855 | @code{glSecondaryColorPointer}. |
12856 | ||
12857 | @item @code{GL_SECONDARY_COLOR_ARRAY_STRIDE} | |
12858 | ||
12859 | ||
12860 | @var{params} returns one value, the byte offset between consecutive | |
f37e7e3d | 12861 | colors in the secondary color array. The initial value is 0. See |
b002944d AW |
12862 | @code{glSecondaryColorPointer}. |
12863 | ||
12864 | @item @code{GL_SECONDARY_COLOR_ARRAY_TYPE} | |
12865 | ||
12866 | ||
12867 | @var{params} returns one value, the data type of each component in the | |
f37e7e3d | 12868 | secondary color array. The initial value is @code{GL_FLOAT}. See |
b002944d AW |
12869 | @code{glSecondaryColorPointer}. |
12870 | ||
12871 | @item @code{GL_SELECTION_BUFFER_SIZE} | |
12872 | ||
12873 | ||
f37e7e3d | 12874 | @var{params} return one value, the size of the selection buffer. See |
b002944d AW |
12875 | @code{glSelectBuffer}. |
12876 | ||
12877 | @item @code{GL_SEPARABLE_2D} | |
12878 | ||
12879 | ||
12880 | @var{params} returns a single boolean value indicating whether 2D | |
f37e7e3d | 12881 | separable convolution is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
12882 | See @code{glSeparableFilter2D}. |
12883 | ||
12884 | @item @code{GL_SHADE_MODEL} | |
12885 | ||
12886 | ||
12887 | @var{params} returns one value, a symbolic constant indicating whether | |
f37e7e3d DH |
12888 | the shading mode is flat or smooth. The initial value is |
12889 | @code{GL_SMOOTH}. See @code{glShadeModel}. | |
b002944d AW |
12890 | |
12891 | @item @code{GL_SMOOTH_LINE_WIDTH_RANGE} | |
12892 | ||
12893 | ||
12894 | @var{params} returns two values, the smallest and largest supported | |
f37e7e3d | 12895 | widths for antialiased lines. See @code{glLineWidth}. |
b002944d AW |
12896 | |
12897 | @item @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY} | |
12898 | ||
12899 | ||
12900 | @var{params} returns one value, the granularity of widths for | |
f37e7e3d | 12901 | antialiased lines. See @code{glLineWidth}. |
b002944d AW |
12902 | |
12903 | @item @code{GL_SMOOTH_POINT_SIZE_RANGE} | |
12904 | ||
12905 | ||
12906 | @var{params} returns two values, the smallest and largest supported | |
f37e7e3d | 12907 | widths for antialiased points. See @code{glPointSize}. |
b002944d AW |
12908 | |
12909 | @item @code{GL_SMOOTH_POINT_SIZE_GRANULARITY} | |
12910 | ||
12911 | ||
12912 | @var{params} returns one value, the granularity of sizes for antialiased | |
f37e7e3d | 12913 | points. See @code{glPointSize}. |
b002944d AW |
12914 | |
12915 | @item @code{GL_STENCIL_BACK_FAIL} | |
12916 | ||
12917 | ||
12918 | @var{params} returns one value, a symbolic constant indicating what | |
12919 | action is taken for back-facing polygons when the stencil test fails. | |
f37e7e3d | 12920 | The initial value is @code{GL_KEEP}. See @code{glStencilOpSeparate}. |
b002944d AW |
12921 | |
12922 | @item @code{GL_STENCIL_BACK_FUNC} | |
12923 | ||
12924 | ||
12925 | @var{params} returns one value, a symbolic constant indicating what | |
12926 | function is used for back-facing polygons to compare the stencil | |
f37e7e3d DH |
12927 | reference value with the stencil buffer value. The initial value is |
12928 | @code{GL_ALWAYS}. See @code{glStencilFuncSeparate}. | |
b002944d AW |
12929 | |
12930 | @item @code{GL_STENCIL_BACK_PASS_DEPTH_FAIL} | |
12931 | ||
12932 | ||
12933 | @var{params} returns one value, a symbolic constant indicating what | |
12934 | action is taken for back-facing polygons when the stencil test passes, | |
f37e7e3d | 12935 | but the depth test fails. The initial value is @code{GL_KEEP}. See |
b002944d AW |
12936 | @code{glStencilOpSeparate}. |
12937 | ||
12938 | @item @code{GL_STENCIL_BACK_PASS_DEPTH_PASS} | |
12939 | ||
12940 | ||
12941 | @var{params} returns one value, a symbolic constant indicating what | |
12942 | action is taken for back-facing polygons when the stencil test passes | |
f37e7e3d | 12943 | and the depth test passes. The initial value is @code{GL_KEEP}. See |
b002944d AW |
12944 | @code{glStencilOpSeparate}. |
12945 | ||
12946 | @item @code{GL_STENCIL_BACK_REF} | |
12947 | ||
12948 | ||
12949 | @var{params} returns one value, the reference value that is compared | |
f37e7e3d DH |
12950 | with the contents of the stencil buffer for back-facing polygons. The |
12951 | initial value is 0. See @code{glStencilFuncSeparate}. | |
b002944d AW |
12952 | |
12953 | @item @code{GL_STENCIL_BACK_VALUE_MASK} | |
12954 | ||
12955 | ||
12956 | @var{params} returns one value, the mask that is used for back-facing | |
12957 | polygons to mask both the stencil reference value and the stencil buffer | |
f37e7e3d | 12958 | value before they are compared. The initial value is all 1's. See |
b002944d AW |
12959 | @code{glStencilFuncSeparate}. |
12960 | ||
12961 | @item @code{GL_STENCIL_BACK_WRITEMASK} | |
12962 | ||
12963 | ||
12964 | @var{params} returns one value, the mask that controls writing of the | |
f37e7e3d DH |
12965 | stencil bitplanes for back-facing polygons. The initial value is all |
12966 | 1's. See @code{glStencilMaskSeparate}. | |
b002944d AW |
12967 | |
12968 | @item @code{GL_STENCIL_BITS} | |
12969 | ||
12970 | ||
12971 | @var{params} returns one value, the number of bitplanes in the stencil | |
12972 | buffer. | |
12973 | ||
12974 | @item @code{GL_STENCIL_CLEAR_VALUE} | |
12975 | ||
12976 | ||
12977 | @var{params} returns one value, the index to which the stencil bitplanes | |
f37e7e3d | 12978 | are cleared. The initial value is 0. See @code{glClearStencil}. |
b002944d AW |
12979 | |
12980 | @item @code{GL_STENCIL_FAIL} | |
12981 | ||
12982 | ||
12983 | @var{params} returns one value, a symbolic constant indicating what | |
f37e7e3d DH |
12984 | action is taken when the stencil test fails. The initial value is |
12985 | @code{GL_KEEP}. See @code{glStencilOp}. If the GL version is 2.0 or | |
b002944d | 12986 | greater, this stencil state only affects non-polygons and front-facing |
f37e7e3d | 12987 | polygons. Back-facing polygons use separate stencil state. See |
b002944d AW |
12988 | @code{glStencilOpSeparate}. |
12989 | ||
12990 | @item @code{GL_STENCIL_FUNC} | |
12991 | ||
12992 | ||
12993 | @var{params} returns one value, a symbolic constant indicating what | |
12994 | function is used to compare the stencil reference value with the stencil | |
f37e7e3d DH |
12995 | buffer value. The initial value is @code{GL_ALWAYS}. See |
12996 | @code{glStencilFunc}. If the GL version is 2.0 or greater, this stencil | |
12997 | state only affects non-polygons and front-facing polygons. Back-facing | |
12998 | polygons use separate stencil state. See @code{glStencilFuncSeparate}. | |
b002944d AW |
12999 | |
13000 | @item @code{GL_STENCIL_PASS_DEPTH_FAIL} | |
13001 | ||
13002 | ||
13003 | @var{params} returns one value, a symbolic constant indicating what | |
13004 | action is taken when the stencil test passes, but the depth test fails. | |
f37e7e3d | 13005 | The initial value is @code{GL_KEEP}. See @code{glStencilOp}. If the GL |
b002944d | 13006 | version is 2.0 or greater, this stencil state only affects non-polygons |
f37e7e3d DH |
13007 | and front-facing polygons. Back-facing polygons use separate stencil |
13008 | state. See @code{glStencilOpSeparate}. | |
b002944d AW |
13009 | |
13010 | @item @code{GL_STENCIL_PASS_DEPTH_PASS} | |
13011 | ||
13012 | ||
13013 | @var{params} returns one value, a symbolic constant indicating what | |
13014 | action is taken when the stencil test passes and the depth test passes. | |
f37e7e3d | 13015 | The initial value is @code{GL_KEEP}. See @code{glStencilOp}. If the GL |
b002944d | 13016 | version is 2.0 or greater, this stencil state only affects non-polygons |
f37e7e3d DH |
13017 | and front-facing polygons. Back-facing polygons use separate stencil |
13018 | state. See @code{glStencilOpSeparate}. | |
b002944d AW |
13019 | |
13020 | @item @code{GL_STENCIL_REF} | |
13021 | ||
13022 | ||
13023 | @var{params} returns one value, the reference value that is compared | |
f37e7e3d DH |
13024 | with the contents of the stencil buffer. The initial value is 0. See |
13025 | @code{glStencilFunc}. If the GL version is 2.0 or greater, this stencil | |
13026 | state only affects non-polygons and front-facing polygons. Back-facing | |
13027 | polygons use separate stencil state. See @code{glStencilFuncSeparate}. | |
b002944d AW |
13028 | |
13029 | @item @code{GL_STENCIL_TEST} | |
13030 | ||
13031 | ||
13032 | @var{params} returns a single boolean value indicating whether stencil | |
f37e7e3d | 13033 | testing of fragments is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
13034 | See @code{glStencilFunc} and @code{glStencilOp}. |
13035 | ||
13036 | @item @code{GL_STENCIL_VALUE_MASK} | |
13037 | ||
13038 | ||
13039 | @var{params} returns one value, the mask that is used to mask both the | |
13040 | stencil reference value and the stencil buffer value before they are | |
f37e7e3d DH |
13041 | compared. The initial value is all 1's. See @code{glStencilFunc}. If the |
13042 | GL version is 2.0 or greater, this stencil state only affects | |
13043 | non-polygons and front-facing polygons. Back-facing polygons use | |
13044 | separate stencil state. See @code{glStencilFuncSeparate}. | |
b002944d AW |
13045 | |
13046 | @item @code{GL_STENCIL_WRITEMASK} | |
13047 | ||
13048 | ||
13049 | @var{params} returns one value, the mask that controls writing of the | |
f37e7e3d DH |
13050 | stencil bitplanes. The initial value is all 1's. See |
13051 | @code{glStencilMask}. If the GL version is 2.0 or greater, this stencil | |
13052 | state only affects non-polygons and front-facing polygons. Back-facing | |
13053 | polygons use separate stencil state. See @code{glStencilMaskSeparate}. | |
b002944d AW |
13054 | |
13055 | @item @code{GL_STEREO} | |
13056 | ||
13057 | ||
13058 | @var{params} returns a single boolean value indicating whether stereo | |
13059 | buffers (left and right) are supported. | |
13060 | ||
13061 | @item @code{GL_SUBPIXEL_BITS} | |
13062 | ||
13063 | ||
13064 | @var{params} returns one value, an estimate of the number of bits of | |
13065 | subpixel resolution that are used to position rasterized geometry in | |
f37e7e3d | 13066 | window coordinates. The value must be at least 4. |
b002944d AW |
13067 | |
13068 | @item @code{GL_TEXTURE_1D} | |
13069 | ||
13070 | ||
13071 | @var{params} returns a single boolean value indicating whether 1D | |
f37e7e3d | 13072 | texture mapping is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
13073 | @code{glTexImage1D}. |
13074 | ||
13075 | @item @code{GL_TEXTURE_BINDING_1D} | |
13076 | ||
13077 | ||
13078 | @var{params} returns a single value, the name of the texture currently | |
f37e7e3d | 13079 | bound to the target @code{GL_TEXTURE_1D}. The initial value is 0. See |
b002944d AW |
13080 | @code{glBindTexture}. |
13081 | ||
13082 | @item @code{GL_TEXTURE_2D} | |
13083 | ||
13084 | ||
13085 | @var{params} returns a single boolean value indicating whether 2D | |
f37e7e3d | 13086 | texture mapping is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
13087 | @code{glTexImage2D}. |
13088 | ||
13089 | @item @code{GL_TEXTURE_BINDING_2D} | |
13090 | ||
13091 | ||
13092 | @var{params} returns a single value, the name of the texture currently | |
f37e7e3d | 13093 | bound to the target @code{GL_TEXTURE_2D}. The initial value is 0. See |
b002944d AW |
13094 | @code{glBindTexture}. |
13095 | ||
13096 | @item @code{GL_TEXTURE_3D} | |
13097 | ||
13098 | ||
13099 | @var{params} returns a single boolean value indicating whether 3D | |
f37e7e3d | 13100 | texture mapping is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
13101 | @code{glTexImage3D}. |
13102 | ||
13103 | @item @code{GL_TEXTURE_BINDING_3D} | |
13104 | ||
13105 | ||
13106 | @var{params} returns a single value, the name of the texture currently | |
f37e7e3d | 13107 | bound to the target @code{GL_TEXTURE_3D}. The initial value is 0. See |
b002944d AW |
13108 | @code{glBindTexture}. |
13109 | ||
13110 | @item @code{GL_TEXTURE_BINDING_CUBE_MAP} | |
13111 | ||
13112 | ||
13113 | @var{params} returns a single value, the name of the texture currently | |
f37e7e3d | 13114 | bound to the target @code{GL_TEXTURE_CUBE_MAP}. The initial value is 0. |
b002944d AW |
13115 | See @code{glBindTexture}. |
13116 | ||
13117 | @item @code{GL_TEXTURE_COMPRESSION_HINT} | |
13118 | ||
13119 | ||
13120 | @var{params} returns a single value indicating the mode of the texture | |
f37e7e3d | 13121 | compression hint. The initial value is @code{GL_DONT_CARE}. |
b002944d AW |
13122 | |
13123 | @item @code{GL_TEXTURE_COORD_ARRAY} | |
13124 | ||
13125 | ||
13126 | @var{params} returns a single boolean value indicating whether the | |
f37e7e3d DH |
13127 | texture coordinate array is enabled. The initial value is |
13128 | @code{GL_FALSE}. See @code{glTexCoordPointer}. | |
b002944d AW |
13129 | |
13130 | @item @code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING} | |
13131 | ||
13132 | ||
13133 | @var{params} returns a single value, the name of the buffer object | |
f37e7e3d | 13134 | associated with the texture coordinate array. This buffer object would |
b002944d | 13135 | have been bound to the target @code{GL_ARRAY_BUFFER} at the time of the |
f37e7e3d DH |
13136 | most recent call to @code{glTexCoordPointer}. If no buffer object was |
13137 | bound to this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
13138 | @code{glBindBuffer}. |
13139 | ||
13140 | @item @code{GL_TEXTURE_COORD_ARRAY_SIZE} | |
13141 | ||
13142 | ||
13143 | @var{params} returns one value, the number of coordinates per element in | |
f37e7e3d | 13144 | the texture coordinate array. The initial value is 4. See |
b002944d AW |
13145 | @code{glTexCoordPointer}. |
13146 | ||
13147 | @item @code{GL_TEXTURE_COORD_ARRAY_STRIDE} | |
13148 | ||
13149 | ||
13150 | @var{params} returns one value, the byte offset between consecutive | |
f37e7e3d | 13151 | elements in the texture coordinate array. The initial value is 0. See |
b002944d AW |
13152 | @code{glTexCoordPointer}. |
13153 | ||
13154 | @item @code{GL_TEXTURE_COORD_ARRAY_TYPE} | |
13155 | ||
13156 | ||
13157 | @var{params} returns one value, the data type of the coordinates in the | |
f37e7e3d | 13158 | texture coordinate array. The initial value is @code{GL_FLOAT}. See |
b002944d AW |
13159 | @code{glTexCoordPointer}. |
13160 | ||
13161 | @item @code{GL_TEXTURE_CUBE_MAP} | |
13162 | ||
13163 | ||
13164 | @var{params} returns a single boolean value indicating whether | |
f37e7e3d DH |
13165 | cube-mapped texture mapping is enabled. The initial value is |
13166 | @code{GL_FALSE}. See @code{glTexImage2D}. | |
b002944d AW |
13167 | |
13168 | @item @code{GL_TEXTURE_GEN_Q} | |
13169 | ||
13170 | ||
13171 | @var{params} returns a single boolean value indicating whether automatic | |
f37e7e3d DH |
13172 | generation of the @var{q} texture coordinate is enabled. The initial |
13173 | value is @code{GL_FALSE}. See @code{glTexGen}. | |
b002944d AW |
13174 | |
13175 | @item @code{GL_TEXTURE_GEN_R} | |
13176 | ||
13177 | ||
13178 | @var{params} returns a single boolean value indicating whether automatic | |
f37e7e3d DH |
13179 | generation of the @var{r} texture coordinate is enabled. The initial |
13180 | value is @code{GL_FALSE}. See @code{glTexGen}. | |
b002944d AW |
13181 | |
13182 | @item @code{GL_TEXTURE_GEN_S} | |
13183 | ||
13184 | ||
13185 | @var{params} returns a single boolean value indicating whether automatic | |
f37e7e3d DH |
13186 | generation of the @var{S} texture coordinate is enabled. The initial |
13187 | value is @code{GL_FALSE}. See @code{glTexGen}. | |
b002944d AW |
13188 | |
13189 | @item @code{GL_TEXTURE_GEN_T} | |
13190 | ||
13191 | ||
13192 | @var{params} returns a single boolean value indicating whether automatic | |
f37e7e3d DH |
13193 | generation of the T texture coordinate is enabled. The initial value is |
13194 | @code{GL_FALSE}. See @code{glTexGen}. | |
b002944d AW |
13195 | |
13196 | @item @code{GL_TEXTURE_MATRIX} | |
13197 | ||
13198 | ||
13199 | @var{params} returns sixteen values: the texture matrix on the top of | |
f37e7e3d | 13200 | the texture matrix stack. Initially this matrix is the identity matrix. |
b002944d AW |
13201 | See @code{glPushMatrix}. |
13202 | ||
13203 | @item @code{GL_TEXTURE_STACK_DEPTH} | |
13204 | ||
13205 | ||
13206 | @var{params} returns one value, the number of matrices on the texture | |
f37e7e3d | 13207 | matrix stack. The initial value is 1. See @code{glPushMatrix}. |
b002944d AW |
13208 | |
13209 | @item @code{GL_TRANSPOSE_COLOR_MATRIX} | |
13210 | ||
13211 | ||
13212 | @var{params} returns 16 values, the elements of the color matrix in | |
f37e7e3d | 13213 | row-major order. See @code{glLoadTransposeMatrix}. |
b002944d AW |
13214 | |
13215 | @item @code{GL_TRANSPOSE_MODELVIEW_MATRIX} | |
13216 | ||
13217 | ||
13218 | @var{params} returns 16 values, the elements of the modelview matrix in | |
f37e7e3d | 13219 | row-major order. See @code{glLoadTransposeMatrix}. |
b002944d AW |
13220 | |
13221 | @item @code{GL_TRANSPOSE_PROJECTION_MATRIX} | |
13222 | ||
13223 | ||
13224 | @var{params} returns 16 values, the elements of the projection matrix in | |
f37e7e3d | 13225 | row-major order. See @code{glLoadTransposeMatrix}. |
b002944d AW |
13226 | |
13227 | @item @code{GL_TRANSPOSE_TEXTURE_MATRIX} | |
13228 | ||
13229 | ||
13230 | @var{params} returns 16 values, the elements of the texture matrix in | |
f37e7e3d | 13231 | row-major order. See @code{glLoadTransposeMatrix}. |
b002944d AW |
13232 | |
13233 | @item @code{GL_UNPACK_ALIGNMENT} | |
13234 | ||
13235 | ||
13236 | @var{params} returns one value, the byte alignment used for reading | |
f37e7e3d | 13237 | pixel data from memory. The initial value is 4. See @code{glPixelStore}. |
b002944d AW |
13238 | |
13239 | @item @code{GL_UNPACK_IMAGE_HEIGHT} | |
13240 | ||
13241 | ||
13242 | @var{params} returns one value, the image height used for reading pixel | |
f37e7e3d | 13243 | data from memory. The initial is 0. See @code{glPixelStore}. |
b002944d AW |
13244 | |
13245 | @item @code{GL_UNPACK_LSB_FIRST} | |
13246 | ||
13247 | ||
13248 | @var{params} returns a single boolean value indicating whether | |
13249 | single-bit pixels being read from memory are read first from the least | |
f37e7e3d DH |
13250 | significant bit of each unsigned byte. The initial value is |
13251 | @code{GL_FALSE}. See @code{glPixelStore}. | |
b002944d AW |
13252 | |
13253 | @item @code{GL_UNPACK_ROW_LENGTH} | |
13254 | ||
13255 | ||
13256 | @var{params} returns one value, the row length used for reading pixel | |
f37e7e3d | 13257 | data from memory. The initial value is 0. See @code{glPixelStore}. |
b002944d AW |
13258 | |
13259 | @item @code{GL_UNPACK_SKIP_IMAGES} | |
13260 | ||
13261 | ||
13262 | @var{params} returns one value, the number of pixel images skipped | |
f37e7e3d | 13263 | before the first pixel is read from memory. The initial value is 0. See |
b002944d AW |
13264 | @code{glPixelStore}. |
13265 | ||
13266 | @item @code{GL_UNPACK_SKIP_PIXELS} | |
13267 | ||
13268 | ||
13269 | @var{params} returns one value, the number of pixel locations skipped | |
f37e7e3d | 13270 | before the first pixel is read from memory. The initial value is 0. See |
b002944d AW |
13271 | @code{glPixelStore}. |
13272 | ||
13273 | @item @code{GL_UNPACK_SKIP_ROWS} | |
8925f36f AW |
13274 | |
13275 | ||
b002944d | 13276 | @var{params} returns one value, the number of rows of pixel locations |
f37e7e3d DH |
13277 | skipped before the first pixel is read from memory. The initial value is |
13278 | 0. See @code{glPixelStore}. | |
8925f36f | 13279 | |
b002944d | 13280 | @item @code{GL_UNPACK_SWAP_BYTES} |
8925f36f AW |
13281 | |
13282 | ||
b002944d AW |
13283 | @var{params} returns a single boolean value indicating whether the bytes |
13284 | of two-byte and four-byte pixel indices and components are swapped after | |
f37e7e3d | 13285 | being read from memory. The initial value is @code{GL_FALSE}. See |
b002944d | 13286 | @code{glPixelStore}. |
8925f36f | 13287 | |
b002944d | 13288 | @item @code{GL_VERTEX_ARRAY} |
8925f36f AW |
13289 | |
13290 | ||
b002944d | 13291 | @var{params} returns a single boolean value indicating whether the |
f37e7e3d | 13292 | vertex array is enabled. The initial value is @code{GL_FALSE}. See |
b002944d | 13293 | @code{glVertexPointer}. |
8925f36f | 13294 | |
b002944d | 13295 | @item @code{GL_VERTEX_ARRAY_BUFFER_BINDING} |
8925f36f AW |
13296 | |
13297 | ||
b002944d | 13298 | @var{params} returns a single value, the name of the buffer object |
f37e7e3d | 13299 | associated with the vertex array. This buffer object would have been |
b002944d | 13300 | bound to the target @code{GL_ARRAY_BUFFER} at the time of the most |
f37e7e3d DH |
13301 | recent call to @code{glVertexPointer}. If no buffer object was bound to |
13302 | this target, 0 is returned. The initial value is 0. See | |
b002944d | 13303 | @code{glBindBuffer}. |
8925f36f | 13304 | |
b002944d | 13305 | @item @code{GL_VERTEX_ARRAY_SIZE} |
8925f36f AW |
13306 | |
13307 | ||
b002944d | 13308 | @var{params} returns one value, the number of coordinates per vertex in |
f37e7e3d | 13309 | the vertex array. The initial value is 4. See @code{glVertexPointer}. |
8925f36f | 13310 | |
b002944d | 13311 | @item @code{GL_VERTEX_ARRAY_STRIDE} |
8925f36f AW |
13312 | |
13313 | ||
b002944d | 13314 | @var{params} returns one value, the byte offset between consecutive |
f37e7e3d | 13315 | vertices in the vertex array. The initial value is 0. See |
b002944d | 13316 | @code{glVertexPointer}. |
8925f36f | 13317 | |
b002944d | 13318 | @item @code{GL_VERTEX_ARRAY_TYPE} |
8925f36f AW |
13319 | |
13320 | ||
b002944d | 13321 | @var{params} returns one value, the data type of each coordinate in the |
f37e7e3d | 13322 | vertex array. The initial value is @code{GL_FLOAT}. See |
b002944d | 13323 | @code{glVertexPointer}. |
8925f36f | 13324 | |
b002944d | 13325 | @item @code{GL_VERTEX_PROGRAM_POINT_SIZE} |
8925f36f AW |
13326 | |
13327 | ||
b002944d | 13328 | @var{params} returns a single boolean value indicating whether vertex |
f37e7e3d | 13329 | program point size mode is enabled. If enabled, and a vertex shader is |
b002944d | 13330 | active, then the point size is taken from the shader built-in |
f37e7e3d | 13331 | @code{gl_PointSize}. If disabled, and a vertex shader is active, then |
b002944d | 13332 | the point size is taken from the point state as specified by |
f37e7e3d | 13333 | @code{glPointSize}. The initial value is @code{GL_FALSE}. |
8925f36f | 13334 | |
b002944d | 13335 | @item @code{GL_VERTEX_PROGRAM_TWO_SIDE} |
8925f36f AW |
13336 | |
13337 | ||
b002944d | 13338 | @var{params} returns a single boolean value indicating whether vertex |
f37e7e3d DH |
13339 | program two-sided color mode is enabled. If enabled, and a vertex shader |
13340 | is active, then the GL chooses the back color output for back-facing | |
13341 | polygons, and the front color output for non-polygons and front-facing | |
13342 | polygons. If disabled, and a vertex shader is active, then the front | |
13343 | color output is always selected. The initial value is @code{GL_FALSE}. | |
8925f36f | 13344 | |
b002944d | 13345 | @item @code{GL_VIEWPORT} |
8925f36f AW |
13346 | |
13347 | ||
b002944d | 13348 | @var{params} returns four values: the @r{@var{x}} and @r{@var{y}} window |
f37e7e3d | 13349 | coordinates of the viewport, followed by its width and height. Initially |
b002944d AW |
13350 | the @r{@var{x}} and @r{@var{y}} window coordinates are both set to 0, |
13351 | and the width and height are set to the width and height of the window | |
f37e7e3d | 13352 | into which the GL will do its rendering. See @code{glViewport}. |
8925f36f | 13353 | |
b002944d | 13354 | @item @code{GL_ZOOM_X} |
8925f36f AW |
13355 | |
13356 | ||
f37e7e3d DH |
13357 | @var{params} returns one value, the @r{@var{x}} pixel zoom factor. The |
13358 | initial value is 1. See @code{glPixelZoom}. | |
8925f36f | 13359 | |
b002944d | 13360 | @item @code{GL_ZOOM_Y} |
8925f36f | 13361 | |
8925f36f | 13362 | |
f37e7e3d DH |
13363 | @var{params} returns one value, the @r{@var{y}} pixel zoom factor. The |
13364 | initial value is 1. See @code{glPixelZoom}. | |
8925f36f | 13365 | |
b002944d | 13366 | @end table |
bb894c9d | 13367 | |
b002944d AW |
13368 | Many of the boolean parameters can also be queried more easily using |
13369 | @code{glIsEnabled}. | |
8925f36f | 13370 | |
b002944d AW |
13371 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
13372 | value. | |
13373 | ||
13374 | @code{GL_INVALID_OPERATION} is generated if @code{glGet} is executed | |
13375 | between the execution of @code{glBegin} and the corresponding execution | |
13376 | of @code{glEnd}. | |
bb894c9d | 13377 | |
8925f36f AW |
13378 | |
13379 | ||
bb894c9d | 13380 | @end deftypefun |
8925f36f | 13381 | |
bb894c9d | 13382 | @deftypefun void glHint target mode |
3c9b6116 AW |
13383 | Specify implementation-specific hints. |
13384 | ||
8925f36f AW |
13385 | @table @asis |
13386 | @item @var{target} | |
13387 | Specifies a symbolic constant indicating the behavior to be controlled. | |
13388 | @code{GL_FOG_HINT}, @code{GL_GENERATE_MIPMAP_HINT}, | |
13389 | @code{GL_LINE_SMOOTH_HINT}, @code{GL_PERSPECTIVE_CORRECTION_HINT}, | |
13390 | @code{GL_POINT_SMOOTH_HINT}, @code{GL_POLYGON_SMOOTH_HINT}, | |
13391 | @code{GL_TEXTURE_COMPRESSION_HINT}, and | |
13392 | @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} are accepted. | |
13393 | ||
13394 | @item @var{mode} | |
13395 | Specifies a symbolic constant indicating the desired behavior. | |
13396 | @code{GL_FASTEST}, @code{GL_NICEST}, and @code{GL_DONT_CARE} are | |
13397 | accepted. | |
13398 | ||
13399 | @end table | |
13400 | ||
8925f36f | 13401 | Certain aspects of GL behavior, when there is room for interpretation, |
f37e7e3d | 13402 | can be controlled with hints. A hint is specified with two arguments. |
8925f36f AW |
13403 | @var{target} is a symbolic constant indicating the behavior to be |
13404 | controlled, and @var{mode} is another symbolic constant indicating the | |
f37e7e3d DH |
13405 | desired behavior. The initial value for each @var{target} is |
13406 | @code{GL_DONT_CARE}. @var{mode} can be one of the following: | |
8925f36f AW |
13407 | |
13408 | @table @asis | |
13409 | @item @code{GL_FASTEST} | |
13410 | ||
13411 | ||
13412 | The most efficient option should be chosen. | |
13413 | ||
13414 | @item @code{GL_NICEST} | |
13415 | ||
13416 | ||
13417 | The most correct, or highest quality, option should be chosen. | |
13418 | ||
13419 | @item @code{GL_DONT_CARE} | |
13420 | ||
13421 | ||
13422 | No preference. | |
13423 | ||
13424 | @end table | |
13425 | ||
13426 | Though the implementation aspects that can be hinted are well defined, | |
f37e7e3d | 13427 | the interpretation of the hints depends on the implementation. The hint |
8925f36f AW |
13428 | aspects that can be specified with @var{target}, along with suggested |
13429 | semantics, are as follows: | |
13430 | ||
13431 | @table @asis | |
13432 | @item @code{GL_FOG_HINT} | |
13433 | ||
13434 | ||
f37e7e3d | 13435 | Indicates the accuracy of fog calculation. If per-pixel fog calculation |
8925f36f AW |
13436 | is not efficiently supported by the GL implementation, hinting |
13437 | @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in per-vertex | |
13438 | calculation of fog effects. | |
13439 | ||
13440 | @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} | |
13441 | ||
13442 | ||
13443 | Indicates the accuracy of the derivative calculation for the GL shading | |
13444 | language fragment processing built-in functions: @code{dFdx}, | |
13445 | @code{dFdy}, and @code{fwidth}. | |
13446 | ||
13447 | @item @code{GL_GENERATE_MIPMAP_HINT} | |
13448 | ||
13449 | ||
13450 | Indicates the quality of filtering when generating mipmap images. | |
13451 | ||
13452 | @item @code{GL_LINE_SMOOTH_HINT} | |
13453 | ||
13454 | ||
f37e7e3d | 13455 | Indicates the sampling quality of antialiased lines. If a larger filter |
8925f36f AW |
13456 | function is applied, hinting @code{GL_NICEST} can result in more pixel |
13457 | fragments being generated during rasterization. | |
13458 | ||
13459 | @item @code{GL_PERSPECTIVE_CORRECTION_HINT} | |
13460 | ||
13461 | ||
13462 | Indicates the quality of color, texture coordinate, and fog coordinate | |
f37e7e3d | 13463 | interpolation. If perspective-corrected parameter interpolation is not |
8925f36f AW |
13464 | efficiently supported by the GL implementation, hinting |
13465 | @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in simple linear | |
13466 | interpolation of colors and/or texture coordinates. | |
13467 | ||
13468 | @item @code{GL_POINT_SMOOTH_HINT} | |
13469 | ||
13470 | ||
f37e7e3d DH |
13471 | Indicates the sampling quality of antialiased points. If a larger filter |
13472 | function is applied, hinting @code{GL_NICEST} can result in more pixel | |
13473 | fragments being generated during rasterization. | |
8925f36f AW |
13474 | |
13475 | @item @code{GL_POLYGON_SMOOTH_HINT} | |
13476 | ||
13477 | ||
f37e7e3d | 13478 | Indicates the sampling quality of antialiased polygons. Hinting |
8925f36f AW |
13479 | @code{GL_NICEST} can result in more pixel fragments being generated |
13480 | during rasterization, if a larger filter function is applied. | |
13481 | ||
13482 | @item @code{GL_TEXTURE_COMPRESSION_HINT} | |
13483 | ||
13484 | ||
13485 | Indicates the quality and performance of the compressing texture images. | |
13486 | Hinting @code{GL_FASTEST} indicates that texture images should be | |
13487 | compressed as quickly as possible, while @code{GL_NICEST} indicates that | |
13488 | texture images should be compressed with as little image quality loss as | |
f37e7e3d | 13489 | possible. @code{GL_NICEST} should be selected if the texture is to be |
8925f36f AW |
13490 | retrieved by @code{glGetCompressedTexImage} for reuse. |
13491 | ||
13492 | @end table | |
13493 | ||
8925f36f AW |
13494 | @code{GL_INVALID_ENUM} is generated if either @var{target} or @var{mode} |
13495 | is not an accepted value. | |
13496 | ||
13497 | @code{GL_INVALID_OPERATION} is generated if @code{glHint} is executed | |
13498 | between the execution of @code{glBegin} and the corresponding execution | |
13499 | of @code{glEnd}. | |
13500 | ||
bb894c9d | 13501 | @end deftypefun |
8925f36f | 13502 | |
bb894c9d | 13503 | @deftypefun void glHistogram target width internalformat sink |
3c9b6116 AW |
13504 | Define histogram table. |
13505 | ||
8925f36f AW |
13506 | @table @asis |
13507 | @item @var{target} | |
f37e7e3d | 13508 | The histogram whose parameters are to be set. Must be one of |
8925f36f AW |
13509 | @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}. |
13510 | ||
13511 | @item @var{width} | |
f37e7e3d | 13512 | The number of entries in the histogram table. Must be a power of 2. |
8925f36f AW |
13513 | |
13514 | @item @var{internalformat} | |
f37e7e3d | 13515 | The format of entries in the histogram table. Must be one of |
8925f36f AW |
13516 | @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, |
13517 | @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
13518 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
13519 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
13520 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
13521 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
13522 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
13523 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
13524 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
13525 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
13526 | @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
13527 | ||
13528 | @item @var{sink} | |
13529 | If @code{GL_TRUE}, pixels will be consumed by the histogramming process | |
f37e7e3d | 13530 | and no drawing or texture loading will take place. If @code{GL_FALSE}, |
8925f36f AW |
13531 | pixels will proceed to the minmax process after histogramming. |
13532 | ||
13533 | @end table | |
13534 | ||
8925f36f AW |
13535 | When @code{GL_HISTOGRAM} is enabled, RGBA color components are converted |
13536 | to histogram table indices by clamping to the range [0,1], multiplying | |
13537 | by the width of the histogram table, and rounding to the nearest | |
f37e7e3d DH |
13538 | integer. The table entries selected by the RGBA indices are then |
13539 | incremented. (If the internal format of the histogram table includes | |
8925f36f AW |
13540 | luminance, then the index derived from the R color component determines |
13541 | the luminance table entry to be incremented.) If a histogram table entry | |
13542 | is incremented beyond its maximum value, then its value becomes | |
f37e7e3d | 13543 | undefined. (This is not an error.) |
8925f36f AW |
13544 | |
13545 | Histogramming is performed only for RGBA pixels (though these may be | |
13546 | specified originally as color indices and converted to RGBA by index | |
f37e7e3d | 13547 | table lookup). Histogramming is enabled with @code{glEnable} and |
8925f36f AW |
13548 | disabled with @code{glDisable}. |
13549 | ||
13550 | When @var{target} is @code{GL_HISTOGRAM}, @code{glHistogram} redefines | |
13551 | the current histogram table to have @var{width} entries of the format | |
f37e7e3d DH |
13552 | specified by @var{internalformat}. The entries are indexed 0 through |
13553 | @r{@var{width}-1}, and all entries are initialized to zero. The values | |
13554 | in the previous histogram table, if any, are lost. If @var{sink} is | |
3c9b6116 | 13555 | @code{GL_TRUE}, then pixels are discarded after histogramming; no |
8925f36f AW |
13556 | further processing of the pixels takes place, and no drawing, texture |
13557 | loading, or pixel readback will result. | |
13558 | ||
13559 | When @var{target} is @code{GL_PROXY_HISTOGRAM}, @code{glHistogram} | |
13560 | computes all state information as if the histogram table were to be | |
f37e7e3d | 13561 | redefined, but does not actually define the new table. If the requested |
8925f36f | 13562 | histogram table is too large to be supported, then the state information |
f37e7e3d | 13563 | will be set to zero. This provides a way to determine if a histogram |
8925f36f AW |
13564 | table with the given parameters can be supported. |
13565 | ||
13566 | ||
13567 | ||
8925f36f AW |
13568 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
13569 | allowable values. | |
13570 | ||
13571 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
13572 | is not a power of 2. | |
13573 | ||
13574 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
13575 | of the allowable values. | |
13576 | ||
13577 | @code{GL_TABLE_TOO_LARGE} is generated if @var{target} is | |
13578 | @code{GL_HISTOGRAM} and the histogram table specified is too large for | |
13579 | the implementation. | |
13580 | ||
13581 | @code{GL_INVALID_OPERATION} is generated if @code{glHistogram} is | |
13582 | executed between the execution of @code{glBegin} and the corresponding | |
13583 | execution of @code{glEnd}. | |
13584 | ||
bb894c9d | 13585 | @end deftypefun |
8925f36f | 13586 | |
bb894c9d | 13587 | @deftypefun void glIndexMask mask |
3c9b6116 AW |
13588 | Control the writing of individual bits in the color index buffers. |
13589 | ||
8925f36f AW |
13590 | @table @asis |
13591 | @item @var{mask} | |
13592 | Specifies a bit mask to enable and disable the writing of individual | |
f37e7e3d | 13593 | bits in the color index buffers. Initially, the mask is all 1's. |
8925f36f AW |
13594 | |
13595 | @end table | |
13596 | ||
8925f36f | 13597 | @code{glIndexMask} controls the writing of individual bits in the color |
f37e7e3d | 13598 | index buffers. The least significant @r{@var{n}} bits of @var{mask}, |
3c9b6116 | 13599 | where @r{@var{n}} is the number of bits in a color index buffer, specify |
f37e7e3d DH |
13600 | a mask. Where a 1 (one) appears in the mask, it's possible to write to |
13601 | the corresponding bit in the color index buffer (or buffers). Where a 0 | |
3c9b6116 | 13602 | (zero) appears, the corresponding bit is write-protected. |
8925f36f AW |
13603 | |
13604 | This mask is used only in color index mode, and it affects only the | |
13605 | buffers currently selected for writing (see @code{glDrawBuffer}). | |
13606 | Initially, all bits are enabled for writing. | |
13607 | ||
8925f36f AW |
13608 | @code{GL_INVALID_OPERATION} is generated if @code{glIndexMask} 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 glIndexPointer type stride pointer |
3c9b6116 AW |
13615 | Define an array of color indexes. |
13616 | ||
8925f36f AW |
13617 | @table @asis |
13618 | @item @var{type} | |
f37e7e3d | 13619 | Specifies the data type of each color index in the array. Symbolic |
8925f36f | 13620 | constants @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, @code{GL_INT}, |
f37e7e3d DH |
13621 | @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is |
13622 | @code{GL_FLOAT}. | |
8925f36f AW |
13623 | |
13624 | @item @var{stride} | |
f37e7e3d | 13625 | Specifies the byte offset between consecutive color indexes. If |
8925f36f | 13626 | @var{stride} is 0, the color indexes are understood to be tightly packed |
f37e7e3d | 13627 | in the array. The initial value is 0. |
8925f36f AW |
13628 | |
13629 | @item @var{pointer} | |
f37e7e3d | 13630 | Specifies a pointer to the first index in the array. The initial value |
8925f36f AW |
13631 | is 0. |
13632 | ||
13633 | @end table | |
13634 | ||
8925f36f | 13635 | @code{glIndexPointer} specifies the location and data format of an array |
f37e7e3d | 13636 | of color indexes to use when rendering. @var{type} specifies the data |
8925f36f AW |
13637 | type of each color index and @var{stride} specifies the byte stride from |
13638 | one color index to the next, allowing vertices and attributes to be | |
13639 | packed into a single array or stored in separate arrays. | |
13640 | ||
13641 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
13642 | target (see @code{glBindBuffer}) while a color index array is specified, | |
13643 | @var{pointer} is treated as a byte offset into the buffer object's data | |
f37e7e3d | 13644 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) |
8925f36f AW |
13645 | is saved as color index vertex array client-side state |
13646 | (@code{GL_INDEX_ARRAY_BUFFER_BINDING}). | |
13647 | ||
13648 | When a color index array is specified, @var{type}, @var{stride}, and | |
13649 | @var{pointer} are saved as client-side state, in addition to the current | |
13650 | vertex array buffer object binding. | |
13651 | ||
13652 | To enable and disable the color index array, call | |
13653 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
f37e7e3d | 13654 | argument @code{GL_INDEX_ARRAY}. If enabled, the color index array is |
8925f36f AW |
13655 | used when @code{glDrawArrays}, @code{glMultiDrawArrays}, |
13656 | @code{glDrawElements}, @code{glMultiDrawElements}, | |
13657 | @code{glDrawRangeElements}, or @code{glArrayElement} is called. | |
13658 | ||
8925f36f AW |
13659 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
13660 | value. | |
13661 | ||
13662 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
13663 | ||
bb894c9d | 13664 | @end deftypefun |
8925f36f | 13665 | |
d172eed9 AW |
13666 | @deftypefun void glIndexs c |
13667 | @deftypefunx void glIndexi c | |
ca09631c | 13668 | @deftypefunx void glIndexf c |
d172eed9 | 13669 | @deftypefunx void glIndexd c |
bb894c9d | 13670 | @deftypefunx void glIndexub c |
d172eed9 AW |
13671 | @deftypefunx void glIndexsv c |
13672 | @deftypefunx void glIndexiv c | |
13673 | @deftypefunx void glIndexfv c | |
13674 | @deftypefunx void glIndexdv c | |
13675 | @deftypefunx void glIndexubv c | |
3c9b6116 AW |
13676 | Set the current color index. |
13677 | ||
8925f36f AW |
13678 | @table @asis |
13679 | @item @var{c} | |
13680 | Specifies the new value for the current color index. | |
13681 | ||
13682 | ||
13683 | ||
13684 | @end table | |
13685 | ||
f37e7e3d DH |
13686 | @code{glIndex} updates the current (single-valued) color index. It takes |
13687 | one argument, the new value for the current color index. | |
8925f36f | 13688 | |
f37e7e3d | 13689 | The current index is stored as a floating-point value. Integer values |
8925f36f | 13690 | are converted directly to floating-point values, with no special |
f37e7e3d | 13691 | mapping. The initial value is 1. |
8925f36f AW |
13692 | |
13693 | Index values outside the representable range of the color index buffer | |
f37e7e3d DH |
13694 | are not clamped. However, before an index is dithered (if enabled) and |
13695 | written to the frame buffer, it is converted to fixed-point format. Any | |
8925f36f AW |
13696 | bits in the integer portion of the resulting fixed-point value that do |
13697 | not correspond to bits in the frame buffer are masked out. | |
13698 | ||
bb894c9d | 13699 | @end deftypefun |
8925f36f | 13700 | |
bb894c9d | 13701 | @deftypefun void glInitNames |
3c9b6116 AW |
13702 | Initialize the name stack. |
13703 | ||
8925f36f | 13704 | The name stack is used during selection mode to allow sets of rendering |
f37e7e3d DH |
13705 | commands to be uniquely identified. It consists of an ordered set of |
13706 | unsigned integers. @code{glInitNames} causes the name stack to be | |
8925f36f AW |
13707 | initialized to its default empty state. |
13708 | ||
13709 | The name stack is always empty while the render mode is not | |
f37e7e3d | 13710 | @code{GL_SELECT}. Calls to @code{glInitNames} while the render mode is |
8925f36f AW |
13711 | not @code{GL_SELECT} are ignored. |
13712 | ||
8925f36f AW |
13713 | @code{GL_INVALID_OPERATION} is generated if @code{glInitNames} is |
13714 | executed between the execution of @code{glBegin} and the corresponding | |
13715 | execution of @code{glEnd}. | |
13716 | ||
bb894c9d | 13717 | @end deftypefun |
8925f36f | 13718 | |
bb894c9d | 13719 | @deftypefun void glInterleavedArrays format stride pointer |
3c9b6116 AW |
13720 | Simultaneously specify and enable several interleaved arrays. |
13721 | ||
8925f36f AW |
13722 | @table @asis |
13723 | @item @var{format} | |
f37e7e3d DH |
13724 | Specifies the type of array to enable. Symbolic constants @code{GL_V2F}, |
13725 | @code{GL_V3F}, @code{GL_C4UB_V2F}, @code{GL_C4UB_V3F}, | |
8925f36f AW |
13726 | @code{GL_C3F_V3F}, @code{GL_N3F_V3F}, @code{GL_C4F_N3F_V3F}, |
13727 | @code{GL_T2F_V3F}, @code{GL_T4F_V4F}, @code{GL_T2F_C4UB_V3F}, | |
13728 | @code{GL_T2F_C3F_V3F}, @code{GL_T2F_N3F_V3F}, @code{GL_T2F_C4F_N3F_V3F}, | |
13729 | and @code{GL_T4F_C4F_N3F_V4F} are accepted. | |
13730 | ||
13731 | @item @var{stride} | |
13732 | Specifies the offset in bytes between each aggregate array element. | |
13733 | ||
13734 | @end table | |
13735 | ||
8925f36f AW |
13736 | @code{glInterleavedArrays} lets you specify and enable individual color, |
13737 | normal, texture and vertex arrays whose elements are part of a larger | |
f37e7e3d | 13738 | aggregate array element. For some implementations, this is more |
8925f36f AW |
13739 | efficient than specifying the arrays separately. |
13740 | ||
13741 | If @var{stride} is 0, the aggregate elements are stored consecutively. | |
13742 | Otherwise, @var{stride} bytes occur between the beginning of one | |
13743 | aggregate array element and the beginning of the next aggregate array | |
13744 | element. | |
13745 | ||
13746 | @var{format} serves as a ``key'' describing the extraction of individual | |
f37e7e3d DH |
13747 | arrays from the aggregate array. If @var{format} contains a T, then |
13748 | texture coordinates are extracted from the interleaved array. If C is | |
13749 | present, color values are extracted. If N is present, normal coordinates | |
13750 | are extracted. Vertex coordinates are always extracted. | |
8925f36f | 13751 | |
f37e7e3d DH |
13752 | The digits 2, 3, and 4 denote how many values are extracted. F indicates |
13753 | that values are extracted as floating-point values. Colors may also be | |
13754 | extracted as 4 unsigned bytes if 4UB follows the C. If a color is | |
13755 | extracted as 4 unsigned bytes, the vertex array element which follows is | |
13756 | located at the first possible floating-point aligned address. | |
8925f36f | 13757 | |
8925f36f AW |
13758 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted |
13759 | value. | |
13760 | ||
13761 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
13762 | ||
bb894c9d | 13763 | @end deftypefun |
8925f36f | 13764 | |
bb894c9d | 13765 | @deftypefun GLboolean glIsBuffer buffer |
3c9b6116 AW |
13766 | Determine if a name corresponds to a buffer object. |
13767 | ||
8925f36f AW |
13768 | @table @asis |
13769 | @item @var{buffer} | |
13770 | Specifies a value that may be the name of a buffer object. | |
13771 | ||
13772 | @end table | |
13773 | ||
8925f36f | 13774 | @code{glIsBuffer} returns @code{GL_TRUE} if @var{buffer} is currently |
f37e7e3d | 13775 | the name of a buffer object. If @var{buffer} is zero, or is a non-zero |
8925f36f AW |
13776 | value that is not currently the name of a buffer object, or if an error |
13777 | occurs, @code{glIsBuffer} returns @code{GL_FALSE}. | |
13778 | ||
13779 | A name returned by @code{glGenBuffers}, but not yet associated with a | |
13780 | buffer object by calling @code{glBindBuffer}, is not the name of a | |
13781 | buffer object. | |
13782 | ||
8925f36f AW |
13783 | @code{GL_INVALID_OPERATION} is generated if @code{glIsBuffer} is |
13784 | executed between the execution of @code{glBegin} and the corresponding | |
13785 | execution of @code{glEnd}. | |
13786 | ||
bb894c9d | 13787 | @end deftypefun |
8925f36f | 13788 | |
bb894c9d | 13789 | @deftypefun GLboolean glIsEnabled cap |
3c9b6116 AW |
13790 | Test whether a capability is enabled. |
13791 | ||
8925f36f AW |
13792 | @table @asis |
13793 | @item @var{cap} | |
13794 | Specifies a symbolic constant indicating a GL capability. | |
13795 | ||
13796 | @end table | |
13797 | ||
8925f36f | 13798 | @code{glIsEnabled} returns @code{GL_TRUE} if @var{cap} is an enabled |
f37e7e3d | 13799 | capability and returns @code{GL_FALSE} otherwise. Initially all |
8925f36f AW |
13800 | capabilities except @code{GL_DITHER} are disabled; @code{GL_DITHER} is |
13801 | initially enabled. | |
13802 | ||
13803 | The following capabilities are accepted for @var{cap}: | |
13804 | ||
13805 | ||
13806 | ||
13807 | @table @asis | |
13808 | @item @strong{Constant} | |
13809 | @strong{See} | |
13810 | ||
13811 | @item @code{GL_ALPHA_TEST} | |
13812 | @code{glAlphaFunc} | |
13813 | ||
13814 | @item @code{GL_AUTO_NORMAL} | |
13815 | @code{glEvalCoord} | |
13816 | ||
13817 | @item @code{GL_BLEND} | |
13818 | @code{glBlendFunc}, @code{glLogicOp} | |
13819 | ||
13820 | @item @code{GL_CLIP_PLANE}@var{i} | |
13821 | @code{glClipPlane} | |
13822 | ||
13823 | @item @code{GL_COLOR_ARRAY} | |
13824 | @code{glColorPointer} | |
13825 | ||
13826 | @item @code{GL_COLOR_LOGIC_OP} | |
13827 | @code{glLogicOp} | |
13828 | ||
13829 | @item @code{GL_COLOR_MATERIAL} | |
13830 | @code{glColorMaterial} | |
13831 | ||
13832 | @item @code{GL_COLOR_SUM} | |
13833 | @code{glSecondaryColor} | |
13834 | ||
13835 | @item @code{GL_COLOR_TABLE} | |
13836 | @code{glColorTable} | |
13837 | ||
13838 | @item @code{GL_CONVOLUTION_1D} | |
13839 | @code{glConvolutionFilter1D} | |
13840 | ||
13841 | @item @code{GL_CONVOLUTION_2D} | |
13842 | @code{glConvolutionFilter2D} | |
13843 | ||
13844 | @item @code{GL_CULL_FACE} | |
13845 | @code{glCullFace} | |
13846 | ||
13847 | @item @code{GL_DEPTH_TEST} | |
13848 | @code{glDepthFunc}, @code{glDepthRange} | |
13849 | ||
13850 | @item @code{GL_DITHER} | |
13851 | @code{glEnable} | |
13852 | ||
13853 | @item @code{GL_EDGE_FLAG_ARRAY} | |
13854 | @code{glEdgeFlagPointer} | |
13855 | ||
13856 | @item @code{GL_FOG} | |
13857 | @code{glFog} | |
13858 | ||
13859 | @item @code{GL_FOG_COORD_ARRAY} | |
13860 | @code{glFogCoordPointer} | |
13861 | ||
13862 | @item @code{GL_HISTOGRAM} | |
13863 | @code{glHistogram} | |
13864 | ||
13865 | @item @code{GL_INDEX_ARRAY} | |
13866 | @code{glIndexPointer} | |
13867 | ||
13868 | @item @code{GL_INDEX_LOGIC_OP} | |
13869 | @code{glLogicOp} | |
13870 | ||
13871 | @item @code{GL_LIGHT}@var{i} | |
13872 | @code{glLightModel}, @code{glLight} | |
13873 | ||
13874 | @item @code{GL_LIGHTING} | |
13875 | @code{glMaterial}, @code{glLightModel}, @code{glLight} | |
13876 | ||
13877 | @item @code{GL_LINE_SMOOTH} | |
13878 | @code{glLineWidth} | |
13879 | ||
13880 | @item @code{GL_LINE_STIPPLE} | |
13881 | @code{glLineStipple} | |
13882 | ||
13883 | @item @code{GL_MAP1_COLOR_4} | |
13884 | @code{glMap1} | |
13885 | ||
13886 | @item @code{GL_MAP1_INDEX} | |
13887 | @code{glMap1} | |
13888 | ||
13889 | @item @code{GL_MAP1_NORMAL} | |
13890 | @code{glMap1} | |
13891 | ||
13892 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
13893 | @code{glMap1} | |
13894 | ||
13895 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
13896 | @code{glMap1} | |
13897 | ||
13898 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
13899 | @code{glMap1} | |
13900 | ||
13901 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
13902 | @code{glMap1} | |
13903 | ||
13904 | @item @code{GL_MAP2_COLOR_4} | |
13905 | @code{glMap2} | |
13906 | ||
13907 | @item @code{GL_MAP2_INDEX} | |
13908 | @code{glMap2} | |
13909 | ||
13910 | @item @code{GL_MAP2_NORMAL} | |
13911 | @code{glMap2} | |
13912 | ||
13913 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
13914 | @code{glMap2} | |
13915 | ||
13916 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
13917 | @code{glMap2} | |
13918 | ||
13919 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
13920 | @code{glMap2} | |
13921 | ||
13922 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
13923 | @code{glMap2} | |
13924 | ||
13925 | @item @code{GL_MAP2_VERTEX_3} | |
13926 | @code{glMap2} | |
13927 | ||
13928 | @item @code{GL_MAP2_VERTEX_4} | |
13929 | @code{glMap2} | |
13930 | ||
13931 | @item @code{GL_MINMAX} | |
13932 | @code{glMinmax} | |
13933 | ||
13934 | @item @code{GL_MULTISAMPLE} | |
13935 | @code{glSampleCoverage} | |
13936 | ||
13937 | @item @code{GL_NORMAL_ARRAY} | |
13938 | @code{glNormalPointer} | |
13939 | ||
13940 | @item @code{GL_NORMALIZE} | |
13941 | @code{glNormal} | |
13942 | ||
13943 | @item @code{GL_POINT_SMOOTH} | |
13944 | @code{glPointSize} | |
13945 | ||
13946 | @item @code{GL_POINT_SPRITE} | |
13947 | @code{glEnable} | |
13948 | ||
13949 | @item @code{GL_POLYGON_SMOOTH} | |
13950 | @code{glPolygonMode} | |
13951 | ||
13952 | @item @code{GL_POLYGON_OFFSET_FILL} | |
13953 | @code{glPolygonOffset} | |
13954 | ||
13955 | @item @code{GL_POLYGON_OFFSET_LINE} | |
13956 | @code{glPolygonOffset} | |
13957 | ||
13958 | @item @code{GL_POLYGON_OFFSET_POINT} | |
13959 | @code{glPolygonOffset} | |
13960 | ||
13961 | @item @code{GL_POLYGON_STIPPLE} | |
13962 | @code{glPolygonStipple} | |
13963 | ||
13964 | @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} | |
13965 | @code{glColorTable} | |
13966 | ||
13967 | @item @code{GL_POST_CONVOLUTION_COLOR_TABLE} | |
13968 | @code{glColorTable} | |
13969 | ||
13970 | @item @code{GL_RESCALE_NORMAL} | |
13971 | @code{glNormal} | |
13972 | ||
13973 | @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE} | |
13974 | @code{glSampleCoverage} | |
13975 | ||
13976 | @item @code{GL_SAMPLE_ALPHA_TO_ONE} | |
13977 | @code{glSampleCoverage} | |
13978 | ||
13979 | @item @code{GL_SAMPLE_COVERAGE} | |
13980 | @code{glSampleCoverage} | |
13981 | ||
13982 | @item @code{GL_SCISSOR_TEST} | |
13983 | @code{glScissor} | |
13984 | ||
13985 | @item @code{GL_SECONDARY_COLOR_ARRAY} | |
13986 | @code{glSecondaryColorPointer} | |
13987 | ||
13988 | @item @code{GL_SEPARABLE_2D} | |
13989 | @code{glSeparableFilter2D} | |
13990 | ||
13991 | @item @code{GL_STENCIL_TEST} | |
13992 | @code{glStencilFunc}, @code{glStencilOp} | |
13993 | ||
13994 | @item @code{GL_TEXTURE_1D} | |
13995 | @code{glTexImage1D} | |
13996 | ||
13997 | @item @code{GL_TEXTURE_2D} | |
13998 | @code{glTexImage2D} | |
13999 | ||
14000 | @item @code{GL_TEXTURE_3D} | |
14001 | @code{glTexImage3D} | |
14002 | ||
14003 | @item @code{GL_TEXTURE_COORD_ARRAY} | |
14004 | @code{glTexCoordPointer} | |
14005 | ||
14006 | @item @code{GL_TEXTURE_CUBE_MAP} | |
14007 | @code{glTexImage2D} | |
14008 | ||
14009 | @item @code{GL_TEXTURE_GEN_Q} | |
14010 | @code{glTexGen} | |
14011 | ||
14012 | @item @code{GL_TEXTURE_GEN_R} | |
14013 | @code{glTexGen} | |
14014 | ||
14015 | @item @code{GL_TEXTURE_GEN_S} | |
14016 | @code{glTexGen} | |
14017 | ||
14018 | @item @code{GL_TEXTURE_GEN_T} | |
14019 | @code{glTexGen} | |
14020 | ||
14021 | @item @code{GL_VERTEX_ARRAY} | |
14022 | @code{glVertexPointer} | |
14023 | ||
14024 | @item @code{GL_VERTEX_PROGRAM_POINT_SIZE} | |
14025 | @code{glEnable} | |
14026 | ||
14027 | @item @code{GL_VERTEX_PROGRAM_TWO_SIDE} | |
14028 | @code{glEnable} | |
14029 | ||
14030 | @end table | |
14031 | ||
14032 | ||
14033 | ||
8925f36f AW |
14034 | @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted |
14035 | value. | |
14036 | ||
14037 | @code{GL_INVALID_OPERATION} is generated if @code{glIsEnabled} is | |
14038 | executed between the execution of @code{glBegin} and the corresponding | |
14039 | execution of @code{glEnd}. | |
14040 | ||
bb894c9d | 14041 | @end deftypefun |
8925f36f | 14042 | |
bb894c9d | 14043 | @deftypefun GLboolean glIsList list |
3c9b6116 AW |
14044 | Determine if a name corresponds to a display list. |
14045 | ||
8925f36f AW |
14046 | @table @asis |
14047 | @item @var{list} | |
14048 | Specifies a potential display list name. | |
14049 | ||
14050 | @end table | |
14051 | ||
8925f36f AW |
14052 | @code{glIsList} returns @code{GL_TRUE} if @var{list} is the name of a |
14053 | display list and returns @code{GL_FALSE} if it is not, or if an error | |
14054 | occurs. | |
14055 | ||
14056 | A name returned by @code{glGenLists}, but not yet associated with a | |
14057 | display list by calling @code{glNewList}, is not the name of a display | |
14058 | list. | |
14059 | ||
8925f36f AW |
14060 | @code{GL_INVALID_OPERATION} is generated if @code{glIsList} is executed |
14061 | between the execution of @code{glBegin} and the corresponding execution | |
14062 | of @code{glEnd}. | |
14063 | ||
bb894c9d | 14064 | @end deftypefun |
8925f36f | 14065 | |
bb894c9d | 14066 | @deftypefun GLboolean glIsProgram program |
3c9b6116 AW |
14067 | Determines if a name corresponds to a program object. |
14068 | ||
8925f36f AW |
14069 | @table @asis |
14070 | @item @var{program} | |
14071 | Specifies a potential program object. | |
14072 | ||
14073 | @end table | |
14074 | ||
8925f36f AW |
14075 | @code{glIsProgram} returns @code{GL_TRUE} if @var{program} is the name |
14076 | of a program object previously created with @code{glCreateProgram} and | |
f37e7e3d DH |
14077 | not yet deleted with @code{glDeleteProgram}. If @var{program} is zero or |
14078 | a non-zero value that is not the name of a program object, or if an | |
8925f36f AW |
14079 | error occurs, @code{glIsProgram} returns @code{GL_FALSE}. |
14080 | ||
8925f36f AW |
14081 | @code{GL_INVALID_OPERATION} is generated if @code{glIsProgram} is |
14082 | executed between the execution of @code{glBegin} and the corresponding | |
14083 | execution of @code{glEnd}. | |
14084 | ||
bb894c9d | 14085 | @end deftypefun |
8925f36f | 14086 | |
bb894c9d | 14087 | @deftypefun GLboolean glIsQuery id |
3c9b6116 AW |
14088 | Determine if a name corresponds to a query object. |
14089 | ||
8925f36f AW |
14090 | @table @asis |
14091 | @item @var{id} | |
14092 | Specifies a value that may be the name of a query object. | |
14093 | ||
14094 | @end table | |
14095 | ||
8925f36f | 14096 | @code{glIsQuery} returns @code{GL_TRUE} if @var{id} is currently the |
f37e7e3d DH |
14097 | name of a query object. If @var{id} is zero, or is a non-zero value that |
14098 | is not currently the name of a query object, or if an error occurs, | |
8925f36f AW |
14099 | @code{glIsQuery} returns @code{GL_FALSE}. |
14100 | ||
14101 | A name returned by @code{glGenQueries}, but not yet associated with a | |
14102 | query object by calling @code{glBeginQuery}, is not the name of a query | |
14103 | object. | |
14104 | ||
8925f36f AW |
14105 | @code{GL_INVALID_OPERATION} is generated if @code{glIsQuery} is executed |
14106 | between the execution of @code{glBegin} and the corresponding execution | |
14107 | of @code{glEnd}. | |
14108 | ||
bb894c9d | 14109 | @end deftypefun |
8925f36f | 14110 | |
bb894c9d | 14111 | @deftypefun GLboolean glIsShader shader |
3c9b6116 AW |
14112 | Determines if a name corresponds to a shader object. |
14113 | ||
8925f36f AW |
14114 | @table @asis |
14115 | @item @var{shader} | |
14116 | Specifies a potential shader object. | |
14117 | ||
14118 | @end table | |
14119 | ||
8925f36f AW |
14120 | @code{glIsShader} returns @code{GL_TRUE} if @var{shader} is the name of |
14121 | a shader object previously created with @code{glCreateShader} and not | |
f37e7e3d | 14122 | yet deleted with @code{glDeleteShader}. If @var{shader} is zero or a |
8925f36f AW |
14123 | non-zero value that is not the name of a shader object, or if an error |
14124 | occurs, @code{glIsShader } returns @code{GL_FALSE}. | |
14125 | ||
8925f36f AW |
14126 | @code{GL_INVALID_OPERATION} is generated if @code{glIsShader} is |
14127 | executed between the execution of @code{glBegin} and the corresponding | |
14128 | execution of @code{glEnd}. | |
14129 | ||
bb894c9d | 14130 | @end deftypefun |
8925f36f | 14131 | |
bb894c9d | 14132 | @deftypefun GLboolean glIsTexture texture |
3c9b6116 AW |
14133 | Determine if a name corresponds to a texture. |
14134 | ||
8925f36f AW |
14135 | @table @asis |
14136 | @item @var{texture} | |
14137 | Specifies a value that may be the name of a texture. | |
14138 | ||
14139 | @end table | |
14140 | ||
8925f36f | 14141 | @code{glIsTexture} returns @code{GL_TRUE} if @var{texture} is currently |
f37e7e3d | 14142 | the name of a texture. If @var{texture} is zero, or is a non-zero value |
8925f36f AW |
14143 | that is not currently the name of a texture, or if an error occurs, |
14144 | @code{glIsTexture} returns @code{GL_FALSE}. | |
14145 | ||
14146 | A name returned by @code{glGenTextures}, but not yet associated with a | |
14147 | texture by calling @code{glBindTexture}, is not the name of a texture. | |
14148 | ||
8925f36f AW |
14149 | @code{GL_INVALID_OPERATION} is generated if @code{glIsTexture} is |
14150 | executed between the execution of @code{glBegin} and the corresponding | |
14151 | execution of @code{glEnd}. | |
14152 | ||
bb894c9d | 14153 | @end deftypefun |
8925f36f | 14154 | |
bb894c9d AW |
14155 | @deftypefun void glLightModelf pname param |
14156 | @deftypefunx void glLightModeli pname param | |
d172eed9 AW |
14157 | @deftypefunx void glLightModelfv pname params |
14158 | @deftypefunx void glLightModeliv pname params | |
3c9b6116 AW |
14159 | Set the lighting model parameters. |
14160 | ||
8925f36f AW |
14161 | @table @asis |
14162 | @item @var{pname} | |
14163 | Specifies a single-valued lighting model parameter. | |
14164 | @code{GL_LIGHT_MODEL_LOCAL_VIEWER}, @code{GL_LIGHT_MODEL_COLOR_CONTROL}, | |
14165 | and @code{GL_LIGHT_MODEL_TWO_SIDE} are accepted. | |
14166 | ||
14167 | @item @var{param} | |
14168 | Specifies the value that @var{param} will be set to. | |
14169 | ||
14170 | @end table | |
14171 | ||
f37e7e3d DH |
14172 | @code{glLightModel} sets the lighting model parameter. @var{pname} names |
14173 | a parameter and @var{params} gives the new value. There are three | |
8925f36f AW |
14174 | lighting model parameters: |
14175 | ||
14176 | @table @asis | |
14177 | @item @code{GL_LIGHT_MODEL_AMBIENT} | |
14178 | ||
14179 | ||
14180 | @var{params} contains four integer or floating-point values that specify | |
f37e7e3d | 14181 | the ambient RGBA intensity of the entire scene. Integer values are |
8925f36f | 14182 | mapped linearly such that the most positive representable value maps to |
3c9b6116 | 14183 | 1.0, and the most negative representable value maps to @r{-1.0}. |
f37e7e3d DH |
14184 | Floating-point values are mapped directly. Neither integer nor |
14185 | floating-point values are clamped. The initial ambient scene intensity | |
8925f36f AW |
14186 | is (0.2, 0.2, 0.2, 1.0). |
14187 | ||
14188 | @item @code{GL_LIGHT_MODEL_COLOR_CONTROL} | |
14189 | ||
14190 | ||
14191 | @var{params} must be either @code{GL_SEPARATE_SPECULAR_COLOR} or | |
f37e7e3d | 14192 | @code{GL_SINGLE_COLOR}. @code{GL_SINGLE_COLOR} specifies that a single |
8925f36f AW |
14193 | color is generated from the lighting computation for a vertex. |
14194 | @code{GL_SEPARATE_SPECULAR_COLOR} specifies that the specular color | |
14195 | computation of lighting be stored separately from the remainder of the | |
f37e7e3d | 14196 | lighting computation. The specular color is summed into the generated |
8925f36f AW |
14197 | fragment's color after the application of texture mapping (if enabled). |
14198 | The initial value is @code{GL_SINGLE_COLOR}. | |
14199 | ||
14200 | @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER} | |
14201 | ||
14202 | ||
14203 | @var{params} is a single integer or floating-point value that specifies | |
f37e7e3d | 14204 | how specular reflection angles are computed. If @var{params} is 0 (or |
8925f36f AW |
14205 | 0.0), specular reflection angles take the view direction to be parallel |
14206 | to and in the direction of the -@var{z} axis, regardless of the location | |
f37e7e3d DH |
14207 | of the vertex in eye coordinates. Otherwise, specular reflections are |
14208 | computed from the origin of the eye coordinate system. The initial value | |
14209 | is 0. | |
8925f36f AW |
14210 | |
14211 | @item @code{GL_LIGHT_MODEL_TWO_SIDE} | |
14212 | ||
14213 | ||
14214 | @var{params} is a single integer or floating-point value that specifies | |
14215 | whether one- or two-sided lighting calculations are done for polygons. | |
14216 | It has no effect on the lighting calculations for points, lines, or | |
f37e7e3d DH |
14217 | bitmaps. If @var{params} is 0 (or 0.0), one-sided lighting is specified, |
14218 | and only the @var{front} material parameters are used in the lighting | |
14219 | equation. Otherwise, two-sided lighting is specified. In this case, | |
14220 | vertices of back-facing polygons are lighted using the @var{back} | |
8925f36f | 14221 | material parameters and have their normals reversed before the lighting |
f37e7e3d | 14222 | equation is evaluated. Vertices of front-facing polygons are always |
8925f36f | 14223 | lighted using the @var{front} material parameters, with no change to |
f37e7e3d | 14224 | their normals. The initial value is 0. |
8925f36f AW |
14225 | |
14226 | @end table | |
14227 | ||
14228 | In RGBA mode, the lighted color of a vertex is the sum of the material | |
14229 | emission intensity, the product of the material ambient reflectance and | |
14230 | the lighting model full-scene ambient intensity, and the contribution of | |
f37e7e3d DH |
14231 | each enabled light source. Each light source contributes the sum of |
14232 | three terms: ambient, diffuse, and specular. The ambient light source | |
8925f36f | 14233 | contribution is the product of the material ambient reflectance and the |
f37e7e3d | 14234 | light's ambient intensity. The diffuse light source contribution is the |
8925f36f AW |
14235 | product of the material diffuse reflectance, the light's diffuse |
14236 | intensity, and the dot product of the vertex's normal with the | |
f37e7e3d | 14237 | normalized vector from the vertex to the light source. The specular |
8925f36f AW |
14238 | light source contribution is the product of the material specular |
14239 | reflectance, the light's specular intensity, and the dot product of the | |
14240 | normalized vertex-to-eye and vertex-to-light vectors, raised to the | |
f37e7e3d | 14241 | power of the shininess of the material. All three light source |
8925f36f AW |
14242 | contributions are attenuated equally based on the distance from the |
14243 | vertex to the light source and on light source direction, spread | |
f37e7e3d | 14244 | exponent, and spread cutoff angle. All dot products are replaced with 0 |
8925f36f AW |
14245 | if they evaluate to a negative value. |
14246 | ||
14247 | The alpha component of the resulting lighted color is set to the alpha | |
14248 | value of the material diffuse reflectance. | |
14249 | ||
14250 | In color index mode, the value of the lighted index of a vertex ranges | |
14251 | from the ambient to the specular values passed to @code{glMaterial} | |
f37e7e3d | 14252 | using @code{GL_COLOR_INDEXES}. Diffuse and specular coefficients, |
8925f36f AW |
14253 | computed with a (.30, .59, .11) weighting of the lights' colors, the |
14254 | shininess of the material, and the same reflection and attenuation | |
14255 | equations as in the RGBA case, determine how much above ambient the | |
14256 | resulting index is. | |
14257 | ||
8925f36f AW |
14258 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
14259 | value. | |
14260 | ||
14261 | @code{GL_INVALID_ENUM} is generated if @var{pname} is | |
14262 | @code{GL_LIGHT_MODEL_COLOR_CONTROL} and @var{params} is not one of | |
14263 | @code{GL_SINGLE_COLOR} or @code{GL_SEPARATE_SPECULAR_COLOR}. | |
14264 | ||
14265 | @code{GL_INVALID_OPERATION} is generated if @code{glLightModel} is | |
14266 | executed between the execution of @code{glBegin} and the corresponding | |
14267 | execution of @code{glEnd}. | |
14268 | ||
bb894c9d | 14269 | @end deftypefun |
8925f36f | 14270 | |
bb894c9d AW |
14271 | @deftypefun void glLightf light pname param |
14272 | @deftypefunx void glLighti light pname param | |
d172eed9 AW |
14273 | @deftypefunx void glLightfv light pname params |
14274 | @deftypefunx void glLightiv light pname params | |
3c9b6116 AW |
14275 | Set light source parameters. |
14276 | ||
8925f36f AW |
14277 | @table @asis |
14278 | @item @var{light} | |
f37e7e3d DH |
14279 | Specifies a light. The number of lights depends on the implementation, |
14280 | but at least eight lights are supported. They are identified by symbolic | |
14281 | names of the form @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to | |
14282 | the value of @code{GL_MAX_LIGHTS} - 1. | |
8925f36f AW |
14283 | |
14284 | @item @var{pname} | |
14285 | Specifies a single-valued light source parameter for @var{light}. | |
14286 | @code{GL_SPOT_EXPONENT}, @code{GL_SPOT_CUTOFF}, | |
14287 | @code{GL_CONSTANT_ATTENUATION}, @code{GL_LINEAR_ATTENUATION}, and | |
14288 | @code{GL_QUADRATIC_ATTENUATION} are accepted. | |
14289 | ||
14290 | @item @var{param} | |
14291 | Specifies the value that parameter @var{pname} of light source | |
14292 | @var{light} will be set to. | |
14293 | ||
14294 | @end table | |
14295 | ||
8925f36f AW |
14296 | @code{glLight} sets the values of individual light source parameters. |
14297 | @var{light} names the light and is a symbolic name of the form | |
3c9b6116 | 14298 | @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to the value of |
f37e7e3d DH |
14299 | @code{GL_MAX_LIGHTS} - 1. @var{pname} specifies one of ten light source |
14300 | parameters, again by symbolic name. @var{params} is either a single | |
8925f36f AW |
14301 | value or a pointer to an array that contains the new values. |
14302 | ||
14303 | To enable and disable lighting calculation, call @code{glEnable} and | |
f37e7e3d DH |
14304 | @code{glDisable} with argument @code{GL_LIGHTING}. Lighting is initially |
14305 | disabled. When it is enabled, light sources that are enabled contribute | |
14306 | to the lighting calculation. Light source @r{@var{i}} is enabled and | |
14307 | disabled using @code{glEnable} and @code{glDisable} with argument | |
14308 | @code{GL_LIGHT}@r{@var{i}}. | |
8925f36f AW |
14309 | |
14310 | The ten light parameters are as follows: | |
14311 | ||
14312 | @table @asis | |
14313 | @item @code{GL_AMBIENT} | |
14314 | @var{params} contains four integer or floating-point values that specify | |
f37e7e3d | 14315 | the ambient RGBA intensity of the light. Integer values are mapped |
8925f36f | 14316 | linearly such that the most positive representable value maps to 1.0, |
3c9b6116 | 14317 | and the most negative representable value maps to @r{-1.0}. |
f37e7e3d DH |
14318 | Floating-point values are mapped directly. Neither integer nor |
14319 | floating-point values are clamped. The initial ambient light intensity | |
8925f36f AW |
14320 | is (0, 0, 0, 1). |
14321 | ||
14322 | @item @code{GL_DIFFUSE} | |
14323 | @var{params} contains four integer or floating-point values that specify | |
f37e7e3d | 14324 | the diffuse RGBA intensity of the light. Integer values are mapped |
8925f36f | 14325 | linearly such that the most positive representable value maps to 1.0, |
3c9b6116 | 14326 | and the most negative representable value maps to @r{-1.0}. |
f37e7e3d DH |
14327 | Floating-point values are mapped directly. Neither integer nor |
14328 | floating-point values are clamped. The initial value for | |
8925f36f AW |
14329 | @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is |
14330 | (0, 0, 0, 1). | |
14331 | ||
14332 | @item @code{GL_SPECULAR} | |
14333 | @var{params} contains four integer or floating-point values that specify | |
f37e7e3d | 14334 | the specular RGBA intensity of the light. Integer values are mapped |
8925f36f | 14335 | linearly such that the most positive representable value maps to 1.0, |
3c9b6116 | 14336 | and the most negative representable value maps to @r{-1.0}. |
f37e7e3d DH |
14337 | Floating-point values are mapped directly. Neither integer nor |
14338 | floating-point values are clamped. The initial value for | |
8925f36f AW |
14339 | @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is |
14340 | (0, 0, 0, 1). | |
14341 | ||
14342 | @item @code{GL_POSITION} | |
14343 | @var{params} contains four integer or floating-point values that specify | |
f37e7e3d DH |
14344 | the position of the light in homogeneous object coordinates. Both |
14345 | integer and floating-point values are mapped directly. Neither integer | |
8925f36f AW |
14346 | nor floating-point values are clamped. |
14347 | ||
14348 | The position is transformed by the modelview matrix when @code{glLight} | |
14349 | is called (just as if it were a point), and it is stored in eye | |
f37e7e3d DH |
14350 | coordinates. If the @r{@var{w}} component of the position is 0, the |
14351 | light is treated as a directional source. Diffuse and specular lighting | |
8925f36f | 14352 | calculations take the light's direction, but not its actual position, |
f37e7e3d | 14353 | into account, and attenuation is disabled. Otherwise, diffuse and |
8925f36f | 14354 | specular lighting calculations are based on the actual location of the |
f37e7e3d | 14355 | light in eye coordinates, and attenuation is enabled. The initial |
8925f36f | 14356 | position is (0, 0, 1, 0); thus, the initial light source is directional, |
3c9b6116 | 14357 | parallel to, and in the direction of the @r{-@var{z}} axis. |
8925f36f AW |
14358 | |
14359 | @item @code{GL_SPOT_DIRECTION} | |
14360 | @var{params} contains three integer or floating-point values that | |
14361 | specify the direction of the light in homogeneous object coordinates. | |
f37e7e3d | 14362 | Both integer and floating-point values are mapped directly. Neither |
8925f36f AW |
14363 | integer nor floating-point values are clamped. |
14364 | ||
14365 | The spot direction is transformed by the upper 3x3 of the modelview | |
14366 | matrix when @code{glLight} is called, and it is stored in eye | |
f37e7e3d DH |
14367 | coordinates. It is significant only when @code{GL_SPOT_CUTOFF} is not |
14368 | 180, which it is initially. The initial direction is @r{(0,0-1)}. | |
8925f36f AW |
14369 | |
14370 | @item @code{GL_SPOT_EXPONENT} | |
14371 | @var{params} is a single integer or floating-point value that specifies | |
f37e7e3d DH |
14372 | the intensity distribution of the light. Integer and floating-point |
14373 | values are mapped directly. Only values in the range @r{[0,128]} are | |
8925f36f AW |
14374 | accepted. |
14375 | ||
14376 | Effective light intensity is attenuated by the cosine of the angle | |
14377 | between the direction of the light and the direction from the light to | |
14378 | the vertex being lighted, raised to the power of the spot exponent. | |
14379 | Thus, higher spot exponents result in a more focused light source, | |
14380 | regardless of the spot cutoff angle (see @code{GL_SPOT_CUTOFF}, next | |
f37e7e3d | 14381 | paragraph). The initial spot exponent is 0, resulting in uniform light |
8925f36f AW |
14382 | distribution. |
14383 | ||
14384 | @item @code{GL_SPOT_CUTOFF} | |
14385 | @var{params} is a single integer or floating-point value that specifies | |
f37e7e3d DH |
14386 | the maximum spread angle of a light source. Integer and floating-point |
14387 | values are mapped directly. Only values in the range @r{[0,90]} and the | |
14388 | special value 180 are accepted. If the angle between the direction of | |
3c9b6116 AW |
14389 | the light and the direction from the light to the vertex being lighted |
14390 | is greater than the spot cutoff angle, the light is completely masked. | |
14391 | Otherwise, its intensity is controlled by the spot exponent and the | |
f37e7e3d | 14392 | attenuation factors. The initial spot cutoff is 180, resulting in |
8925f36f AW |
14393 | uniform light distribution. |
14394 | ||
14395 | @item @code{GL_CONSTANT_ATTENUATION} | |
14396 | @item @code{GL_LINEAR_ATTENUATION} | |
14397 | @item @code{GL_QUADRATIC_ATTENUATION} | |
14398 | @var{params} is a single integer or floating-point value that specifies | |
f37e7e3d DH |
14399 | one of the three light attenuation factors. Integer and floating-point |
14400 | values are mapped directly. Only nonnegative values are accepted. If the | |
14401 | light is positional, rather than directional, its intensity is | |
8925f36f AW |
14402 | attenuated by the reciprocal of the sum of the constant factor, the |
14403 | linear factor times the distance between the light and the vertex being | |
14404 | lighted, and the quadratic factor times the square of the same distance. | |
14405 | The initial attenuation factors are (1, 0, 0), resulting in no | |
14406 | attenuation. | |
14407 | ||
14408 | @end table | |
14409 | ||
8925f36f AW |
14410 | @code{GL_INVALID_ENUM} is generated if either @var{light} or @var{pname} |
14411 | is not an accepted value. | |
14412 | ||
14413 | @code{GL_INVALID_VALUE} is generated if a spot exponent value is | |
3c9b6116 AW |
14414 | specified outside the range @r{[0,128]}, or if spot cutoff is specified |
14415 | outside the range @r{[0,90]} (except for the special value 180), or if a | |
14416 | negative attenuation factor is specified. | |
8925f36f AW |
14417 | |
14418 | @code{GL_INVALID_OPERATION} is generated if @code{glLight} is executed | |
14419 | between the execution of @code{glBegin} and the corresponding execution | |
14420 | of @code{glEnd}. | |
14421 | ||
bb894c9d | 14422 | @end deftypefun |
8925f36f | 14423 | |
bb894c9d | 14424 | @deftypefun void glLineStipple factor pattern |
3c9b6116 AW |
14425 | Specify the line stipple pattern. |
14426 | ||
8925f36f AW |
14427 | @table @asis |
14428 | @item @var{factor} | |
f37e7e3d | 14429 | Specifies a multiplier for each bit in the line stipple pattern. If |
8925f36f | 14430 | @var{factor} is 3, for example, each bit in the pattern is used three |
f37e7e3d | 14431 | times before the next bit in the pattern is used. @var{factor} is |
8925f36f AW |
14432 | clamped to the range [1, 256] and defaults to 1. |
14433 | ||
14434 | @item @var{pattern} | |
14435 | Specifies a 16-bit integer whose bit pattern determines which fragments | |
f37e7e3d | 14436 | of a line will be drawn when the line is rasterized. Bit zero is used |
8925f36f AW |
14437 | first; the default pattern is all 1's. |
14438 | ||
14439 | @end table | |
14440 | ||
8925f36f | 14441 | Line stippling masks out certain fragments produced by rasterization; |
f37e7e3d | 14442 | those fragments will not be drawn. The masking is achieved by using |
8925f36f | 14443 | three parameters: the 16-bit line stipple pattern @var{pattern}, the |
3c9b6116 | 14444 | repeat count @var{factor}, and an integer stipple counter @r{@var{s}}. |
8925f36f | 14445 | |
3c9b6116 AW |
14446 | Counter @r{@var{s}} is reset to 0 whenever @code{glBegin} is called and |
14447 | before each line segment of a | |
f37e7e3d | 14448 | @code{glBegin}(@code{GL_LINES})/@code{glEnd} sequence is generated. It |
8925f36f | 14449 | is incremented after each fragment of a unit width aliased line segment |
3c9b6116 | 14450 | is generated or after each @r{@var{i}} fragments of an @r{@var{i}} width |
f37e7e3d | 14451 | line segment are generated. The @r{@var{i}} fragments associated with |
3c9b6116 | 14452 | count @r{@var{s}} are masked out if |
8925f36f | 14453 | |
3c9b6116 | 14454 | @var{pattern} bit @r{(@var{s}/@var{factor},)%16} |
8925f36f | 14455 | |
f37e7e3d | 14456 | is 0, otherwise these fragments are sent to the frame buffer. Bit zero |
8925f36f AW |
14457 | of @var{pattern} is the least significant bit. |
14458 | ||
3c9b6116 | 14459 | Antialiased lines are treated as a sequence of @r{1×@var{width}} |
f37e7e3d | 14460 | rectangles for purposes of stippling. Whether rectangle @r{@var{s}} is |
3c9b6116 | 14461 | rasterized or not depends on the fragment rule described for aliased |
8925f36f AW |
14462 | lines, counting rectangles rather than groups of fragments. |
14463 | ||
14464 | To enable and disable line stippling, call @code{glEnable} and | |
f37e7e3d DH |
14465 | @code{glDisable} with argument @code{GL_LINE_STIPPLE}. When enabled, the |
14466 | line stipple pattern is applied as described above. When disabled, it is | |
14467 | as if the pattern were all 1's. Initially, line stippling is disabled. | |
8925f36f | 14468 | |
8925f36f AW |
14469 | @code{GL_INVALID_OPERATION} is generated if @code{glLineStipple} is |
14470 | executed between the execution of @code{glBegin} and the corresponding | |
14471 | execution of @code{glEnd}. | |
14472 | ||
bb894c9d | 14473 | @end deftypefun |
8925f36f | 14474 | |
bb894c9d | 14475 | @deftypefun void glLineWidth width |
3c9b6116 AW |
14476 | Specify the width of rasterized lines. |
14477 | ||
8925f36f AW |
14478 | @table @asis |
14479 | @item @var{width} | |
f37e7e3d | 14480 | Specifies the width of rasterized lines. The initial value is 1. |
8925f36f AW |
14481 | |
14482 | @end table | |
14483 | ||
8925f36f | 14484 | @code{glLineWidth} specifies the rasterized width of both aliased and |
f37e7e3d DH |
14485 | antialiased lines. Using a line width other than 1 has different |
14486 | effects, depending on whether line antialiasing is enabled. To enable | |
8925f36f | 14487 | and disable line antialiasing, call @code{glEnable} and @code{glDisable} |
f37e7e3d | 14488 | with argument @code{GL_LINE_SMOOTH}. Line antialiasing is initially |
8925f36f AW |
14489 | disabled. |
14490 | ||
14491 | If line antialiasing is disabled, the actual width is determined by | |
f37e7e3d | 14492 | rounding the supplied width to the nearest integer. (If the rounding |
8925f36f | 14493 | results in the value 0, it is as if the line width were 1.) If |
3c9b6116 AW |
14494 | @r{∣Δ@var{x},∣>=∣Δ@var{y},∣}, @var{i} pixels are filled in each column |
14495 | that is rasterized, where @var{i} is the rounded value of @var{width}. | |
14496 | Otherwise, @var{i} pixels are filled in each row that is rasterized. | |
8925f36f AW |
14497 | |
14498 | If antialiasing is enabled, line rasterization produces a fragment for | |
14499 | each pixel square that intersects the region lying within the rectangle | |
14500 | having width equal to the current line width, length equal to the actual | |
f37e7e3d | 14501 | length of the line, and centered on the mathematical line segment. The |
8925f36f AW |
14502 | coverage value for each fragment is the window coordinate area of the |
14503 | intersection of the rectangular region with the corresponding pixel | |
f37e7e3d | 14504 | square. This value is saved and used in the final rasterization step. |
8925f36f | 14505 | |
f37e7e3d DH |
14506 | Not all widths can be supported when line antialiasing is enabled. If an |
14507 | unsupported width is requested, the nearest supported width is used. | |
8925f36f | 14508 | Only width 1 is guaranteed to be supported; others depend on the |
f37e7e3d DH |
14509 | implementation. Likewise, there is a range for aliased line widths as |
14510 | well. To query the range of supported widths and the size difference | |
8925f36f AW |
14511 | between supported widths within the range, call @code{glGet} with |
14512 | arguments @code{GL_ALIASED_LINE_WIDTH_RANGE}, | |
14513 | @code{GL_SMOOTH_LINE_WIDTH_RANGE}, and | |
14514 | @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY}. | |
14515 | ||
8925f36f AW |
14516 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than or |
14517 | equal to 0. | |
14518 | ||
14519 | @code{GL_INVALID_OPERATION} is generated if @code{glLineWidth} is | |
14520 | executed between the execution of @code{glBegin} and the corresponding | |
14521 | execution of @code{glEnd}. | |
14522 | ||
bb894c9d | 14523 | @end deftypefun |
8925f36f | 14524 | |
bb894c9d | 14525 | @deftypefun void glLinkProgram program |
3c9b6116 AW |
14526 | Links a program object. |
14527 | ||
8925f36f AW |
14528 | @table @asis |
14529 | @item @var{program} | |
14530 | Specifies the handle of the program object to be linked. | |
14531 | ||
14532 | @end table | |
14533 | ||
8925f36f | 14534 | @code{glLinkProgram} links the program object specified by |
f37e7e3d DH |
14535 | @var{program}. If any shader objects of type @code{GL_VERTEX_SHADER} are |
14536 | attached to @var{program}, they will be used to create an executable | |
14537 | that will run on the programmable vertex processor. If any shader | |
8925f36f AW |
14538 | objects of type @code{GL_FRAGMENT_SHADER} are attached to @var{program}, |
14539 | they will be used to create an executable that will run on the | |
14540 | programmable fragment processor. | |
14541 | ||
14542 | The status of the link operation will be stored as part of the program | |
f37e7e3d | 14543 | object's state. This value will be set to @code{GL_TRUE} if the program |
8925f36f | 14544 | object was linked without errors and is ready for use, and |
f37e7e3d | 14545 | @code{GL_FALSE} otherwise. It can be queried by calling |
8925f36f AW |
14546 | @code{glGetProgram} with arguments @var{program} and |
14547 | @code{GL_LINK_STATUS}. | |
14548 | ||
14549 | As a result of a successful link operation, all active user-defined | |
14550 | uniform variables belonging to @var{program} will be initialized to 0, | |
14551 | and each of the program object's active uniform variables will be | |
14552 | assigned a location that can be queried by calling | |
f37e7e3d | 14553 | @code{glGetUniformLocation}. Also, any active user-defined attribute |
8925f36f AW |
14554 | variables that have not been bound to a generic vertex attribute index |
14555 | will be bound to one at this time. | |
14556 | ||
14557 | Linking of a program object can fail for a number of reasons as | |
f37e7e3d | 14558 | specified in the @var{OpenGL Shading Language Specification}. The |
8925f36f AW |
14559 | following lists some of the conditions that will cause a link error. |
14560 | ||
14561 | @itemize | |
14562 | @item | |
14563 | The number of active attribute variables supported by the implementation | |
14564 | has been exceeded. | |
14565 | ||
14566 | @item | |
14567 | The storage limit for uniform variables has been exceeded. | |
14568 | ||
14569 | @item | |
14570 | The number of active uniform variables supported by the implementation | |
14571 | has been exceeded. | |
14572 | ||
14573 | @item | |
14574 | The @code{main} function is missing for the vertex shader or the | |
14575 | fragment shader. | |
14576 | ||
14577 | @item | |
14578 | A varying variable actually used in the fragment shader is not declared | |
14579 | in the same way (or is not declared at all) in the vertex shader. | |
14580 | ||
14581 | @item | |
14582 | A reference to a function or variable name is unresolved. | |
14583 | ||
14584 | @item | |
14585 | A shared global is declared with two different types or two different | |
14586 | initial values. | |
14587 | ||
14588 | @item | |
14589 | One or more of the attached shader objects has not been successfully | |
14590 | compiled. | |
14591 | ||
14592 | @item | |
14593 | Binding a generic attribute matrix caused some rows of the matrix to | |
14594 | fall outside the allowed maximum of @code{GL_MAX_VERTEX_ATTRIBS}. | |
14595 | ||
14596 | @item | |
14597 | Not enough contiguous vertex attribute slots could be found to bind | |
14598 | attribute matrices. | |
14599 | ||
14600 | @end itemize | |
14601 | ||
14602 | When a program object has been successfully linked, the program object | |
14603 | can be made part of current state by calling @code{glUseProgram}. | |
14604 | Whether or not the link operation was successful, the program object's | |
f37e7e3d | 14605 | information log will be overwritten. The information log can be |
8925f36f AW |
14606 | retrieved by calling @code{glGetProgramInfoLog}. |
14607 | ||
14608 | @code{glLinkProgram} will also install the generated executables as part | |
14609 | of the current rendering state if the link operation was successful and | |
14610 | the specified program object is already currently in use as a result of | |
f37e7e3d | 14611 | a previous call to @code{glUseProgram}. If the program object currently |
8925f36f AW |
14612 | in use is relinked unsuccessfully, its link status will be set to |
14613 | @code{GL_FALSE} , but the executables and associated state will remain | |
14614 | part of the current state until a subsequent call to @code{glUseProgram} | |
f37e7e3d | 14615 | removes it from use. After it is removed from use, it cannot be made |
8925f36f AW |
14616 | part of current state until it has been successfully relinked. |
14617 | ||
14618 | If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER} | |
14619 | but does not contain shader objects of type @code{GL_FRAGMENT_SHADER}, | |
14620 | the vertex shader will be linked against the implicit interface for | |
f37e7e3d | 14621 | fixed functionality fragment processing. Similarly, if @var{program} |
8925f36f AW |
14622 | contains shader objects of type @code{GL_FRAGMENT_SHADER} but it does |
14623 | not contain shader objects of type @code{GL_VERTEX_SHADER}, the fragment | |
14624 | shader will be linked against the implicit interface for fixed | |
14625 | functionality vertex processing. | |
14626 | ||
14627 | The program object's information log is updated and the program is | |
f37e7e3d | 14628 | generated at the time of the link operation. After the link operation, |
8925f36f AW |
14629 | applications are free to modify attached shader objects, compile |
14630 | attached shader objects, detach shader objects, delete shader objects, | |
f37e7e3d | 14631 | and attach additional shader objects. None of these operations affects |
8925f36f AW |
14632 | the information log or the program that is part of the program object. |
14633 | ||
8925f36f AW |
14634 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
14635 | generated by OpenGL. | |
14636 | ||
14637 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
14638 | program object. | |
14639 | ||
14640 | @code{GL_INVALID_OPERATION} is generated if @code{glLinkProgram} is | |
14641 | executed between the execution of @code{glBegin} and the corresponding | |
14642 | execution of @code{glEnd}. | |
14643 | ||
bb894c9d | 14644 | @end deftypefun |
8925f36f | 14645 | |
bb894c9d | 14646 | @deftypefun void glListBase base |
3c9b6116 AW |
14647 | Set the display-list base for . |
14648 | ||
8925f36f AW |
14649 | @table @asis |
14650 | @item @var{base} | |
14651 | Specifies an integer offset that will be added to @code{glCallLists} | |
f37e7e3d | 14652 | offsets to generate display-list names. The initial value is 0. |
8925f36f AW |
14653 | |
14654 | @end table | |
14655 | ||
f37e7e3d DH |
14656 | @code{glCallLists} specifies an array of offsets. Display-list names are |
14657 | generated by adding @var{base} to each offset. Names that reference | |
8925f36f AW |
14658 | valid display lists are executed; the others are ignored. |
14659 | ||
8925f36f AW |
14660 | @code{GL_INVALID_OPERATION} is generated if @code{glListBase} is |
14661 | executed between the execution of @code{glBegin} and the corresponding | |
14662 | execution of @code{glEnd}. | |
14663 | ||
bb894c9d | 14664 | @end deftypefun |
8925f36f | 14665 | |
bb894c9d | 14666 | @deftypefun void glLoadIdentity |
3c9b6116 AW |
14667 | Replace the current matrix with the identity matrix. |
14668 | ||
8925f36f | 14669 | @code{glLoadIdentity} replaces the current matrix with the identity |
f37e7e3d | 14670 | matrix. It is semantically equivalent to calling @code{glLoadMatrix} |
8925f36f AW |
14671 | with the identity matrix |
14672 | ||
14673 | ||
14674 | ||
3c9b6116 | 14675 | @r{((1 0 0 0), (0 1 0 0), (0 0 1 0), (0 0 0 1),,)} |
8925f36f AW |
14676 | |
14677 | ||
14678 | ||
14679 | but in some cases it is more efficient. | |
14680 | ||
8925f36f AW |
14681 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadIdentity} is |
14682 | executed between the execution of @code{glBegin} and the corresponding | |
14683 | execution of @code{glEnd}. | |
14684 | ||
bb894c9d | 14685 | @end deftypefun |
8925f36f | 14686 | |
d172eed9 AW |
14687 | @deftypefun void glLoadMatrixd m |
14688 | @deftypefunx void glLoadMatrixf m | |
3c9b6116 AW |
14689 | Replace the current matrix with the specified matrix. |
14690 | ||
8925f36f AW |
14691 | @table @asis |
14692 | @item @var{m} | |
14693 | Specifies a pointer to 16 consecutive values, which are used as the | |
3c9b6116 | 14694 | elements of a @r{4×4} column-major matrix. |
8925f36f AW |
14695 | |
14696 | @end table | |
14697 | ||
8925f36f | 14698 | @code{glLoadMatrix} replaces the current matrix with the one whose |
f37e7e3d | 14699 | elements are specified by @var{m}. The current matrix is the projection |
8925f36f AW |
14700 | matrix, modelview matrix, or texture matrix, depending on the current |
14701 | matrix mode (see @code{glMatrixMode}). | |
14702 | ||
f37e7e3d DH |
14703 | The current matrix, M, defines a transformation of coordinates. For |
14704 | instance, assume M refers to the modelview matrix. If | |
3c9b6116 AW |
14705 | @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the |
14706 | set of object coordinates of a vertex, and @var{m} points to an array of | |
14707 | @r{16} single- or double-precision floating-point values | |
14708 | @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then | |
14709 | the modelview transformation @r{@var{M}(@var{v},)} does the following: | |
8925f36f | 14710 | |
3c9b6116 | 14711 | @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[4,] @var{m}[8,] |
8925f36f AW |
14712 | @var{m}[12,]), (@var{m}[1,] @var{m}[5,] @var{m}[9,] @var{m}[13,]), |
14713 | (@var{m}[2,] @var{m}[6,] @var{m}[10,] @var{m}[14,]), (@var{m}[3,] | |
14714 | @var{m}[7,] @var{m}[11,] @var{m}[15,]),)×((@var{v}[0,]), | |
14715 | (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)} | |
14716 | ||
14717 | ||
14718 | ||
14719 | Projection and texture transformations are similarly defined. | |
14720 | ||
8925f36f AW |
14721 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadMatrix} is |
14722 | executed between the execution of @code{glBegin} and the corresponding | |
14723 | execution of @code{glEnd}. | |
14724 | ||
bb894c9d | 14725 | @end deftypefun |
8925f36f | 14726 | |
bb894c9d | 14727 | @deftypefun void glLoadName name |
3c9b6116 AW |
14728 | Load a name onto the name stack. |
14729 | ||
8925f36f AW |
14730 | @table @asis |
14731 | @item @var{name} | |
14732 | Specifies a name that will replace the top value on the name stack. | |
14733 | ||
14734 | @end table | |
14735 | ||
8925f36f | 14736 | The name stack is used during selection mode to allow sets of rendering |
f37e7e3d | 14737 | commands to be uniquely identified. It consists of an ordered set of |
8925f36f AW |
14738 | unsigned integers and is initially empty. |
14739 | ||
14740 | @code{glLoadName} causes @var{name} to replace the value on the top of | |
14741 | the name stack. | |
14742 | ||
14743 | The name stack is always empty while the render mode is not | |
f37e7e3d | 14744 | @code{GL_SELECT}. Calls to @code{glLoadName} while the render mode is |
8925f36f AW |
14745 | not @code{GL_SELECT} are ignored. |
14746 | ||
8925f36f AW |
14747 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is called |
14748 | while the name stack is empty. | |
14749 | ||
14750 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is | |
14751 | executed between the execution of @code{glBegin} and the corresponding | |
14752 | execution of @code{glEnd}. | |
14753 | ||
bb894c9d | 14754 | @end deftypefun |
8925f36f | 14755 | |
d172eed9 AW |
14756 | @deftypefun void glLoadTransposeMatrixd m |
14757 | @deftypefunx void glLoadTransposeMatrixf m | |
3c9b6116 AW |
14758 | Replace the current matrix with the specified row-major ordered matrix. |
14759 | ||
8925f36f AW |
14760 | @table @asis |
14761 | @item @var{m} | |
14762 | Specifies a pointer to 16 consecutive values, which are used as the | |
3c9b6116 | 14763 | elements of a @r{4×4} row-major matrix. |
8925f36f AW |
14764 | |
14765 | @end table | |
14766 | ||
8925f36f | 14767 | @code{glLoadTransposeMatrix} replaces the current matrix with the one |
f37e7e3d | 14768 | whose elements are specified by @var{m}. The current matrix is the |
8925f36f AW |
14769 | projection matrix, modelview matrix, or texture matrix, depending on the |
14770 | current matrix mode (see @code{glMatrixMode}). | |
14771 | ||
f37e7e3d DH |
14772 | The current matrix, M, defines a transformation of coordinates. For |
14773 | instance, assume M refers to the modelview matrix. If | |
3c9b6116 AW |
14774 | @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the |
14775 | set of object coordinates of a vertex, and @var{m} points to an array of | |
14776 | @r{16} single- or double-precision floating-point values | |
14777 | @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then | |
14778 | the modelview transformation @r{@var{M}(@var{v},)} does the following: | |
8925f36f | 14779 | |
3c9b6116 | 14780 | @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[1,] @var{m}[2,] |
8925f36f AW |
14781 | @var{m}[3,]), (@var{m}[4,] @var{m}[5,] @var{m}[6,] @var{m}[7,]), |
14782 | (@var{m}[8,] @var{m}[9,] @var{m}[10,] @var{m}[11,]), (@var{m}[12,] | |
14783 | @var{m}[13,] @var{m}[14,] @var{m}[15,]),)×((@var{v}[0,]), | |
14784 | (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)} | |
14785 | ||
14786 | ||
14787 | ||
14788 | Projection and texture transformations are similarly defined. | |
14789 | ||
3c9b6116 AW |
14790 | Calling @code{glLoadTransposeMatrix} with matrix @r{@var{M}} is |
14791 | identical in operation to @code{glLoadMatrix} with @r{@var{M}^@var{T}}, | |
14792 | where @r{@var{T}} represents the transpose. | |
8925f36f | 14793 | |
8925f36f AW |
14794 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadTransposeMatrix} |
14795 | is executed between the execution of @code{glBegin} and the | |
14796 | corresponding execution of @code{glEnd}. | |
14797 | ||
bb894c9d | 14798 | @end deftypefun |
8925f36f | 14799 | |
bb894c9d | 14800 | @deftypefun void glLogicOp opcode |
3c9b6116 AW |
14801 | Specify a logical pixel operation for color index rendering. |
14802 | ||
8925f36f AW |
14803 | @table @asis |
14804 | @item @var{opcode} | |
f37e7e3d | 14805 | Specifies a symbolic constant that selects a logical operation. The |
8925f36f AW |
14806 | following symbols are accepted: @code{GL_CLEAR}, @code{GL_SET}, |
14807 | @code{GL_COPY}, @code{GL_COPY_INVERTED}, @code{GL_NOOP}, | |
14808 | @code{GL_INVERT}, @code{GL_AND}, @code{GL_NAND}, @code{GL_OR}, | |
14809 | @code{GL_NOR}, @code{GL_XOR}, @code{GL_EQUIV}, @code{GL_AND_REVERSE}, | |
14810 | @code{GL_AND_INVERTED}, @code{GL_OR_REVERSE}, and @code{GL_OR_INVERTED}. | |
14811 | The initial value is @code{GL_COPY}. | |
14812 | ||
14813 | @end table | |
14814 | ||
8925f36f AW |
14815 | @code{glLogicOp} specifies a logical operation that, when enabled, is |
14816 | applied between the incoming color index or RGBA color and the color | |
14817 | index or RGBA color at the corresponding location in the frame buffer. | |
14818 | To enable or disable the logical operation, call @code{glEnable} and | |
14819 | @code{glDisable} using the symbolic constant @code{GL_COLOR_LOGIC_OP} | |
f37e7e3d | 14820 | for RGBA mode or @code{GL_INDEX_LOGIC_OP} for color index mode. The |
8925f36f AW |
14821 | initial value is disabled for both operations. |
14822 | ||
14823 | ||
14824 | ||
14825 | @table @asis | |
14826 | @item @strong{Opcode} | |
14827 | @strong{Resulting Operation} | |
14828 | ||
14829 | @item @code{GL_CLEAR} | |
14830 | 0 | |
14831 | ||
14832 | @item @code{GL_SET} | |
14833 | 1 | |
14834 | ||
14835 | @item @code{GL_COPY} | |
14836 | s | |
14837 | ||
14838 | @item @code{GL_COPY_INVERTED} | |
14839 | ~s | |
14840 | ||
14841 | @item @code{GL_NOOP} | |
14842 | d | |
14843 | ||
14844 | @item @code{GL_INVERT} | |
14845 | ~d | |
14846 | ||
14847 | @item @code{GL_AND} | |
14848 | s & d | |
14849 | ||
14850 | @item @code{GL_NAND} | |
14851 | ~(s & d) | |
14852 | ||
14853 | @item @code{GL_OR} | |
14854 | s | d | |
14855 | ||
14856 | @item @code{GL_NOR} | |
14857 | ~(s | d) | |
14858 | ||
14859 | @item @code{GL_XOR} | |
14860 | s ^ d | |
14861 | ||
14862 | @item @code{GL_EQUIV} | |
14863 | ~(s ^ d) | |
14864 | ||
14865 | @item @code{GL_AND_REVERSE} | |
14866 | s & ~d | |
14867 | ||
14868 | @item @code{GL_AND_INVERTED} | |
14869 | ~s & d | |
14870 | ||
14871 | @item @code{GL_OR_REVERSE} | |
14872 | s | ~d | |
14873 | ||
14874 | @item @code{GL_OR_INVERTED} | |
14875 | ~s | d | |
14876 | ||
14877 | @end table | |
14878 | ||
f37e7e3d | 14879 | @var{opcode} is a symbolic constant chosen from the list above. In the |
8925f36f AW |
14880 | explanation of the logical operations, @var{s} represents the incoming |
14881 | color index and @var{d} represents the index in the frame buffer. | |
f37e7e3d | 14882 | Standard C-language operators are used. As these bitwise operators |
8925f36f AW |
14883 | suggest, the logical operation is applied independently to each bit pair |
14884 | of the source and destination indices or colors. | |
14885 | ||
8925f36f AW |
14886 | @code{GL_INVALID_ENUM} is generated if @var{opcode} is not an accepted |
14887 | value. | |
14888 | ||
14889 | @code{GL_INVALID_OPERATION} is generated if @code{glLogicOp} is executed | |
14890 | between the execution of @code{glBegin} and the corresponding execution | |
14891 | of @code{glEnd}. | |
14892 | ||
bb894c9d | 14893 | @end deftypefun |
8925f36f | 14894 | |
ca09631c | 14895 | @deftypefun void glMap1f target u1 u2 stride order points |
d172eed9 | 14896 | @deftypefunx void glMap1d target u1 u2 stride order points |
3c9b6116 AW |
14897 | Define a one-dimensional evaluator. |
14898 | ||
8925f36f AW |
14899 | @table @asis |
14900 | @item @var{target} | |
14901 | Specifies the kind of values that are generated by the evaluator. | |
14902 | Symbolic constants @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4}, | |
14903 | @code{GL_MAP1_INDEX}, @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_NORMAL}, | |
14904 | @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2}, | |
14905 | @code{GL_MAP1_TEXTURE_COORD_3}, and @code{GL_MAP1_TEXTURE_COORD_4} are | |
14906 | accepted. | |
14907 | ||
14908 | @item @var{u1} | |
14909 | @itemx @var{u2} | |
3c9b6116 AW |
14910 | Specify a linear mapping of @r{@var{u}}, as presented to |
14911 | @code{glEvalCoord1}, to @r{@var{u}^}, the variable that is evaluated by | |
14912 | the equations specified by this command. | |
8925f36f AW |
14913 | |
14914 | @item @var{stride} | |
14915 | Specifies the number of floats or doubles between the beginning of one | |
14916 | control point and the beginning of the next one in the data structure | |
f37e7e3d DH |
14917 | referenced in @var{points}. This allows control points to be embedded in |
14918 | arbitrary data structures. The only constraint is that the values for a | |
14919 | particular control point must occupy contiguous memory locations. | |
8925f36f AW |
14920 | |
14921 | @item @var{order} | |
f37e7e3d | 14922 | Specifies the number of control points. Must be positive. |
8925f36f AW |
14923 | |
14924 | @item @var{points} | |
14925 | Specifies a pointer to the array of control points. | |
14926 | ||
14927 | @end table | |
14928 | ||
8925f36f AW |
14929 | Evaluators provide a way to use polynomial or rational polynomial |
14930 | mapping to produce vertices, normals, texture coordinates, and colors. | |
14931 | The values produced by an evaluator are sent to further stages of GL | |
14932 | processing just as if they had been presented using @code{glVertex}, | |
14933 | @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except | |
14934 | that the generated values do not update the current normal, texture | |
14935 | coordinates, or color. | |
14936 | ||
14937 | All polynomial or rational polynomial splines of any degree (up to the | |
14938 | maximum degree supported by the GL implementation) can be described | |
f37e7e3d | 14939 | using evaluators. These include almost all splines used in computer |
8925f36f AW |
14940 | graphics: B-splines, Bezier curves, Hermite splines, and so on. |
14941 | ||
f37e7e3d | 14942 | Evaluators define curves based on Bernstein polynomials. Define |
3c9b6116 | 14943 | @r{@var{p}(@var{u}^,)} as |
8925f36f | 14944 | |
3c9b6116 | 14945 | @r{@var{p}(@var{u}^,)=Σ@var{i}=0@var{n}@var{B}_@var{i},^@var{n}(@var{u}^,)@var{R}_@var{i}} |
8925f36f AW |
14946 | |
14947 | ||
14948 | ||
3c9b6116 AW |
14949 | where @r{@var{R}_@var{i}} is a control point and |
14950 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein | |
14951 | polynomial of degree @r{@var{n}} (@var{order} = @r{@var{n}+1}): | |
8925f36f | 14952 | |
3c9b6116 | 14953 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}), |
8925f36f AW |
14954 | (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,} |
14955 | ||
14956 | Recall that | |
14957 | ||
3c9b6116 | 14958 | @r{0^0==1} and @r{((@var{n}), (0),,)==1} |
8925f36f AW |
14959 | |
14960 | @code{glMap1} is used to define the basis and to specify what kind of | |
f37e7e3d | 14961 | values are produced. Once defined, a map can be enabled and disabled by |
8925f36f AW |
14962 | calling @code{glEnable} and @code{glDisable} with the map name, one of |
14963 | the nine predefined values for @var{target} described below. | |
14964 | @code{glEvalCoord1} evaluates the one-dimensional maps that are enabled. | |
3c9b6116 AW |
14965 | When @code{glEvalCoord1} presents a value @r{@var{u}}, the Bernstein |
14966 | functions are evaluated using @r{@var{u}^}, where | |
14967 | @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},} | |
8925f36f AW |
14968 | |
14969 | @var{target} is a symbolic constant that indicates what kind of control | |
14970 | points are provided in @var{points}, and what output is generated when | |
f37e7e3d | 14971 | the map is evaluated. It can assume one of nine predefined values: |
8925f36f AW |
14972 | |
14973 | @table @asis | |
14974 | @item @code{GL_MAP1_VERTEX_3} | |
14975 | Each control point is three floating-point values representing | |
f37e7e3d | 14976 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3} |
3c9b6116 | 14977 | commands are generated when the map is evaluated. |
8925f36f AW |
14978 | |
14979 | @item @code{GL_MAP1_VERTEX_4} | |
14980 | Each control point is four floating-point values representing | |
f37e7e3d | 14981 | @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal |
3c9b6116 | 14982 | @code{glVertex4} commands are generated when the map is evaluated. |
8925f36f AW |
14983 | |
14984 | @item @code{GL_MAP1_INDEX} | |
14985 | Each control point is a single floating-point value representing a color | |
f37e7e3d | 14986 | index. Internal @code{glIndex} commands are generated when the map is |
8925f36f AW |
14987 | evaluated but the current index is not updated with the value of these |
14988 | @code{glIndex} commands. | |
14989 | ||
14990 | @item @code{GL_MAP1_COLOR_4} | |
14991 | Each control point is four floating-point values representing red, | |
f37e7e3d | 14992 | green, blue, and alpha. Internal @code{glColor4} commands are generated |
8925f36f AW |
14993 | when the map is evaluated but the current color is not updated with the |
14994 | value of these @code{glColor4} commands. | |
14995 | ||
14996 | @item @code{GL_MAP1_NORMAL} | |
14997 | Each control point is three floating-point values representing the | |
3c9b6116 AW |
14998 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector. |
14999 | Internal @code{glNormal} commands are generated when the map is | |
15000 | evaluated but the current normal is not updated with the value of these | |
15001 | @code{glNormal} commands. | |
8925f36f AW |
15002 | |
15003 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
15004 | Each control point is a single floating-point value representing the | |
f37e7e3d DH |
15005 | @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands are |
15006 | generated when the map is evaluated but the current texture coordinates | |
15007 | are not updated with the value of these @code{glTexCoord} commands. | |
8925f36f AW |
15008 | |
15009 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
15010 | Each control point is two floating-point values representing the | |
f37e7e3d | 15011 | @r{@var{s}} and @r{@var{t}} texture coordinates. Internal |
8925f36f AW |
15012 | @code{glTexCoord2} commands are generated when the map is evaluated but |
15013 | the current texture coordinates are not updated with the value of these | |
15014 | @code{glTexCoord} commands. | |
15015 | ||
15016 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
15017 | Each control point is three floating-point values representing the | |
f37e7e3d | 15018 | @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal |
3c9b6116 AW |
15019 | @code{glTexCoord3} commands are generated when the map is evaluated but |
15020 | the current texture coordinates are not updated with the value of these | |
15021 | @code{glTexCoord} commands. | |
8925f36f AW |
15022 | |
15023 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
15024 | Each control point is four floating-point values representing the | |
3c9b6116 | 15025 | @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture |
f37e7e3d DH |
15026 | coordinates. Internal @code{glTexCoord4} commands are generated when the |
15027 | map is evaluated but the current texture coordinates are not updated | |
3c9b6116 | 15028 | with the value of these @code{glTexCoord} commands. |
8925f36f AW |
15029 | |
15030 | @end table | |
15031 | ||
15032 | @var{stride}, @var{order}, and @var{points} define the array addressing | |
f37e7e3d | 15033 | for accessing the control points. @var{points} is the location of the |
8925f36f | 15034 | first control point, which occupies one, two, three, or four contiguous |
f37e7e3d DH |
15035 | memory locations, depending on which map is being defined. @var{order} |
15036 | is the number of control points in the array. @var{stride} specifies how | |
15037 | many float or double locations to advance the internal memory pointer to | |
15038 | reach the next control point. | |
8925f36f | 15039 | |
8925f36f AW |
15040 | @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted |
15041 | value. | |
15042 | ||
15043 | @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2}. | |
15044 | ||
15045 | @code{GL_INVALID_VALUE} is generated if @var{stride} is less than the | |
15046 | number of values in a control point. | |
15047 | ||
15048 | @code{GL_INVALID_VALUE} is generated if @var{order} is less than 1 or | |
15049 | greater than the return value of @code{GL_MAX_EVAL_ORDER}. | |
15050 | ||
15051 | @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is executed | |
15052 | between the execution of @code{glBegin} and the corresponding execution | |
15053 | of @code{glEnd}. | |
15054 | ||
15055 | @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is called and | |
15056 | the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}. | |
15057 | ||
bb894c9d | 15058 | @end deftypefun |
8925f36f | 15059 | |
ca09631c | 15060 | @deftypefun void glMap2f target u1 u2 ustride uorder v1 v2 vstride vorder points |
d172eed9 | 15061 | @deftypefunx void glMap2d target u1 u2 ustride uorder v1 v2 vstride vorder points |
3c9b6116 AW |
15062 | Define a two-dimensional evaluator. |
15063 | ||
8925f36f AW |
15064 | @table @asis |
15065 | @item @var{target} | |
15066 | Specifies the kind of values that are generated by the evaluator. | |
15067 | Symbolic constants @code{GL_MAP2_VERTEX_3}, @code{GL_MAP2_VERTEX_4}, | |
15068 | @code{GL_MAP2_INDEX}, @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_NORMAL}, | |
15069 | @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2}, | |
15070 | @code{GL_MAP2_TEXTURE_COORD_3}, and @code{GL_MAP2_TEXTURE_COORD_4} are | |
15071 | accepted. | |
15072 | ||
15073 | @item @var{u1} | |
15074 | @itemx @var{u2} | |
3c9b6116 AW |
15075 | Specify a linear mapping of @r{@var{u}}, as presented to |
15076 | @code{glEvalCoord2}, to @r{@var{u}^}, one of the two variables that are | |
f37e7e3d | 15077 | evaluated by the equations specified by this command. Initially, |
8925f36f AW |
15078 | @var{u1} is 0 and @var{u2} is 1. |
15079 | ||
15080 | @item @var{ustride} | |
15081 | Specifies the number of floats or doubles between the beginning of | |
3c9b6116 AW |
15082 | control point @r{@var{R}_@var{ij}} and the beginning of control point |
15083 | @r{@var{R}_(@var{i}+1,)@var{j},}, where @r{@var{i}} and @r{@var{j}} are | |
15084 | the @r{@var{u}} and @r{@var{v}} control point indices, respectively. | |
15085 | This allows control points to be embedded in arbitrary data structures. | |
15086 | The only constraint is that the values for a particular control point | |
f37e7e3d | 15087 | must occupy contiguous memory locations. The initial value of |
3c9b6116 | 15088 | @var{ustride} is 0. |
8925f36f AW |
15089 | |
15090 | @item @var{uorder} | |
3c9b6116 | 15091 | Specifies the dimension of the control point array in the @r{@var{u}} |
f37e7e3d | 15092 | axis. Must be positive. The initial value is 1. |
8925f36f AW |
15093 | |
15094 | @item @var{v1} | |
15095 | @itemx @var{v2} | |
3c9b6116 AW |
15096 | Specify a linear mapping of @r{@var{v}}, as presented to |
15097 | @code{glEvalCoord2}, to @r{@var{v}^}, one of the two variables that are | |
f37e7e3d | 15098 | evaluated by the equations specified by this command. Initially, |
8925f36f AW |
15099 | @var{v1} is 0 and @var{v2} is 1. |
15100 | ||
15101 | @item @var{vstride} | |
15102 | Specifies the number of floats or doubles between the beginning of | |
3c9b6116 AW |
15103 | control point @r{@var{R}_@var{ij}} and the beginning of control point |
15104 | @r{@var{R}_@var{i}(@var{j}+1,),}, where @r{@var{i}} and @r{@var{j}} are | |
15105 | the @r{@var{u}} and @r{@var{v}} control point indices, respectively. | |
15106 | This allows control points to be embedded in arbitrary data structures. | |
15107 | The only constraint is that the values for a particular control point | |
f37e7e3d | 15108 | must occupy contiguous memory locations. The initial value of |
3c9b6116 | 15109 | @var{vstride} is 0. |
8925f36f AW |
15110 | |
15111 | @item @var{vorder} | |
3c9b6116 | 15112 | Specifies the dimension of the control point array in the @r{@var{v}} |
f37e7e3d | 15113 | axis. Must be positive. The initial value is 1. |
8925f36f AW |
15114 | |
15115 | @item @var{points} | |
15116 | Specifies a pointer to the array of control points. | |
15117 | ||
15118 | @end table | |
15119 | ||
8925f36f AW |
15120 | Evaluators provide a way to use polynomial or rational polynomial |
15121 | mapping to produce vertices, normals, texture coordinates, and colors. | |
15122 | The values produced by an evaluator are sent on to further stages of GL | |
15123 | processing just as if they had been presented using @code{glVertex}, | |
15124 | @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except | |
15125 | that the generated values do not update the current normal, texture | |
15126 | coordinates, or color. | |
15127 | ||
15128 | All polynomial or rational polynomial splines of any degree (up to the | |
15129 | maximum degree supported by the GL implementation) can be described | |
f37e7e3d | 15130 | using evaluators. These include almost all surfaces used in computer |
8925f36f AW |
15131 | graphics, including B-spline surfaces, NURBS surfaces, Bezier surfaces, |
15132 | and so on. | |
15133 | ||
15134 | Evaluators define surfaces based on bivariate Bernstein polynomials. | |
3c9b6116 | 15135 | Define @r{@var{p}(@var{u}^,@var{v}^)} as |
8925f36f | 15136 | |
3c9b6116 | 15137 | @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 |
15138 | |
15139 | ||
15140 | ||
3c9b6116 AW |
15141 | where @r{@var{R}_@var{ij}} is a control point, |
15142 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein | |
15143 | polynomial of degree @r{@var{n}} (@var{uorder} = @r{@var{n}+1}) | |
8925f36f | 15144 | |
3c9b6116 | 15145 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}), |
8925f36f AW |
15146 | (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,} |
15147 | ||
3c9b6116 AW |
15148 | and @r{@var{B}_@var{j},^@var{m}(@var{v}^,)} is the @r{@var{j}}th |
15149 | Bernstein polynomial of degree @r{@var{m}} (@var{vorder} = | |
15150 | @r{@var{m}+1}) | |
8925f36f | 15151 | |
3c9b6116 | 15152 | @r{@var{B}_@var{j},^@var{m}(@var{v}^,)=((@var{m}), |
8925f36f AW |
15153 | (@var{j}),,)@var{v}^,^@var{j}(1-@var{v}^,)^@var{m}-@var{j},,} |
15154 | ||
3c9b6116 | 15155 | Recall that @r{0^0==1} and @r{((@var{n}), (0),,)==1} |
8925f36f AW |
15156 | |
15157 | @code{glMap2} is used to define the basis and to specify what kind of | |
f37e7e3d | 15158 | values are produced. Once defined, a map can be enabled and disabled by |
8925f36f | 15159 | calling @code{glEnable} and @code{glDisable} with the map name, one of |
f37e7e3d | 15160 | the nine predefined values for @var{target}, described below. When |
3c9b6116 AW |
15161 | @code{glEvalCoord2} presents values @r{@var{u}} and @r{@var{v}}, the |
15162 | bivariate Bernstein polynomials are evaluated using @r{@var{u}^} and | |
15163 | @r{@var{v}^}, where | |
8925f36f | 15164 | |
3c9b6116 | 15165 | @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},} |
8925f36f | 15166 | |
3c9b6116 | 15167 | @r{@var{v}^=@var{v}-@var{v1},/@var{v2}-@var{v1},} |
8925f36f AW |
15168 | |
15169 | @var{target} is a symbolic constant that indicates what kind of control | |
15170 | points are provided in @var{points}, and what output is generated when | |
f37e7e3d | 15171 | the map is evaluated. It can assume one of nine predefined values: |
8925f36f AW |
15172 | |
15173 | @table @asis | |
15174 | @item @code{GL_MAP2_VERTEX_3} | |
15175 | Each control point is three floating-point values representing | |
f37e7e3d | 15176 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3} |
3c9b6116 | 15177 | commands are generated when the map is evaluated. |
8925f36f AW |
15178 | |
15179 | @item @code{GL_MAP2_VERTEX_4} | |
15180 | Each control point is four floating-point values representing | |
f37e7e3d | 15181 | @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal |
3c9b6116 | 15182 | @code{glVertex4} commands are generated when the map is evaluated. |
8925f36f AW |
15183 | |
15184 | @item @code{GL_MAP2_INDEX} | |
15185 | Each control point is a single floating-point value representing a color | |
f37e7e3d | 15186 | index. Internal @code{glIndex} commands are generated when the map is |
8925f36f AW |
15187 | evaluated but the current index is not updated with the value of these |
15188 | @code{glIndex} commands. | |
15189 | ||
15190 | @item @code{GL_MAP2_COLOR_4} | |
15191 | Each control point is four floating-point values representing red, | |
f37e7e3d | 15192 | green, blue, and alpha. Internal @code{glColor4} commands are generated |
8925f36f AW |
15193 | when the map is evaluated but the current color is not updated with the |
15194 | value of these @code{glColor4} commands. | |
15195 | ||
15196 | @item @code{GL_MAP2_NORMAL} | |
15197 | Each control point is three floating-point values representing the | |
3c9b6116 AW |
15198 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector. |
15199 | Internal @code{glNormal} commands are generated when the map is | |
15200 | evaluated but the current normal is not updated with the value of these | |
15201 | @code{glNormal} commands. | |
8925f36f AW |
15202 | |
15203 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
15204 | Each control point is a single floating-point value representing the | |
f37e7e3d DH |
15205 | @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands are |
15206 | generated when the map is evaluated but the current texture coordinates | |
15207 | are not updated with the value of these @code{glTexCoord} commands. | |
8925f36f AW |
15208 | |
15209 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
15210 | Each control point is two floating-point values representing the | |
f37e7e3d | 15211 | @r{@var{s}} and @r{@var{t}} texture coordinates. Internal |
8925f36f AW |
15212 | @code{glTexCoord2} commands are generated when the map is evaluated but |
15213 | the current texture coordinates are not updated with the value of these | |
15214 | @code{glTexCoord} commands. | |
15215 | ||
15216 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
15217 | Each control point is three floating-point values representing the | |
f37e7e3d | 15218 | @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal |
3c9b6116 AW |
15219 | @code{glTexCoord3} commands are generated when the map is evaluated but |
15220 | the current texture coordinates are not updated with the value of these | |
15221 | @code{glTexCoord} commands. | |
8925f36f AW |
15222 | |
15223 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
15224 | Each control point is four floating-point values representing the | |
3c9b6116 | 15225 | @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture |
f37e7e3d DH |
15226 | coordinates. Internal @code{glTexCoord4} commands are generated when the |
15227 | map is evaluated but the current texture coordinates are not updated | |
3c9b6116 | 15228 | with the value of these @code{glTexCoord} commands. |
8925f36f AW |
15229 | |
15230 | @end table | |
15231 | ||
15232 | @var{ustride}, @var{uorder}, @var{vstride}, @var{vorder}, and | |
15233 | @var{points} define the array addressing for accessing the control | |
f37e7e3d | 15234 | points. @var{points} is the location of the first control point, which |
8925f36f | 15235 | occupies one, two, three, or four contiguous memory locations, depending |
f37e7e3d DH |
15236 | on which map is being defined. There are @r{@var{uorder}×@var{vorder}} |
15237 | control points in the array. @var{ustride} specifies how many float or | |
3c9b6116 AW |
15238 | double locations are skipped to advance the internal memory pointer from |
15239 | control point @r{@var{R}_@var{i}@var{j},} to control point | |
f37e7e3d | 15240 | @r{@var{R}_(@var{i}+1,)@var{j},}. @var{vstride} specifies how many |
8925f36f | 15241 | float or double locations are skipped to advance the internal memory |
3c9b6116 AW |
15242 | pointer from control point @r{@var{R}_@var{i}@var{j},} to control point |
15243 | @r{@var{R}_@var{i}(@var{j}+1,),}. | |
8925f36f | 15244 | |
8925f36f AW |
15245 | @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted |
15246 | value. | |
15247 | ||
15248 | @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2}, | |
15249 | or if @var{v1} is equal to @var{v2}. | |
15250 | ||
15251 | @code{GL_INVALID_VALUE} is generated if either @var{ustride} or | |
15252 | @var{vstride} is less than the number of values in a control point. | |
15253 | ||
15254 | @code{GL_INVALID_VALUE} is generated if either @var{uorder} or | |
15255 | @var{vorder} is less than 1 or greater than the return value of | |
15256 | @code{GL_MAX_EVAL_ORDER}. | |
15257 | ||
15258 | @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is executed | |
15259 | between the execution of @code{glBegin} and the corresponding execution | |
15260 | of @code{glEnd}. | |
15261 | ||
15262 | @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is called and | |
15263 | the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}. | |
15264 | ||
bb894c9d | 15265 | @end deftypefun |
8925f36f | 15266 | |
00239761 | 15267 | @deftypefun void-* glMapBuffer target access |
bb894c9d | 15268 | @deftypefunx GLboolean glUnmapBuffer target |
3c9b6116 AW |
15269 | Map a buffer object's data store. |
15270 | ||
8925f36f AW |
15271 | @table @asis |
15272 | @item @var{target} | |
f37e7e3d | 15273 | Specifies the target buffer object being mapped. The symbolic constant |
8925f36f AW |
15274 | must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
15275 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
15276 | ||
15277 | @item @var{access} | |
15278 | Specifies the access policy, indicating whether it will be possible to | |
15279 | read from, write to, or both read from and write to the buffer object's | |
f37e7e3d | 15280 | mapped data store. The symbolic constant must be @code{GL_READ_ONLY}, |
8925f36f AW |
15281 | @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}. |
15282 | ||
15283 | @end table | |
15284 | ||
8925f36f | 15285 | @code{glMapBuffer} maps to the client's address space the entire data |
f37e7e3d DH |
15286 | store of the buffer object currently bound to @var{target}. The data can |
15287 | then be directly read and/or written relative to the returned pointer, | |
15288 | depending on the specified @var{access} policy. If the GL is unable to | |
15289 | map the buffer object's data store, @code{glMapBuffer} generates an | |
15290 | error and returns @code{NULL}. This may occur for system-specific | |
15291 | reasons, such as low virtual memory availability. | |
8925f36f AW |
15292 | |
15293 | If a mapped data store is accessed in a way inconsistent with the | |
15294 | specified @var{access} policy, no error is generated, but performance | |
15295 | may be negatively impacted and system errors, including program | |
f37e7e3d | 15296 | termination, may result. Unlike the @var{usage} parameter of |
8925f36f AW |
15297 | @code{glBufferData}, @var{access} is not a hint, and does in fact |
15298 | constrain the usage of the mapped data store on some GL implementations. | |
15299 | In order to achieve the highest performance available, a buffer object's | |
15300 | data store should be used in ways consistent with both its specified | |
15301 | @var{usage} and @var{access} parameters. | |
15302 | ||
15303 | A mapped data store must be unmapped with @code{glUnmapBuffer} before | |
f37e7e3d | 15304 | its buffer object is used. Otherwise an error will be generated by any |
8925f36f AW |
15305 | GL command that attempts to dereference the buffer object's data store. |
15306 | When a data store is unmapped, the pointer to its data store becomes | |
f37e7e3d | 15307 | invalid. @code{glUnmapBuffer} returns @code{GL_TRUE} unless the data |
8925f36f | 15308 | store contents have become corrupt during the time the data store was |
f37e7e3d DH |
15309 | mapped. This can occur for system-specific reasons that affect the |
15310 | availability of graphics memory, such as screen mode changes. In such | |
8925f36f | 15311 | situations, @code{GL_FALSE} is returned and the data store contents are |
f37e7e3d | 15312 | undefined. An application must detect this rare condition and |
8925f36f AW |
15313 | reinitialize the data store. |
15314 | ||
15315 | A buffer object's mapped data store is automatically unmapped when the | |
15316 | buffer object is deleted or its data store is recreated with | |
15317 | @code{glBufferData}. | |
15318 | ||
8925f36f AW |
15319 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
15320 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
15321 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
15322 | ||
15323 | @code{GL_INVALID_ENUM} is generated if @var{access} is not | |
15324 | @code{GL_READ_ONLY}, @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}. | |
15325 | ||
15326 | @code{GL_OUT_OF_MEMORY} is generated when @code{glMapBuffer} is executed | |
f37e7e3d | 15327 | if the GL is unable to map the buffer object's data store. This may |
8925f36f AW |
15328 | occur for a variety of system-specific reasons, such as the absence of |
15329 | sufficient remaining virtual memory. | |
15330 | ||
15331 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
15332 | name 0 is bound to @var{target}. | |
15333 | ||
15334 | @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} is | |
15335 | executed for a buffer object whose data store is already mapped. | |
15336 | ||
15337 | @code{GL_INVALID_OPERATION} is generated if @code{glUnmapBuffer} is | |
15338 | executed for a buffer object whose data store is not currently mapped. | |
15339 | ||
15340 | @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} or | |
15341 | @code{glUnmapBuffer} is executed between the execution of @code{glBegin} | |
15342 | and the corresponding execution of @code{glEnd}. | |
15343 | ||
bb894c9d | 15344 | @end deftypefun |
8925f36f | 15345 | |
d172eed9 AW |
15346 | @deftypefun void glMapGrid1d un u1 u2 |
15347 | @deftypefunx void glMapGrid1f un u1 u2 | |
15348 | @deftypefunx void glMapGrid2d un u1 u2 vn v1 v2 | |
ca09631c | 15349 | @deftypefunx void glMapGrid2f un u1 u2 vn v1 v2 |
3c9b6116 AW |
15350 | Define a one- or two-dimensional mesh. |
15351 | ||
8925f36f AW |
15352 | @table @asis |
15353 | @item @var{un} | |
15354 | Specifies the number of partitions in the grid range interval [@var{u1}, | |
f37e7e3d | 15355 | @var{u2}]. Must be positive. |
8925f36f AW |
15356 | |
15357 | @item @var{u1} | |
15358 | @itemx @var{u2} | |
3c9b6116 AW |
15359 | Specify the mappings for integer grid domain values @r{@var{i}=0} and |
15360 | @r{@var{i}=@var{un}}. | |
8925f36f AW |
15361 | |
15362 | @item @var{vn} | |
15363 | Specifies the number of partitions in the grid range interval [@var{v1}, | |
15364 | @var{v2}] (@code{glMapGrid2} only). | |
15365 | ||
15366 | @item @var{v1} | |
15367 | @itemx @var{v2} | |
3c9b6116 AW |
15368 | Specify the mappings for integer grid domain values @r{@var{j}=0} and |
15369 | @r{@var{j}=@var{vn}} (@code{glMapGrid2} only). | |
8925f36f AW |
15370 | |
15371 | @end table | |
15372 | ||
8925f36f AW |
15373 | @code{glMapGrid} and @code{glEvalMesh} are used together to efficiently |
15374 | generate and evaluate a series of evenly-spaced map domain values. | |
15375 | @code{glEvalMesh} steps through the integer domain of a one- or | |
15376 | two-dimensional grid, whose range is the domain of the evaluation maps | |
15377 | specified by @code{glMap1} and @code{glMap2}. | |
15378 | ||
15379 | @code{glMapGrid1} and @code{glMapGrid2} specify the linear grid mappings | |
3c9b6116 AW |
15380 | between the @r{@var{i}} (or @r{@var{i}} and @r{@var{j}}) integer grid |
15381 | coordinates, to the @r{@var{u}} (or @r{@var{u}} and @r{@var{v}}) | |
f37e7e3d | 15382 | floating-point evaluation map coordinates. See @code{glMap1} and |
3c9b6116 AW |
15383 | @code{glMap2} for details of how @r{@var{u}} and @r{@var{v}} coordinates |
15384 | are evaluated. | |
8925f36f AW |
15385 | |
15386 | @code{glMapGrid1} specifies a single linear mapping such that integer | |
15387 | grid coordinate 0 maps exactly to @var{u1}, and integer grid coordinate | |
f37e7e3d | 15388 | @var{un} maps exactly to @var{u2}. All other integer grid coordinates |
3c9b6116 | 15389 | @r{@var{i}} are mapped so that |
8925f36f | 15390 | |
3c9b6116 | 15391 | @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}} |
8925f36f | 15392 | |
f37e7e3d | 15393 | @code{glMapGrid2} specifies two such linear mappings. One maps integer |
3c9b6116 | 15394 | grid coordinate @r{@var{i}=0} exactly to @var{u1}, and integer grid |
f37e7e3d | 15395 | coordinate @r{@var{i}=@var{un}} exactly to @var{u2}. The other maps |
3c9b6116 | 15396 | integer grid coordinate @r{@var{j}=0} exactly to @var{v1}, and integer |
f37e7e3d | 15397 | grid coordinate @r{@var{j}=@var{vn}} exactly to @var{v2}. Other integer |
3c9b6116 | 15398 | grid coordinates @r{@var{i}} and @r{@var{j}} are mapped such that |
8925f36f | 15399 | |
3c9b6116 | 15400 | @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}} |
8925f36f | 15401 | |
3c9b6116 | 15402 | @r{@var{v}=@var{j}(@var{v2}-@var{v1},)/@var{vn}+@var{v1}} |
8925f36f AW |
15403 | |
15404 | The mappings specified by @code{glMapGrid} are used identically by | |
15405 | @code{glEvalMesh} and @code{glEvalPoint}. | |
15406 | ||
8925f36f AW |
15407 | @code{GL_INVALID_VALUE} is generated if either @var{un} or @var{vn} is |
15408 | not positive. | |
15409 | ||
15410 | @code{GL_INVALID_OPERATION} is generated if @code{glMapGrid} is executed | |
15411 | between the execution of @code{glBegin} and the corresponding execution | |
15412 | of @code{glEnd}. | |
15413 | ||
bb894c9d | 15414 | @end deftypefun |
8925f36f | 15415 | |
bb894c9d AW |
15416 | @deftypefun void glMaterialf face pname param |
15417 | @deftypefunx void glMateriali face pname param | |
d172eed9 AW |
15418 | @deftypefunx void glMaterialfv face pname params |
15419 | @deftypefunx void glMaterialiv face pname params | |
3c9b6116 AW |
15420 | Specify material parameters for the lighting model. |
15421 | ||
8925f36f AW |
15422 | @table @asis |
15423 | @item @var{face} | |
f37e7e3d | 15424 | Specifies which face or faces are being updated. Must be one of |
8925f36f AW |
15425 | @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}. |
15426 | ||
15427 | @item @var{pname} | |
15428 | Specifies the single-valued material parameter of the face or faces that | |
f37e7e3d | 15429 | is being updated. Must be @code{GL_SHININESS}. |
8925f36f AW |
15430 | |
15431 | @item @var{param} | |
15432 | Specifies the value that parameter @code{GL_SHININESS} will be set to. | |
15433 | ||
15434 | @end table | |
15435 | ||
f37e7e3d DH |
15436 | @code{glMaterial} assigns values to material parameters. There are two |
15437 | matched sets of material parameters. One, the @var{front-facing} set, is | |
15438 | used to shade points, lines, bitmaps, and all polygons (when two-sided | |
15439 | lighting is disabled), or just front-facing polygons (when two-sided | |
15440 | lighting is enabled). The other set, @var{back-facing}, is used to shade | |
15441 | back-facing polygons only when two-sided lighting is enabled. Refer to | |
15442 | the @code{glLightModel} reference page for details concerning one- and | |
15443 | two-sided lighting calculations. | |
8925f36f | 15444 | |
f37e7e3d | 15445 | @code{glMaterial} takes three arguments. The first, @var{face}, |
8925f36f AW |
15446 | specifies whether the @code{GL_FRONT} materials, the @code{GL_BACK} |
15447 | materials, or both @code{GL_FRONT_AND_BACK} materials will be modified. | |
15448 | The second, @var{pname}, specifies which of several parameters in one or | |
f37e7e3d | 15449 | both sets will be modified. The third, @var{params}, specifies what |
8925f36f AW |
15450 | value or values will be assigned to the specified parameter. |
15451 | ||
15452 | Material parameters are used in the lighting equation that is optionally | |
f37e7e3d DH |
15453 | applied to each vertex. The equation is discussed in the |
15454 | @code{glLightModel} reference page. The parameters that can be specified | |
15455 | using @code{glMaterial}, and their interpretations by the lighting | |
15456 | equation, are as follows: | |
8925f36f AW |
15457 | |
15458 | @table @asis | |
15459 | @item @code{GL_AMBIENT} | |
15460 | @var{params} contains four integer or floating-point values that specify | |
f37e7e3d | 15461 | the ambient RGBA reflectance of the material. Integer values are mapped |
8925f36f | 15462 | linearly such that the most positive representable value maps to 1.0, |
3c9b6116 | 15463 | and the most negative representable value maps to @r{-1.0}. |
f37e7e3d DH |
15464 | Floating-point values are mapped directly. Neither integer nor |
15465 | floating-point values are clamped. The initial ambient reflectance for | |
8925f36f AW |
15466 | both front- and back-facing materials is (0.2, 0.2, 0.2, 1.0). |
15467 | ||
15468 | @item @code{GL_DIFFUSE} | |
15469 | @var{params} contains four integer or floating-point values that specify | |
f37e7e3d | 15470 | the diffuse RGBA reflectance of the material. Integer values are mapped |
8925f36f | 15471 | linearly such that the most positive representable value maps to 1.0, |
3c9b6116 | 15472 | and the most negative representable value maps to @r{-1.0}. |
f37e7e3d DH |
15473 | Floating-point values are mapped directly. Neither integer nor |
15474 | floating-point values are clamped. The initial diffuse reflectance for | |
8925f36f AW |
15475 | both front- and back-facing materials is (0.8, 0.8, 0.8, 1.0). |
15476 | ||
15477 | @item @code{GL_SPECULAR} | |
15478 | @var{params} contains four integer or floating-point values that specify | |
f37e7e3d DH |
15479 | the specular RGBA reflectance of the material. Integer values are mapped |
15480 | linearly such that the most positive representable value maps to 1.0, | |
15481 | and the most negative representable value maps to @r{-1.0}. | |
15482 | Floating-point values are mapped directly. Neither integer nor | |
15483 | floating-point values are clamped. The initial specular reflectance for | |
8925f36f AW |
15484 | both front- and back-facing materials is (0, 0, 0, 1). |
15485 | ||
15486 | @item @code{GL_EMISSION} | |
15487 | @var{params} contains four integer or floating-point values that specify | |
f37e7e3d | 15488 | the RGBA emitted light intensity of the material. Integer values are |
8925f36f | 15489 | mapped linearly such that the most positive representable value maps to |
3c9b6116 | 15490 | 1.0, and the most negative representable value maps to @r{-1.0}. |
f37e7e3d DH |
15491 | Floating-point values are mapped directly. Neither integer nor |
15492 | floating-point values are clamped. The initial emission intensity for | |
8925f36f AW |
15493 | both front- and back-facing materials is (0, 0, 0, 1). |
15494 | ||
15495 | @item @code{GL_SHININESS} | |
15496 | @var{params} is a single integer or floating-point value that specifies | |
f37e7e3d DH |
15497 | the RGBA specular exponent of the material. Integer and floating-point |
15498 | values are mapped directly. Only values in the range @r{[0,128]} are | |
15499 | accepted. The initial specular exponent for both front- and back-facing | |
8925f36f AW |
15500 | materials is 0. |
15501 | ||
15502 | @item @code{GL_AMBIENT_AND_DIFFUSE} | |
15503 | Equivalent to calling @code{glMaterial} twice with the same parameter | |
15504 | values, once with @code{GL_AMBIENT} and once with @code{GL_DIFFUSE}. | |
15505 | ||
15506 | @item @code{GL_COLOR_INDEXES} | |
15507 | @var{params} contains three integer or floating-point values specifying | |
f37e7e3d | 15508 | the color indices for ambient, diffuse, and specular lighting. These |
8925f36f | 15509 | three values, and @code{GL_SHININESS}, are the only material values used |
f37e7e3d | 15510 | by the color index mode lighting equation. Refer to the |
8925f36f AW |
15511 | @code{glLightModel} reference page for a discussion of color index |
15512 | lighting. | |
15513 | ||
15514 | @end table | |
15515 | ||
8925f36f AW |
15516 | @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{pname} |
15517 | is not an accepted value. | |
15518 | ||
15519 | @code{GL_INVALID_VALUE} is generated if a specular exponent outside the | |
3c9b6116 | 15520 | range @r{[0,128]} is specified. |
8925f36f | 15521 | |
bb894c9d | 15522 | @end deftypefun |
8925f36f | 15523 | |
bb894c9d | 15524 | @deftypefun void glMatrixMode mode |
3c9b6116 AW |
15525 | Specify which matrix is the current matrix. |
15526 | ||
8925f36f AW |
15527 | @table @asis |
15528 | @item @var{mode} | |
15529 | Specifies which matrix stack is the target for subsequent matrix | |
f37e7e3d DH |
15530 | operations. Three values are accepted: @code{GL_MODELVIEW}, |
15531 | @code{GL_PROJECTION}, and @code{GL_TEXTURE}. The initial value is | |
15532 | @code{GL_MODELVIEW}. Additionally, if the @code{ARB_imaging} extension | |
8925f36f AW |
15533 | is supported, @code{GL_COLOR} is also accepted. |
15534 | ||
15535 | @end table | |
15536 | ||
f37e7e3d | 15537 | @code{glMatrixMode} sets the current matrix mode. @var{mode} can assume |
8925f36f AW |
15538 | one of four values: |
15539 | ||
15540 | @table @asis | |
15541 | @item @code{GL_MODELVIEW} | |
15542 | Applies subsequent matrix operations to the modelview matrix stack. | |
15543 | ||
15544 | @item @code{GL_PROJECTION} | |
15545 | Applies subsequent matrix operations to the projection matrix stack. | |
15546 | ||
15547 | @item @code{GL_TEXTURE} | |
15548 | Applies subsequent matrix operations to the texture matrix stack. | |
15549 | ||
15550 | @item @code{GL_COLOR} | |
15551 | Applies subsequent matrix operations to the color matrix stack. | |
15552 | ||
15553 | @end table | |
15554 | ||
15555 | To find out which matrix stack is currently the target of all matrix | |
f37e7e3d | 15556 | operations, call @code{glGet} with argument @code{GL_MATRIX_MODE}. The |
8925f36f AW |
15557 | initial value is @code{GL_MODELVIEW}. |
15558 | ||
8925f36f AW |
15559 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
15560 | value. | |
15561 | ||
15562 | @code{GL_INVALID_OPERATION} is generated if @code{glMatrixMode} is | |
15563 | executed between the execution of @code{glBegin} and the corresponding | |
15564 | execution of @code{glEnd}. | |
15565 | ||
bb894c9d | 15566 | @end deftypefun |
8925f36f | 15567 | |
bb894c9d | 15568 | @deftypefun void glMinmax target internalformat sink |
3c9b6116 AW |
15569 | Define minmax table. |
15570 | ||
8925f36f AW |
15571 | @table @asis |
15572 | @item @var{target} | |
f37e7e3d | 15573 | The minmax table whose parameters are to be set. Must be |
8925f36f AW |
15574 | @code{GL_MINMAX}. |
15575 | ||
15576 | @item @var{internalformat} | |
f37e7e3d | 15577 | The format of entries in the minmax table. Must be one of |
8925f36f AW |
15578 | @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, |
15579 | @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
15580 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
15581 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
15582 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
15583 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
15584 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
15585 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
15586 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
15587 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
15588 | @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
15589 | ||
15590 | @item @var{sink} | |
15591 | If @code{GL_TRUE}, pixels will be consumed by the minmax process and no | |
f37e7e3d | 15592 | drawing or texture loading will take place. If @code{GL_FALSE}, pixels |
8925f36f AW |
15593 | will proceed to the final conversion process after minmax. |
15594 | ||
15595 | @end table | |
15596 | ||
8925f36f AW |
15597 | When @code{GL_MINMAX} is enabled, the RGBA components of incoming pixels |
15598 | are compared to the minimum and maximum values for each component, which | |
f37e7e3d | 15599 | are stored in the two-element minmax table. (The first element stores |
8925f36f AW |
15600 | the minima, and the second element stores the maxima.) If a pixel |
15601 | component is greater than the corresponding component in the maximum | |
15602 | element, then the maximum element is updated with the pixel component | |
f37e7e3d | 15603 | value. If a pixel component is less than the corresponding component in |
8925f36f | 15604 | the minimum element, then the minimum element is updated with the pixel |
f37e7e3d | 15605 | component value. (In both cases, if the internal format of the minmax |
8925f36f AW |
15606 | table includes luminance, then the R color component of incoming pixels |
15607 | is used for comparison.) The contents of the minmax table may be | |
f37e7e3d | 15608 | retrieved at a later time by calling @code{glGetMinmax}. The minmax |
8925f36f AW |
15609 | operation is enabled or disabled by calling @code{glEnable} or |
15610 | @code{glDisable}, respectively, with an argument of @code{GL_MINMAX}. | |
15611 | ||
15612 | @code{glMinmax} redefines the current minmax table to have entries of | |
f37e7e3d | 15613 | the format specified by @var{internalformat}. The maximum element is |
8925f36f | 15614 | initialized with the smallest possible component values, and the minimum |
f37e7e3d DH |
15615 | element is initialized with the largest possible component values. The |
15616 | values in the previous minmax table, if any, are lost. If @var{sink} is | |
8925f36f AW |
15617 | @code{GL_TRUE}, then pixels are discarded after minmax; no further |
15618 | processing of the pixels takes place, and no drawing, texture loading, | |
15619 | or pixel readback will result. | |
15620 | ||
15621 | ||
15622 | ||
8925f36f AW |
15623 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
15624 | allowable values. | |
15625 | ||
15626 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
15627 | of the allowable values. | |
15628 | ||
15629 | @code{GL_INVALID_OPERATION} is generated if @code{glMinmax} is executed | |
15630 | between the execution of @code{glBegin} and the corresponding execution | |
15631 | of @code{glEnd}. | |
15632 | ||
bb894c9d | 15633 | @end deftypefun |
8925f36f | 15634 | |
bb894c9d | 15635 | @deftypefun void glMultiDrawArrays mode first count primcount |
3c9b6116 AW |
15636 | Render multiple sets of primitives from array data. |
15637 | ||
8925f36f AW |
15638 | @table @asis |
15639 | @item @var{mode} | |
f37e7e3d | 15640 | Specifies what kind of primitives to render. Symbolic constants |
8925f36f AW |
15641 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, |
15642 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
15643 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
15644 | @code{GL_POLYGON} are accepted. | |
15645 | ||
15646 | @item @var{first} | |
15647 | Points to an array of starting indices in the enabled arrays. | |
15648 | ||
15649 | @item @var{count} | |
15650 | Points to an array of the number of indices to be rendered. | |
15651 | ||
15652 | @item @var{primcount} | |
15653 | Specifies the size of the first and count | |
15654 | ||
15655 | @end table | |
15656 | ||
8925f36f | 15657 | @code{glMultiDrawArrays} specifies multiple sets of geometric primitives |
f37e7e3d | 15658 | with very few subroutine calls. Instead of calling a GL procedure to |
8925f36f AW |
15659 | pass each individual vertex, normal, texture coordinate, edge flag, or |
15660 | color, you can prespecify separate arrays of vertices, normals, and | |
15661 | colors and use them to construct a sequence of primitives with a single | |
15662 | call to @code{glMultiDrawArrays}. | |
15663 | ||
15664 | @code{glMultiDrawArrays} behaves identically to @code{glDrawArrays} | |
15665 | except that @var{primcount} separate ranges of elements are specified | |
15666 | instead. | |
15667 | ||
15668 | When @code{glMultiDrawArrays} is called, it uses @var{count} sequential | |
15669 | elements from each enabled array to construct a sequence of geometric | |
f37e7e3d | 15670 | primitives, beginning with element @var{first}. @var{mode} specifies |
8925f36f | 15671 | what kind of primitives are constructed, and how the array elements |
f37e7e3d DH |
15672 | construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, no |
15673 | geometric primitives are generated. | |
8925f36f AW |
15674 | |
15675 | Vertex attributes that are modified by @code{glMultiDrawArrays} have an | |
f37e7e3d | 15676 | unspecified value after @code{glMultiDrawArrays} returns. For example, |
8925f36f | 15677 | if @code{GL_COLOR_ARRAY} is enabled, the value of the current color is |
f37e7e3d | 15678 | undefined after @code{glMultiDrawArrays} executes. Attributes that |
8925f36f AW |
15679 | aren't modified remain well defined. |
15680 | ||
8925f36f AW |
15681 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
15682 | value. | |
15683 | ||
15684 | @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative. | |
15685 | ||
15686 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
15687 | name is bound to an enabled array and the buffer object's data store is | |
15688 | currently mapped. | |
15689 | ||
15690 | @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawArrays} is | |
15691 | executed between the execution of @code{glBegin} and the corresponding | |
15692 | @code{glEnd}. | |
15693 | ||
bb894c9d | 15694 | @end deftypefun |
8925f36f | 15695 | |
bb894c9d | 15696 | @deftypefun void glMultiDrawElements mode count type indices primcount |
3c9b6116 AW |
15697 | Render multiple sets of primitives by specifying indices of array data |
15698 | elements. | |
15699 | ||
8925f36f AW |
15700 | @table @asis |
15701 | @item @var{mode} | |
f37e7e3d | 15702 | Specifies what kind of primitives to render. Symbolic constants |
8925f36f AW |
15703 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, |
15704 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
15705 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
15706 | @code{GL_POLYGON} are accepted. | |
15707 | ||
15708 | @item @var{count} | |
15709 | Points to an array of the elements counts. | |
15710 | ||
15711 | @item @var{type} | |
f37e7e3d | 15712 | Specifies the type of the values in @var{indices}. Must be one of |
8925f36f AW |
15713 | @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or |
15714 | @code{GL_UNSIGNED_INT}. | |
15715 | ||
15716 | @item @var{indices} | |
15717 | Specifies a pointer to the location where the indices are stored. | |
15718 | ||
15719 | @item @var{primcount} | |
15720 | Specifies the size of the @var{count} array. | |
15721 | ||
15722 | @end table | |
15723 | ||
8925f36f | 15724 | @code{glMultiDrawElements} specifies multiple sets of geometric |
f37e7e3d | 15725 | primitives with very few subroutine calls. Instead of calling a GL |
8925f36f AW |
15726 | function to pass each individual vertex, normal, texture coordinate, |
15727 | edge flag, or color, you can prespecify separate arrays of vertices, | |
15728 | normals, and so on, and use them to construct a sequence of primitives | |
15729 | with a single call to @code{glMultiDrawElements}. | |
15730 | ||
15731 | @code{glMultiDrawElements} is identical in operation to | |
15732 | @code{glDrawElements} except that @var{primcount} separate lists of | |
15733 | elements are specified. | |
15734 | ||
15735 | Vertex attributes that are modified by @code{glMultiDrawElements} have | |
f37e7e3d | 15736 | an unspecified value after @code{glMultiDrawElements} returns. For |
8925f36f | 15737 | example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current |
f37e7e3d | 15738 | color is undefined after @code{glMultiDrawElements} executes. Attributes |
8925f36f AW |
15739 | that aren't modified maintain their previous values. |
15740 | ||
8925f36f AW |
15741 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
15742 | value. | |
15743 | ||
15744 | @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative. | |
15745 | ||
15746 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
15747 | name is bound to an enabled array or the element array and the buffer | |
15748 | object's data store is currently mapped. | |
15749 | ||
15750 | @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawElements} | |
15751 | is executed between the execution of @code{glBegin} and the | |
15752 | corresponding @code{glEnd}. | |
15753 | ||
bb894c9d | 15754 | @end deftypefun |
8925f36f | 15755 | |
d172eed9 AW |
15756 | @deftypefun void glMultiTexCoord1s target s |
15757 | @deftypefunx void glMultiTexCoord1i target s | |
ca09631c | 15758 | @deftypefunx void glMultiTexCoord1f target s |
d172eed9 AW |
15759 | @deftypefunx void glMultiTexCoord1d target s |
15760 | @deftypefunx void glMultiTexCoord2s target s t | |
bb894c9d | 15761 | @deftypefunx void glMultiTexCoord2i target s t |
ca09631c | 15762 | @deftypefunx void glMultiTexCoord2f target s t |
d172eed9 AW |
15763 | @deftypefunx void glMultiTexCoord2d target s t |
15764 | @deftypefunx void glMultiTexCoord3s target s t r | |
bb894c9d | 15765 | @deftypefunx void glMultiTexCoord3i target s t r |
ca09631c | 15766 | @deftypefunx void glMultiTexCoord3f target s t r |
d172eed9 AW |
15767 | @deftypefunx void glMultiTexCoord3d target s t r |
15768 | @deftypefunx void glMultiTexCoord4s target s t r q | |
bb894c9d | 15769 | @deftypefunx void glMultiTexCoord4i target s t r q |
ca09631c | 15770 | @deftypefunx void glMultiTexCoord4f target s t r q |
d172eed9 AW |
15771 | @deftypefunx void glMultiTexCoord4d target s t r q |
15772 | @deftypefunx void glMultiTexCoord1sv target v | |
15773 | @deftypefunx void glMultiTexCoord1iv target v | |
15774 | @deftypefunx void glMultiTexCoord1fv target v | |
15775 | @deftypefunx void glMultiTexCoord1dv target v | |
15776 | @deftypefunx void glMultiTexCoord2sv target v | |
15777 | @deftypefunx void glMultiTexCoord2iv target v | |
15778 | @deftypefunx void glMultiTexCoord2fv target v | |
15779 | @deftypefunx void glMultiTexCoord2dv target v | |
15780 | @deftypefunx void glMultiTexCoord3sv target v | |
15781 | @deftypefunx void glMultiTexCoord3iv target v | |
15782 | @deftypefunx void glMultiTexCoord3fv target v | |
15783 | @deftypefunx void glMultiTexCoord3dv target v | |
15784 | @deftypefunx void glMultiTexCoord4sv target v | |
15785 | @deftypefunx void glMultiTexCoord4iv target v | |
15786 | @deftypefunx void glMultiTexCoord4fv target v | |
15787 | @deftypefunx void glMultiTexCoord4dv target v | |
3c9b6116 AW |
15788 | Set the current texture coordinates. |
15789 | ||
8925f36f AW |
15790 | @table @asis |
15791 | @item @var{target} | |
f37e7e3d | 15792 | Specifies the texture unit whose coordinates should be modified. The |
8925f36f | 15793 | number of texture units is implementation dependent, but must be at |
f37e7e3d | 15794 | least two. Symbolic constant must be one of |
3c9b6116 | 15795 | @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to |
8925f36f AW |
15796 | @code{GL_MAX_TEXTURE_COORDS} - 1, which is an implementation-dependent |
15797 | value. | |
15798 | ||
15799 | @item @var{s} | |
15800 | @itemx @var{t} | |
15801 | @itemx @var{r} | |
15802 | @itemx @var{q} | |
15803 | Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates for | |
f37e7e3d | 15804 | @var{target} texture unit. Not all parameters are present in all forms |
8925f36f AW |
15805 | of the command. |
15806 | ||
15807 | @end table | |
15808 | ||
8925f36f | 15809 | @code{glMultiTexCoord} specifies texture coordinates in one, two, three, |
f37e7e3d | 15810 | or four dimensions. @code{glMultiTexCoord1} sets the current texture |
3c9b6116 | 15811 | coordinates to @r{(@var{s},001)}; a call to @code{glMultiTexCoord2} sets |
f37e7e3d | 15812 | them to @r{(@var{s},@var{t}01)}. Similarly, @code{glMultiTexCoord3} |
3c9b6116 AW |
15813 | specifies the texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and |
15814 | @code{glMultiTexCoord4} defines all four components explicitly as | |
15815 | @r{(@var{s},@var{t}@var{r}@var{q})}. | |
8925f36f AW |
15816 | |
15817 | The current texture coordinates are part of the data that is associated | |
f37e7e3d | 15818 | with each vertex and with the current raster position. Initially, the |
3c9b6116 | 15819 | values for @r{(@var{s},@var{t}@var{r}@var{q})} are @r{(0,001)}. |
8925f36f AW |
15820 | |
15821 | ||
15822 | ||
bb894c9d | 15823 | @end deftypefun |
8925f36f | 15824 | |
d172eed9 AW |
15825 | @deftypefun void glMultMatrixd m |
15826 | @deftypefunx void glMultMatrixf m | |
3c9b6116 AW |
15827 | Multiply the current matrix with the specified matrix. |
15828 | ||
8925f36f AW |
15829 | @table @asis |
15830 | @item @var{m} | |
15831 | Points to 16 consecutive values that are used as the elements of a | |
3c9b6116 | 15832 | @r{4×4} column-major matrix. |
8925f36f AW |
15833 | |
15834 | @end table | |
15835 | ||
8925f36f AW |
15836 | @code{glMultMatrix} multiplies the current matrix with the one specified |
15837 | using @var{m}, and replaces the current matrix with the product. | |
15838 | ||
15839 | The current matrix is determined by the current matrix mode (see | |
f37e7e3d | 15840 | @code{glMatrixMode}). It is either the projection matrix, modelview |
8925f36f AW |
15841 | matrix, or the texture matrix. |
15842 | ||
8925f36f AW |
15843 | @code{GL_INVALID_OPERATION} is generated if @code{glMultMatrix} is |
15844 | executed between the execution of @code{glBegin} and the corresponding | |
15845 | execution of @code{glEnd}. | |
15846 | ||
bb894c9d | 15847 | @end deftypefun |
8925f36f | 15848 | |
d172eed9 AW |
15849 | @deftypefun void glMultTransposeMatrixd m |
15850 | @deftypefunx void glMultTransposeMatrixf m | |
3c9b6116 AW |
15851 | Multiply the current matrix with the specified row-major ordered matrix. |
15852 | ||
8925f36f AW |
15853 | @table @asis |
15854 | @item @var{m} | |
15855 | Points to 16 consecutive values that are used as the elements of a | |
3c9b6116 | 15856 | @r{4×4} row-major matrix. |
8925f36f AW |
15857 | |
15858 | @end table | |
15859 | ||
8925f36f AW |
15860 | @code{glMultTransposeMatrix} multiplies the current matrix with the one |
15861 | specified using @var{m}, and replaces the current matrix with the | |
15862 | product. | |
15863 | ||
15864 | The current matrix is determined by the current matrix mode (see | |
f37e7e3d | 15865 | @code{glMatrixMode}). It is either the projection matrix, modelview |
8925f36f AW |
15866 | matrix, or the texture matrix. |
15867 | ||
8925f36f AW |
15868 | @code{GL_INVALID_OPERATION} is generated if @code{glMultTransposeMatrix} |
15869 | is executed between the execution of @code{glBegin} and the | |
15870 | corresponding execution of @code{glEnd}. | |
15871 | ||
bb894c9d | 15872 | @end deftypefun |
8925f36f | 15873 | |
bb894c9d AW |
15874 | @deftypefun void glNewList list mode |
15875 | @deftypefunx void glEndList | |
3c9b6116 AW |
15876 | Create or replace a display list. |
15877 | ||
8925f36f AW |
15878 | @table @asis |
15879 | @item @var{list} | |
15880 | Specifies the display-list name. | |
15881 | ||
15882 | @item @var{mode} | |
15883 | Specifies the compilation mode, which can be @code{GL_COMPILE} or | |
15884 | @code{GL_COMPILE_AND_EXECUTE}. | |
15885 | ||
15886 | @end table | |
15887 | ||
8925f36f | 15888 | Display lists are groups of GL commands that have been stored for |
f37e7e3d | 15889 | subsequent execution. Display lists are created with @code{glNewList}. |
8925f36f AW |
15890 | All subsequent commands are placed in the display list, in the order |
15891 | issued, until @code{glEndList} is called. | |
15892 | ||
f37e7e3d DH |
15893 | @code{glNewList} has two arguments. The first argument, @var{list}, is a |
15894 | positive integer that becomes the unique name for the display list. | |
8925f36f | 15895 | Names can be created and reserved with @code{glGenLists} and tested for |
f37e7e3d | 15896 | uniqueness with @code{glIsList}. The second argument, @var{mode}, is a |
8925f36f AW |
15897 | symbolic constant that can assume one of two values: |
15898 | ||
15899 | @table @asis | |
15900 | @item @code{GL_COMPILE} | |
15901 | Commands are merely compiled. | |
15902 | ||
15903 | @item @code{GL_COMPILE_AND_EXECUTE} | |
15904 | Commands are executed as they are compiled into the display list. | |
15905 | ||
15906 | @end table | |
15907 | ||
15908 | Certain commands are not compiled into the display list but are executed | |
f37e7e3d | 15909 | immediately, regardless of the display-list mode. These commands are |
8925f36f AW |
15910 | @code{glAreTexturesResident}, @code{glColorPointer}, |
15911 | @code{glDeleteLists}, @code{glDeleteTextures}, | |
15912 | @code{glDisableClientState}, @code{glEdgeFlagPointer}, | |
15913 | @code{glEnableClientState}, @code{glFeedbackBuffer}, @code{glFinish}, | |
15914 | @code{glFlush}, @code{glGenLists}, @code{glGenTextures}, | |
15915 | @code{glIndexPointer}, @code{glInterleavedArrays}, @code{glIsEnabled}, | |
15916 | @code{glIsList}, @code{glIsTexture}, @code{glNormalPointer}, | |
15917 | @code{glPopClientAttrib}, @code{glPixelStore}, | |
15918 | @code{glPushClientAttrib}, @code{glReadPixels}, @code{glRenderMode}, | |
15919 | @code{glSelectBuffer}, @code{glTexCoordPointer}, @code{glVertexPointer}, | |
15920 | and all of the @code{glGet} commands. | |
15921 | ||
15922 | Similarly, @code{glTexImage1D}, @code{glTexImage2D}, and | |
15923 | @code{glTexImage3D} are executed immediately and not compiled into the | |
15924 | display list when their first argument is @code{GL_PROXY_TEXTURE_1D}, | |
15925 | @code{GL_PROXY_TEXTURE_1D}, or @code{GL_PROXY_TEXTURE_3D}, respectively. | |
15926 | ||
15927 | When the @code{ARB_imaging} extension is supported, @code{glHistogram} | |
15928 | executes immediately when its argument is @code{GL_PROXY_HISTOGRAM}. | |
15929 | Similarly, @code{glColorTable} executes immediately when its first | |
15930 | argument is @code{GL_PROXY_COLOR_TABLE}, | |
15931 | @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or | |
15932 | @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}. | |
15933 | ||
15934 | For OpenGL versions 1.3 and greater, or when the @code{ARB_multitexture} | |
15935 | extension is supported, @code{glClientActiveTexture} is not compiled | |
15936 | into display lists, but executed immediately. | |
15937 | ||
15938 | When @code{glEndList} is encountered, the display-list definition is | |
15939 | completed by associating the list with the unique name @var{list} | |
f37e7e3d DH |
15940 | (specified in the @code{glNewList} command). If a display list with name |
15941 | @var{list} already exists, it is replaced only when @code{glEndList} is | |
15942 | called. | |
8925f36f | 15943 | |
8925f36f AW |
15944 | @code{GL_INVALID_VALUE} is generated if @var{list} is 0. |
15945 | ||
15946 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted | |
15947 | value. | |
15948 | ||
15949 | @code{GL_INVALID_OPERATION} is generated if @code{glEndList} is called | |
15950 | without a preceding @code{glNewList}, or if @code{glNewList} is called | |
15951 | while a display list is being defined. | |
15952 | ||
15953 | @code{GL_INVALID_OPERATION} is generated if @code{glNewList} or | |
15954 | @code{glEndList} is executed between the execution of @code{glBegin} and | |
15955 | the corresponding execution of @code{glEnd}. | |
15956 | ||
15957 | @code{GL_OUT_OF_MEMORY} is generated if there is insufficient memory to | |
f37e7e3d DH |
15958 | compile the display list. If the GL version is 1.1 or greater, no change |
15959 | is made to the previous contents of the display list, if any, and no | |
15960 | other change is made to the GL state. (It is as if no attempt had been | |
15961 | made to create the new display list.) | |
8925f36f | 15962 | |
bb894c9d | 15963 | @end deftypefun |
8925f36f | 15964 | |
bb894c9d | 15965 | @deftypefun void glNormalPointer type stride pointer |
3c9b6116 AW |
15966 | Define an array of normals. |
15967 | ||
8925f36f AW |
15968 | @table @asis |
15969 | @item @var{type} | |
f37e7e3d | 15970 | Specifies the data type of each coordinate in the array. Symbolic |
8925f36f | 15971 | constants @code{GL_BYTE}, @code{GL_SHORT}, @code{GL_INT}, |
f37e7e3d DH |
15972 | @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is |
15973 | @code{GL_FLOAT}. | |
8925f36f AW |
15974 | |
15975 | @item @var{stride} | |
f37e7e3d DH |
15976 | Specifies the byte offset between consecutive normals. If @var{stride} |
15977 | is 0, the normals are understood to be tightly packed in the array. The | |
8925f36f AW |
15978 | initial value is 0. |
15979 | ||
15980 | @item @var{pointer} | |
15981 | Specifies a pointer to the first coordinate of the first normal in the | |
f37e7e3d | 15982 | array. The initial value is 0. |
8925f36f AW |
15983 | |
15984 | @end table | |
15985 | ||
8925f36f | 15986 | @code{glNormalPointer} specifies the location and data format of an |
f37e7e3d | 15987 | array of normals to use when rendering. @var{type} specifies the data |
8925f36f AW |
15988 | type of each normal coordinate, and @var{stride} specifies the byte |
15989 | stride from one normal to the next, allowing vertices and attributes to | |
15990 | be packed into a single array or stored in separate arrays. | |
15991 | (Single-array storage may be more efficient on some implementations; see | |
15992 | @code{glInterleavedArrays}.) | |
15993 | ||
15994 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
15995 | target (see @code{glBindBuffer}) while a normal array is specified, | |
15996 | @var{pointer} is treated as a byte offset into the buffer object's data | |
f37e7e3d | 15997 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) |
8925f36f AW |
15998 | is saved as normal vertex array client-side state |
15999 | (@code{GL_NORMAL_ARRAY_BUFFER_BINDING}). | |
16000 | ||
16001 | When a normal array is specified, @var{type}, @var{stride}, and | |
16002 | @var{pointer} are saved as client-side state, in addition to the current | |
16003 | vertex array buffer object binding. | |
16004 | ||
16005 | To enable and disable the normal array, call @code{glEnableClientState} | |
16006 | and @code{glDisableClientState} with the argument | |
f37e7e3d | 16007 | @code{GL_NORMAL_ARRAY}. If enabled, the normal array is used when |
8925f36f AW |
16008 | @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements}, |
16009 | @code{glMultiDrawElements}, @code{glDrawRangeElements}, or | |
16010 | @code{glArrayElement} is called. | |
16011 | ||
8925f36f AW |
16012 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
16013 | value. | |
16014 | ||
16015 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
16016 | ||
bb894c9d | 16017 | @end deftypefun |
8925f36f | 16018 | |
d172eed9 AW |
16019 | @deftypefun void glNormal3b nx ny nz |
16020 | @deftypefunx void glNormal3d nx ny nz | |
16021 | @deftypefunx void glNormal3f nx ny nz | |
bb894c9d | 16022 | @deftypefunx void glNormal3i nx ny nz |
d172eed9 AW |
16023 | @deftypefunx void glNormal3s nx ny nz |
16024 | @deftypefunx void glNormal3bv v | |
16025 | @deftypefunx void glNormal3dv v | |
16026 | @deftypefunx void glNormal3fv v | |
16027 | @deftypefunx void glNormal3iv v | |
16028 | @deftypefunx void glNormal3sv v | |
3c9b6116 AW |
16029 | Set the current normal vector. |
16030 | ||
8925f36f AW |
16031 | @table @asis |
16032 | @item @var{nx} | |
16033 | @itemx @var{ny} | |
16034 | @itemx @var{nz} | |
3c9b6116 | 16035 | Specify the @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} coordinates of the |
f37e7e3d | 16036 | new current normal. The initial value of the current normal is the unit |
3c9b6116 | 16037 | vector, (0, 0, 1). |
8925f36f AW |
16038 | |
16039 | ||
16040 | ||
16041 | @end table | |
16042 | ||
8925f36f | 16043 | The current normal is set to the given coordinates whenever |
f37e7e3d | 16044 | @code{glNormal} is issued. Byte, short, or integer arguments are |
8925f36f AW |
16045 | converted to floating-point format with a linear mapping that maps the |
16046 | most positive representable integer value to 1.0 and the most negative | |
3c9b6116 | 16047 | representable integer value to @r{-1.0}. |
8925f36f | 16048 | |
f37e7e3d | 16049 | Normals specified with @code{glNormal} need not have unit length. If |
8925f36f | 16050 | @code{GL_NORMALIZE} is enabled, then normals of any length specified |
f37e7e3d | 16051 | with @code{glNormal} are normalized after transformation. If |
8925f36f | 16052 | @code{GL_RESCALE_NORMAL} is enabled, normals are scaled by a scaling |
f37e7e3d | 16053 | factor derived from the modelview matrix. @code{GL_RESCALE_NORMAL} |
8925f36f AW |
16054 | requires that the originally specified normals were of unit length, and |
16055 | that the modelview matrix contain only uniform scales for proper | |
f37e7e3d | 16056 | results. To enable and disable normalization, call @code{glEnable} and |
8925f36f | 16057 | @code{glDisable} with either @code{GL_NORMALIZE} or |
f37e7e3d | 16058 | @code{GL_RESCALE_NORMAL}. Normalization is initially disabled. |
8925f36f | 16059 | |
bb894c9d | 16060 | @end deftypefun |
8925f36f | 16061 | |
bb894c9d | 16062 | @deftypefun void glOrtho left right bottom top nearVal farVal |
3c9b6116 AW |
16063 | Multiply the current matrix with an orthographic matrix. |
16064 | ||
8925f36f AW |
16065 | @table @asis |
16066 | @item @var{left} | |
16067 | @itemx @var{right} | |
16068 | Specify the coordinates for the left and right vertical clipping planes. | |
16069 | ||
16070 | @item @var{bottom} | |
16071 | @itemx @var{top} | |
16072 | Specify the coordinates for the bottom and top horizontal clipping | |
16073 | planes. | |
16074 | ||
16075 | @item @var{nearVal} | |
16076 | @itemx @var{farVal} | |
16077 | Specify the distances to the nearer and farther depth clipping planes. | |
16078 | These values are negative if the plane is to be behind the viewer. | |
16079 | ||
16080 | @end table | |
16081 | ||
8925f36f | 16082 | @code{glOrtho} describes a transformation that produces a parallel |
f37e7e3d | 16083 | projection. The current matrix (see @code{glMatrixMode}) is multiplied |
8925f36f AW |
16084 | by this matrix and the result replaces the current matrix, as if |
16085 | @code{glMultMatrix} were called with the following matrix as its | |
16086 | argument: | |
16087 | ||
3c9b6116 | 16088 | @r{((2/@var{right}-@var{left},, 0 0 @var{t}_@var{x},), (0 |
8925f36f AW |
16089 | 2/@var{top}-@var{bottom},, 0 @var{t}_@var{y},), (0 0 |
16090 | -2/@var{farVal}-@var{nearVal},, @var{t}_@var{z},), (0 0 0 1),)} | |
16091 | ||
16092 | where | |
3c9b6116 | 16093 | @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 |
16094 | |
16095 | Typically, the matrix mode is @code{GL_PROJECTION}, and | |
3c9b6116 AW |
16096 | @r{(@var{left},@var{bottom}-@var{nearVal})} and |
16097 | @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near | |
16098 | clipping plane that are mapped to the lower left and upper right corners | |
16099 | of the window, respectively, assuming that the eye is located at (0, 0, | |
f37e7e3d | 16100 | 0). @r{-@var{farVal}} specifies the location of the far clipping plane. |
3c9b6116 | 16101 | Both @var{nearVal} and @var{farVal} can be either positive or negative. |
8925f36f AW |
16102 | |
16103 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
16104 | current matrix stack. | |
16105 | ||
8925f36f AW |
16106 | @code{GL_INVALID_VALUE} is generated if @var{left} = @var{right}, or |
16107 | @var{bottom} = @var{top}, or @var{near} = @var{far}. | |
16108 | ||
16109 | @code{GL_INVALID_OPERATION} is generated if @code{glOrtho} is executed | |
16110 | between the execution of @code{glBegin} and the corresponding execution | |
16111 | of @code{glEnd}. | |
16112 | ||
bb894c9d | 16113 | @end deftypefun |
8925f36f | 16114 | |
bb894c9d | 16115 | @deftypefun void glPassThrough token |
3c9b6116 AW |
16116 | Place a marker in the feedback buffer. |
16117 | ||
8925f36f AW |
16118 | @table @asis |
16119 | @item @var{token} | |
16120 | Specifies a marker value to be placed in the feedback buffer following a | |
16121 | @code{GL_PASS_THROUGH_TOKEN}. | |
16122 | ||
16123 | @end table | |
16124 | ||
8925f36f AW |
16125 | |
16126 | ||
f37e7e3d DH |
16127 | Feedback is a GL render mode. The mode is selected by calling |
16128 | @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback | |
16129 | mode, no pixels are produced by rasterization. Instead, information | |
8925f36f | 16130 | about primitives that would have been rasterized is fed back to the |
f37e7e3d DH |
16131 | application using the GL. See the @code{glFeedbackBuffer} reference page |
16132 | for a description of the feedback buffer and the values in it. | |
8925f36f AW |
16133 | |
16134 | @code{glPassThrough} inserts a user-defined marker in the feedback | |
f37e7e3d | 16135 | buffer when it is executed in feedback mode. @var{token} is returned as |
8925f36f | 16136 | if it were a primitive; it is indicated with its own unique identifying |
f37e7e3d | 16137 | value: @code{GL_PASS_THROUGH_TOKEN}. The order of @code{glPassThrough} |
8925f36f AW |
16138 | commands with respect to the specification of graphics primitives is |
16139 | maintained. | |
16140 | ||
8925f36f AW |
16141 | @code{GL_INVALID_OPERATION} is generated if @code{glPassThrough} is |
16142 | executed between the execution of @code{glBegin} and the corresponding | |
16143 | execution of @code{glEnd}. | |
16144 | ||
bb894c9d | 16145 | @end deftypefun |
8925f36f | 16146 | |
b002944d AW |
16147 | @deftypefun void glPixelMapfv map mapsize values |
16148 | @deftypefunx void glPixelMapuiv map mapsize values | |
d172eed9 | 16149 | @deftypefunx void glPixelMapusv map mapsize values |
b002944d AW |
16150 | Set up pixel transfer maps. |
16151 | ||
16152 | @table @asis | |
16153 | @item @var{map} | |
f37e7e3d | 16154 | Specifies a symbolic map name. Must be one of the following: |
b002944d AW |
16155 | @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S}, |
16156 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
16157 | @code{GL_PIXEL_MAP_I_TO_B}, @code{GL_PIXEL_MAP_I_TO_A}, | |
16158 | @code{GL_PIXEL_MAP_R_TO_R}, @code{GL_PIXEL_MAP_G_TO_G}, | |
16159 | @code{GL_PIXEL_MAP_B_TO_B}, or @code{GL_PIXEL_MAP_A_TO_A}. | |
16160 | ||
16161 | @item @var{mapsize} | |
16162 | Specifies the size of the map being defined. | |
16163 | ||
16164 | @item @var{values} | |
16165 | Specifies an array of @var{mapsize} values. | |
16166 | ||
16167 | @end table | |
16168 | ||
16169 | @code{glPixelMap} sets up translation tables, or @var{maps}, used by | |
16170 | @code{glCopyPixels}, @code{glCopyTexImage1D}, @code{glCopyTexImage2D}, | |
16171 | @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, | |
16172 | @code{glCopyTexSubImage3D}, @code{glDrawPixels}, @code{glReadPixels}, | |
16173 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
16174 | @code{glTexSubImage1D}, @code{glTexSubImage2D}, and | |
f37e7e3d | 16175 | @code{glTexSubImage3D}. Additionally, if the @code{ARB_imaging} subset |
b002944d AW |
16176 | is supported, the routines @code{glColorTable}, @code{glColorSubTable}, |
16177 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, | |
f37e7e3d | 16178 | @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D}. Use |
b002944d AW |
16179 | of these maps is described completely in the @code{glPixelTransfer} |
16180 | reference page, and partly in the reference pages for the pixel and | |
f37e7e3d | 16181 | texture image commands. Only the specification of the maps is described |
b002944d AW |
16182 | in this reference page. |
16183 | ||
16184 | @var{map} is a symbolic map name, indicating one of ten maps to set. | |
16185 | @var{mapsize} specifies the number of entries in the map, and | |
16186 | @var{values} is a pointer to an array of @var{mapsize} map values. | |
16187 | ||
16188 | If a non-zero named buffer object is bound to the | |
16189 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
16190 | pixel transfer map is specified, @var{values} is treated as a byte | |
16191 | offset into the buffer object's data store. | |
16192 | ||
16193 | The ten maps are as follows: | |
16194 | ||
16195 | @table @asis | |
16196 | @item @code{GL_PIXEL_MAP_I_TO_I} | |
16197 | Maps color indices to color indices. | |
16198 | ||
16199 | @item @code{GL_PIXEL_MAP_S_TO_S} | |
16200 | Maps stencil indices to stencil indices. | |
16201 | ||
16202 | @item @code{GL_PIXEL_MAP_I_TO_R} | |
16203 | Maps color indices to red components. | |
16204 | ||
16205 | @item @code{GL_PIXEL_MAP_I_TO_G} | |
16206 | Maps color indices to green components. | |
16207 | ||
16208 | @item @code{GL_PIXEL_MAP_I_TO_B} | |
16209 | Maps color indices to blue components. | |
16210 | ||
16211 | @item @code{GL_PIXEL_MAP_I_TO_A} | |
16212 | Maps color indices to alpha components. | |
16213 | ||
16214 | @item @code{GL_PIXEL_MAP_R_TO_R} | |
16215 | Maps red components to red components. | |
16216 | ||
16217 | @item @code{GL_PIXEL_MAP_G_TO_G} | |
16218 | Maps green components to green components. | |
16219 | ||
16220 | @item @code{GL_PIXEL_MAP_B_TO_B} | |
16221 | Maps blue components to blue components. | |
16222 | ||
16223 | @item @code{GL_PIXEL_MAP_A_TO_A} | |
16224 | Maps alpha components to alpha components. | |
16225 | ||
16226 | @end table | |
16227 | ||
16228 | The entries in a map can be specified as single-precision floating-point | |
f37e7e3d | 16229 | numbers, unsigned short integers, or unsigned int integers. Maps that |
b002944d AW |
16230 | store color component values (all but @code{GL_PIXEL_MAP_I_TO_I} and |
16231 | @code{GL_PIXEL_MAP_S_TO_S}) retain their values in floating-point | |
f37e7e3d | 16232 | format, with unspecified mantissa and exponent sizes. Floating-point |
b002944d AW |
16233 | values specified by @code{glPixelMapfv} are converted directly to the |
16234 | internal floating-point format of these maps, then clamped to the range | |
f37e7e3d | 16235 | [0,1]. Unsigned integer values specified by @code{glPixelMapusv} and |
b002944d AW |
16236 | @code{glPixelMapuiv} are converted linearly such that the largest |
16237 | representable integer maps to 1.0, and 0 maps to 0.0. | |
16238 | ||
16239 | Maps that store indices, @code{GL_PIXEL_MAP_I_TO_I} and | |
16240 | @code{GL_PIXEL_MAP_S_TO_S}, retain their values in fixed-point format, | |
16241 | with an unspecified number of bits to the right of the binary point. | |
16242 | Floating-point values specified by @code{glPixelMapfv} are converted | |
f37e7e3d | 16243 | directly to the internal fixed-point format of these maps. Unsigned |
b002944d AW |
16244 | integer values specified by @code{glPixelMapusv} and |
16245 | @code{glPixelMapuiv} specify integer values, with all 0's to the right | |
16246 | of the binary point. | |
16247 | ||
16248 | The following table shows the initial sizes and values for each of the | |
f37e7e3d DH |
16249 | maps. Maps that are indexed by either color or stencil indices must have |
16250 | @var{mapsize} = @r{2^@var{n}} for some @r{@var{n}} or the results are | |
16251 | undefined. The maximum allowable size for each map depends on the | |
b002944d | 16252 | implementation and can be determined by calling @code{glGet} with |
f37e7e3d | 16253 | argument @code{GL_MAX_PIXEL_MAP_TABLE}. The single maximum applies to |
b002944d AW |
16254 | all maps; it is at least 32. |
16255 | ||
16256 | @table @asis | |
16257 | @item @strong{@var{map}} | |
16258 | @strong{Lookup Index}, @strong{Lookup Value}, @strong{Initial Size}, | |
16259 | @strong{Initial Value} | |
16260 | ||
16261 | @item @code{GL_PIXEL_MAP_I_TO_I} | |
16262 | color index , color index , 1 , 0 | |
16263 | ||
16264 | @item @code{GL_PIXEL_MAP_S_TO_S} | |
16265 | stencil index , stencil index , 1 , 0 | |
16266 | ||
16267 | @item @code{GL_PIXEL_MAP_I_TO_R} | |
16268 | color index , R , 1 , 0 | |
16269 | ||
16270 | @item @code{GL_PIXEL_MAP_I_TO_G} | |
16271 | color index , G , 1 , 0 | |
16272 | ||
16273 | @item @code{GL_PIXEL_MAP_I_TO_B} | |
16274 | color index , B , 1 , 0 | |
16275 | ||
16276 | @item @code{GL_PIXEL_MAP_I_TO_A} | |
16277 | color index , A , 1 , 0 | |
16278 | ||
16279 | @item @code{GL_PIXEL_MAP_R_TO_R} | |
16280 | R , R , 1 , 0 | |
16281 | ||
16282 | @item @code{GL_PIXEL_MAP_G_TO_G} | |
16283 | G , G , 1 , 0 | |
16284 | ||
16285 | @item @code{GL_PIXEL_MAP_B_TO_B} | |
16286 | B , B , 1 , 0 | |
16287 | ||
16288 | @item @code{GL_PIXEL_MAP_A_TO_A} | |
16289 | A , A , 1 , 0 | |
16290 | ||
16291 | @end table | |
16292 | ||
16293 | @code{GL_INVALID_ENUM} is generated if @var{map} is not an accepted | |
16294 | value. | |
16295 | ||
16296 | @code{GL_INVALID_VALUE} is generated if @var{mapsize} is less than one | |
16297 | or larger than @code{GL_MAX_PIXEL_MAP_TABLE}. | |
16298 | ||
16299 | @code{GL_INVALID_VALUE} is generated if @var{map} is | |
16300 | @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S}, | |
16301 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
16302 | @code{GL_PIXEL_MAP_I_TO_B}, or @code{GL_PIXEL_MAP_I_TO_A}, and | |
16303 | @var{mapsize} is not a power of two. | |
16304 | ||
16305 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16306 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
16307 | object's data store is currently mapped. | |
16308 | ||
16309 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16310 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
16311 | would be unpacked from the buffer object such that the memory reads | |
16312 | required would exceed the data store size. | |
16313 | ||
16314 | @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapfv} if a | |
16315 | non-zero buffer object name is bound to the | |
16316 | @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly | |
16317 | divisible into the number of bytes needed to store in memory a GLfloat | |
16318 | datum. | |
16319 | ||
16320 | @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapuiv} if a | |
16321 | non-zero buffer object name is bound to the | |
16322 | @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly | |
16323 | divisible into the number of bytes needed to store in memory a GLuint | |
16324 | datum. | |
16325 | ||
16326 | @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapusv} if a | |
16327 | non-zero buffer object name is bound to the | |
16328 | @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly | |
16329 | divisible into the number of bytes needed to store in memory a GLushort | |
16330 | datum. | |
16331 | ||
16332 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelMap} is | |
16333 | executed between the execution of @code{glBegin} and the corresponding | |
16334 | execution of @code{glEnd}. | |
16335 | ||
16336 | @end deftypefun | |
16337 | ||
bb894c9d AW |
16338 | @deftypefun void glPixelStoref pname param |
16339 | @deftypefunx void glPixelStorei pname param | |
3c9b6116 AW |
16340 | Set pixel storage modes. |
16341 | ||
8925f36f AW |
16342 | @table @asis |
16343 | @item @var{pname} | |
f37e7e3d | 16344 | Specifies the symbolic name of the parameter to be set. Six values |
8925f36f AW |
16345 | affect the packing of pixel data into memory: @code{GL_PACK_SWAP_BYTES}, |
16346 | @code{GL_PACK_LSB_FIRST}, @code{GL_PACK_ROW_LENGTH}, | |
16347 | @code{GL_PACK_IMAGE_HEIGHT}, @code{GL_PACK_SKIP_PIXELS}, | |
16348 | @code{GL_PACK_SKIP_ROWS}, @code{GL_PACK_SKIP_IMAGES}, and | |
f37e7e3d | 16349 | @code{GL_PACK_ALIGNMENT}. Six more affect the unpacking of pixel data |
8925f36f AW |
16350 | @var{from} memory: @code{GL_UNPACK_SWAP_BYTES}, |
16351 | @code{GL_UNPACK_LSB_FIRST}, @code{GL_UNPACK_ROW_LENGTH}, | |
16352 | @code{GL_UNPACK_IMAGE_HEIGHT}, @code{GL_UNPACK_SKIP_PIXELS}, | |
16353 | @code{GL_UNPACK_SKIP_ROWS}, @code{GL_UNPACK_SKIP_IMAGES}, and | |
16354 | @code{GL_UNPACK_ALIGNMENT}. | |
16355 | ||
16356 | @item @var{param} | |
16357 | Specifies the value that @var{pname} is set to. | |
16358 | ||
16359 | @end table | |
16360 | ||
8925f36f AW |
16361 | @code{glPixelStore} sets pixel storage modes that affect the operation |
16362 | of subsequent @code{glDrawPixels} and @code{glReadPixels} as well as the | |
16363 | unpacking of polygon stipple patterns (see @code{glPolygonStipple}), | |
16364 | bitmaps (see @code{glBitmap}), texture patterns (see | |
16365 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
16366 | @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D}). | |
16367 | Additionally, if the @code{ARB_imaging} extension is supported, pixel | |
16368 | storage modes affect convolution filters (see | |
16369 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and | |
16370 | @code{glSeparableFilter2D}, color table (see @code{glColorTable}, and | |
16371 | @code{glColorSubTable}, and unpacking histogram (See | |
16372 | @code{glHistogram}), and minmax (See @code{glMinmax}) data. | |
16373 | ||
16374 | @var{pname} is a symbolic constant indicating the parameter to be set, | |
f37e7e3d DH |
16375 | and @var{param} is the new value. Six of the twelve storage parameters |
16376 | affect how pixel data is returned to client memory. They are as follows: | |
8925f36f AW |
16377 | |
16378 | @table @asis | |
16379 | @item @code{GL_PACK_SWAP_BYTES} | |
16380 | If true, byte ordering for multibyte color components, depth components, | |
f37e7e3d | 16381 | color indices, or stencil indices is reversed. That is, if a four-byte |
3c9b6116 AW |
16382 | component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2}, |
16383 | @r{@var{b}_3}, it is stored in memory as @r{@var{b}_3}, @r{@var{b}_2}, | |
16384 | @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_PACK_SWAP_BYTES} is true. | |
16385 | @code{GL_PACK_SWAP_BYTES} has no effect on the memory order of | |
16386 | components within a pixel, only on the order of bytes within components | |
f37e7e3d | 16387 | or indices. For example, the three components of a @code{GL_RGB} format |
3c9b6116 AW |
16388 | pixel are always stored with red first, green second, and blue third, |
16389 | regardless of the value of @code{GL_PACK_SWAP_BYTES}. | |
8925f36f AW |
16390 | |
16391 | @item @code{GL_PACK_LSB_FIRST} | |
16392 | If true, bits are ordered within a byte from least significant to most | |
16393 | significant; otherwise, the first bit in each byte is the most | |
f37e7e3d | 16394 | significant one. This parameter is significant for bitmap data only. |
8925f36f AW |
16395 | |
16396 | @item @code{GL_PACK_ROW_LENGTH} | |
16397 | If greater than 0, @code{GL_PACK_ROW_LENGTH} defines the number of | |
f37e7e3d | 16398 | pixels in a row. If the first pixel of a row is placed at location |
3c9b6116 AW |
16399 | @r{@var{p}} in memory, then the location of the first pixel of the next |
16400 | row is obtained by skipping | |
8925f36f | 16401 | |
3c9b6116 | 16402 | @r{@var{k}=@{(@var{n}@var{l}), |
8925f36f AW |
16403 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}), |
16404 | (@var{s}<@var{a}),} | |
16405 | ||
3c9b6116 AW |
16406 | components or indices, where @r{@var{n}} is the number of components or |
16407 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
16408 | (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}} | |
16409 | argument to the pixel routine otherwise), @r{@var{a}} is the value of | |
16410 | @code{GL_PACK_ALIGNMENT}, and @r{@var{s}} is the size, in bytes, of a | |
16411 | single component (if @r{@var{a}<@var{s}}, then it is as if | |
f37e7e3d | 16412 | @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the |
3c9b6116 | 16413 | next row is obtained by skipping |
8925f36f | 16414 | |
3c9b6116 | 16415 | @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉} |
8925f36f AW |
16416 | |
16417 | components or indices. | |
16418 | ||
16419 | The word @var{component} in this description refers to the nonindex | |
f37e7e3d DH |
16420 | values red, green, blue, alpha, and depth. Storage format @code{GL_RGB}, |
16421 | for example, has three components per pixel: first red, then green, and | |
16422 | finally blue. | |
8925f36f AW |
16423 | |
16424 | @item @code{GL_PACK_IMAGE_HEIGHT} | |
16425 | If greater than 0, @code{GL_PACK_IMAGE_HEIGHT} defines the number of | |
16426 | pixels in an image three-dimensional texture volume, where ``image'' is | |
f37e7e3d | 16427 | defined by all pixels sharing the same third dimension index. If the |
3c9b6116 AW |
16428 | first pixel of a row is placed at location @r{@var{p}} in memory, then |
16429 | the location of the first pixel of the next row is obtained by skipping | |
8925f36f | 16430 | |
3c9b6116 | 16431 | @r{@var{k}=@{(@var{n}@var{l}@var{h}), |
8925f36f AW |
16432 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}), |
16433 | (@var{s}<@var{a}),} | |
16434 | ||
3c9b6116 AW |
16435 | components or indices, where @r{@var{n}} is the number of components or |
16436 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
16437 | (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}} | |
16438 | argument to @code{glTexImage3D} otherwise), @r{@var{h}} is the number of | |
16439 | rows in a pixel image (@code{GL_PACK_IMAGE_HEIGHT} if it is greater than | |
16440 | 0, the @r{@var{height}} argument to the @code{glTexImage3D} routine | |
16441 | otherwise), @r{@var{a}} is the value of @code{GL_PACK_ALIGNMENT}, and | |
16442 | @r{@var{s}} is the size, in bytes, of a single component (if | |
16443 | @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}). | |
8925f36f AW |
16444 | |
16445 | The word @var{component} in this description refers to the nonindex | |
f37e7e3d DH |
16446 | values red, green, blue, alpha, and depth. Storage format @code{GL_RGB}, |
16447 | for example, has three components per pixel: first red, then green, and | |
16448 | finally blue. | |
8925f36f AW |
16449 | |
16450 | @item @code{GL_PACK_SKIP_PIXELS}, @code{GL_PACK_SKIP_ROWS}, and @code{GL_PACK_SKIP_IMAGES} | |
16451 | These values are provided as a convenience to the programmer; they | |
16452 | provide no functionality that cannot be duplicated simply by | |
f37e7e3d | 16453 | incrementing the pointer passed to @code{glReadPixels}. Setting |
3c9b6116 AW |
16454 | @code{GL_PACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to incrementing |
16455 | the pointer by @r{@var{i}@var{n}} components or indices, where | |
16456 | @r{@var{n}} is the number of components or indices in each pixel. | |
16457 | Setting @code{GL_PACK_SKIP_ROWS} to @r{@var{j}} is equivalent to | |
16458 | incrementing the pointer by @r{@var{j}@var{m}} components or indices, | |
16459 | where @r{@var{m}} is the number of components or indices per row, as | |
f37e7e3d | 16460 | just computed in the @code{GL_PACK_ROW_LENGTH} section. Setting |
3c9b6116 AW |
16461 | @code{GL_PACK_SKIP_IMAGES} to @r{@var{k}} is equivalent to incrementing |
16462 | the pointer by @r{@var{k}@var{p}}, where @r{@var{p}} is the number of | |
16463 | components or indices per image, as computed in the | |
16464 | @code{GL_PACK_IMAGE_HEIGHT} section. | |
8925f36f AW |
16465 | |
16466 | @item @code{GL_PACK_ALIGNMENT} | |
16467 | Specifies the alignment requirements for the start of each pixel row in | |
f37e7e3d | 16468 | memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to |
8925f36f AW |
16469 | even-numbered bytes), 4 (word-alignment), and 8 (rows start on |
16470 | double-word boundaries). | |
16471 | ||
16472 | @end table | |
16473 | ||
16474 | The other six of the twelve storage parameters affect how pixel data is | |
f37e7e3d | 16475 | read from client memory. These values are significant for |
8925f36f AW |
16476 | @code{glDrawPixels}, @code{glTexImage1D}, @code{glTexImage2D}, |
16477 | @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, | |
16478 | @code{glTexSubImage3D}, @code{glBitmap}, and @code{glPolygonStipple}. | |
16479 | ||
16480 | Additionally, if the @code{ARB_imaging} extension is supported, | |
16481 | @code{glColorTable}, @code{glColorSubTable}, | |
16482 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and | |
f37e7e3d | 16483 | @code{glSeparableFilter2D}. They are as follows: |
8925f36f AW |
16484 | |
16485 | @table @asis | |
16486 | @item @code{GL_UNPACK_SWAP_BYTES} | |
16487 | If true, byte ordering for multibyte color components, depth components, | |
f37e7e3d | 16488 | color indices, or stencil indices is reversed. That is, if a four-byte |
3c9b6116 AW |
16489 | component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2}, |
16490 | @r{@var{b}_3}, it is taken from memory as @r{@var{b}_3}, @r{@var{b}_2}, | |
16491 | @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_UNPACK_SWAP_BYTES} is true. | |
16492 | @code{GL_UNPACK_SWAP_BYTES} has no effect on the memory order of | |
16493 | components within a pixel, only on the order of bytes within components | |
f37e7e3d | 16494 | or indices. For example, the three components of a @code{GL_RGB} format |
3c9b6116 AW |
16495 | pixel are always stored with red first, green second, and blue third, |
16496 | regardless of the value of @code{GL_UNPACK_SWAP_BYTES}. | |
8925f36f AW |
16497 | |
16498 | @item @code{GL_UNPACK_LSB_FIRST} | |
16499 | If true, bits are ordered within a byte from least significant to most | |
16500 | significant; otherwise, the first bit in each byte is the most | |
f37e7e3d | 16501 | significant one. This is relevant only for bitmap data. |
8925f36f AW |
16502 | |
16503 | @item @code{GL_UNPACK_ROW_LENGTH} | |
16504 | If greater than 0, @code{GL_UNPACK_ROW_LENGTH} defines the number of | |
f37e7e3d | 16505 | pixels in a row. If the first pixel of a row is placed at location |
3c9b6116 AW |
16506 | @r{@var{p}} in memory, then the location of the first pixel of the next |
16507 | row is obtained by skipping | |
8925f36f | 16508 | |
3c9b6116 | 16509 | @r{@var{k}=@{(@var{n}@var{l}), |
8925f36f AW |
16510 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}), |
16511 | (@var{s}<@var{a}),} | |
16512 | ||
3c9b6116 AW |
16513 | components or indices, where @r{@var{n}} is the number of components or |
16514 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
8925f36f | 16515 | (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the |
3c9b6116 AW |
16516 | @r{@var{width}} argument to the pixel routine otherwise), @r{@var{a}} is |
16517 | the value of @code{GL_UNPACK_ALIGNMENT}, and @r{@var{s}} is the size, in | |
16518 | bytes, of a single component (if @r{@var{a}<@var{s}}, then it is as if | |
f37e7e3d | 16519 | @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the |
3c9b6116 | 16520 | next row is obtained by skipping |
8925f36f | 16521 | |
3c9b6116 | 16522 | @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉} |
8925f36f AW |
16523 | |
16524 | components or indices. | |
16525 | ||
16526 | The word @var{component} in this description refers to the nonindex | |
f37e7e3d DH |
16527 | values red, green, blue, alpha, and depth. Storage format @code{GL_RGB}, |
16528 | for example, has three components per pixel: first red, then green, and | |
16529 | finally blue. | |
8925f36f AW |
16530 | |
16531 | @item @code{GL_UNPACK_IMAGE_HEIGHT} | |
16532 | If greater than 0, @code{GL_UNPACK_IMAGE_HEIGHT} defines the number of | |
f37e7e3d | 16533 | pixels in an image of a three-dimensional texture volume. Where |
8925f36f | 16534 | ``image'' is defined by all pixel sharing the same third dimension |
f37e7e3d | 16535 | index. If the first pixel of a row is placed at location @r{@var{p}} in |
3c9b6116 AW |
16536 | memory, then the location of the first pixel of the next row is obtained |
16537 | by skipping | |
8925f36f | 16538 | |
3c9b6116 | 16539 | @r{@var{k}=@{(@var{n}@var{l}@var{h}), |
8925f36f AW |
16540 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}), |
16541 | (@var{s}<@var{a}),} | |
16542 | ||
3c9b6116 AW |
16543 | components or indices, where @r{@var{n}} is the number of components or |
16544 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
8925f36f | 16545 | (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the |
3c9b6116 AW |
16546 | @r{@var{width}} argument to @code{glTexImage3D} otherwise), @r{@var{h}} |
16547 | is the number of rows in an image (@code{GL_UNPACK_IMAGE_HEIGHT} if it | |
16548 | is greater than 0, the @r{@var{height}} argument to @code{glTexImage3D} | |
16549 | otherwise), @r{@var{a}} is the value of @code{GL_UNPACK_ALIGNMENT}, and | |
16550 | @r{@var{s}} is the size, in bytes, of a single component (if | |
16551 | @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}). | |
8925f36f AW |
16552 | |
16553 | The word @var{component} in this description refers to the nonindex | |
f37e7e3d DH |
16554 | values red, green, blue, alpha, and depth. Storage format @code{GL_RGB}, |
16555 | for example, has three components per pixel: first red, then green, and | |
16556 | finally blue. | |
8925f36f AW |
16557 | |
16558 | @item @code{GL_UNPACK_SKIP_PIXELS} and @code{GL_UNPACK_SKIP_ROWS} | |
16559 | These values are provided as a convenience to the programmer; they | |
16560 | provide no functionality that cannot be duplicated by incrementing the | |
16561 | pointer passed to @code{glDrawPixels}, @code{glTexImage1D}, | |
16562 | @code{glTexImage2D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, | |
f37e7e3d | 16563 | @code{glBitmap}, or @code{glPolygonStipple}. Setting |
3c9b6116 AW |
16564 | @code{GL_UNPACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to |
16565 | incrementing the pointer by @r{@var{i}@var{n}} components or indices, | |
16566 | where @r{@var{n}} is the number of components or indices in each pixel. | |
16567 | Setting @code{GL_UNPACK_SKIP_ROWS} to @r{@var{j}} is equivalent to | |
16568 | incrementing the pointer by @r{@var{j}@var{k}} components or indices, | |
16569 | where @r{@var{k}} is the number of components or indices per row, as | |
16570 | just computed in the @code{GL_UNPACK_ROW_LENGTH} section. | |
8925f36f AW |
16571 | |
16572 | @item @code{GL_UNPACK_ALIGNMENT} | |
16573 | Specifies the alignment requirements for the start of each pixel row in | |
f37e7e3d | 16574 | memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to |
8925f36f AW |
16575 | even-numbered bytes), 4 (word-alignment), and 8 (rows start on |
16576 | double-word boundaries). | |
16577 | ||
16578 | @end table | |
16579 | ||
16580 | The following table gives the type, initial value, and range of valid | |
16581 | values for each storage parameter that can be set with | |
16582 | @code{glPixelStore}. | |
16583 | ||
16584 | ||
16585 | ||
16586 | @table @asis | |
16587 | @item @strong{@var{pname}} | |
16588 | @strong{Type}, @strong{Initial Value}, @strong{Valid Range} | |
16589 | ||
16590 | @item @code{GL_PACK_SWAP_BYTES} | |
16591 | boolean , false , true or false | |
16592 | ||
16593 | @item @code{GL_PACK_LSB_FIRST} | |
16594 | boolean , false , true or false | |
16595 | ||
16596 | @item @code{GL_PACK_ROW_LENGTH} | |
3c9b6116 | 16597 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16598 | |
16599 | @item @code{GL_PACK_IMAGE_HEIGHT} | |
3c9b6116 | 16600 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16601 | |
16602 | @item @code{GL_PACK_SKIP_ROWS} | |
3c9b6116 | 16603 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16604 | |
16605 | @item @code{GL_PACK_SKIP_PIXELS} | |
3c9b6116 | 16606 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16607 | |
16608 | @item @code{GL_PACK_SKIP_IMAGES} | |
3c9b6116 | 16609 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16610 | |
16611 | @item @code{GL_PACK_ALIGNMENT} | |
16612 | integer , 4 , 1, 2, 4, or 8 | |
16613 | ||
16614 | @item @code{GL_UNPACK_SWAP_BYTES} | |
16615 | boolean , false , true or false | |
16616 | ||
16617 | @item @code{GL_UNPACK_LSB_FIRST} | |
16618 | boolean , false , true or false | |
16619 | ||
16620 | @item @code{GL_UNPACK_ROW_LENGTH} | |
3c9b6116 | 16621 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16622 | |
16623 | @item @code{GL_UNPACK_IMAGE_HEIGHT} | |
3c9b6116 | 16624 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16625 | |
16626 | @item @code{GL_UNPACK_SKIP_ROWS} | |
3c9b6116 | 16627 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16628 | |
16629 | @item @code{GL_UNPACK_SKIP_PIXELS} | |
3c9b6116 | 16630 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16631 | |
16632 | @item @code{GL_UNPACK_SKIP_IMAGES} | |
3c9b6116 | 16633 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16634 | |
16635 | @item @code{GL_UNPACK_ALIGNMENT} | |
16636 | integer , 4 , 1, 2, 4, or 8 | |
16637 | ||
16638 | @end table | |
16639 | ||
f37e7e3d | 16640 | @code{glPixelStoref} can be used to set any pixel store parameter. If |
8925f36f | 16641 | the parameter type is boolean, then if @var{param} is 0, the parameter |
f37e7e3d | 16642 | is false; otherwise it is set to true. If @var{pname} is a integer type |
8925f36f AW |
16643 | parameter, @var{param} is rounded to the nearest integer. |
16644 | ||
16645 | Likewise, @code{glPixelStorei} can also be used to set any of the pixel | |
f37e7e3d | 16646 | store parameters. Boolean parameters are set to false if @var{param} is |
8925f36f AW |
16647 | 0 and true otherwise. |
16648 | ||
8925f36f AW |
16649 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
16650 | value. | |
16651 | ||
16652 | @code{GL_INVALID_VALUE} is generated if a negative row length, pixel | |
16653 | skip, or row skip value is specified, or if alignment is specified as | |
16654 | other than 1, 2, 4, or 8. | |
16655 | ||
16656 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelStore} is | |
16657 | executed between the execution of @code{glBegin} and the corresponding | |
16658 | execution of @code{glEnd}. | |
16659 | ||
bb894c9d | 16660 | @end deftypefun |
8925f36f | 16661 | |
bb894c9d AW |
16662 | @deftypefun void glPixelTransferf pname param |
16663 | @deftypefunx void glPixelTransferi pname param | |
3c9b6116 AW |
16664 | Set pixel transfer modes. |
16665 | ||
8925f36f AW |
16666 | @table @asis |
16667 | @item @var{pname} | |
16668 | Specifies the symbolic name of the pixel transfer parameter to be set. | |
16669 | Must be one of the following: @code{GL_MAP_COLOR}, | |
16670 | @code{GL_MAP_STENCIL}, @code{GL_INDEX_SHIFT}, @code{GL_INDEX_OFFSET}, | |
16671 | @code{GL_RED_SCALE}, @code{GL_RED_BIAS}, @code{GL_GREEN_SCALE}, | |
16672 | @code{GL_GREEN_BIAS}, @code{GL_BLUE_SCALE}, @code{GL_BLUE_BIAS}, | |
16673 | @code{GL_ALPHA_SCALE}, @code{GL_ALPHA_BIAS}, @code{GL_DEPTH_SCALE}, or | |
16674 | @code{GL_DEPTH_BIAS}. | |
16675 | ||
16676 | Additionally, if the @code{ARB_imaging} extension is supported, the | |
16677 | following symbolic names are accepted: | |
16678 | @code{GL_POST_COLOR_MATRIX_RED_SCALE}, | |
16679 | @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}, | |
16680 | @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}, | |
16681 | @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}, | |
16682 | @code{GL_POST_COLOR_MATRIX_RED_BIAS}, | |
16683 | @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}, | |
16684 | @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}, | |
16685 | @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}, | |
16686 | @code{GL_POST_CONVOLUTION_RED_SCALE}, | |
16687 | @code{GL_POST_CONVOLUTION_GREEN_SCALE}, | |
16688 | @code{GL_POST_CONVOLUTION_BLUE_SCALE}, | |
16689 | @code{GL_POST_CONVOLUTION_ALPHA_SCALE}, | |
16690 | @code{GL_POST_CONVOLUTION_RED_BIAS}, | |
16691 | @code{GL_POST_CONVOLUTION_GREEN_BIAS}, | |
16692 | @code{GL_POST_CONVOLUTION_BLUE_BIAS}, and | |
16693 | @code{GL_POST_CONVOLUTION_ALPHA_BIAS}. | |
16694 | ||
16695 | @item @var{param} | |
16696 | Specifies the value that @var{pname} is set to. | |
16697 | ||
16698 | @end table | |
16699 | ||
8925f36f AW |
16700 | @code{glPixelTransfer} sets pixel transfer modes that affect the |
16701 | operation of subsequent @code{glCopyPixels}, @code{glCopyTexImage1D}, | |
16702 | @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D}, | |
16703 | @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D}, | |
16704 | @code{glDrawPixels}, @code{glReadPixels}, @code{glTexImage1D}, | |
16705 | @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D}, | |
16706 | @code{glTexSubImage2D}, and @code{glTexSubImage3D} commands. | |
16707 | Additionally, if the @code{ARB_imaging} subset is supported, the | |
16708 | routines @code{glColorTable}, @code{glColorSubTable}, | |
16709 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, | |
16710 | @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D} are | |
f37e7e3d DH |
16711 | also affected. The algorithms that are specified by pixel transfer modes |
16712 | operate on pixels after they are read from the frame buffer | |
8925f36f AW |
16713 | (@code{glCopyPixels}@code{glCopyTexImage1D}, @code{glCopyTexImage2D}, |
16714 | @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, | |
16715 | @code{glCopyTexSubImage3D}, and @code{glReadPixels}), or unpacked from | |
16716 | client memory (@code{glDrawPixels}, @code{glTexImage1D}, | |
16717 | @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D}, | |
f37e7e3d | 16718 | @code{glTexSubImage2D}, and @code{glTexSubImage3D}). Pixel transfer |
8925f36f | 16719 | operations happen in the same order, and in the same manner, regardless |
f37e7e3d DH |
16720 | of the command that resulted in the pixel operation. Pixel storage modes |
16721 | (see @code{glPixelStore}) control the unpacking of pixels being read | |
16722 | from client memory and the packing of pixels being written back into | |
16723 | client memory. | |
8925f36f AW |
16724 | |
16725 | Pixel transfer operations handle four fundamental pixel types: | |
16726 | @var{color}, @var{color index}, @var{depth}, and @var{stencil}. | |
16727 | @var{Color} pixels consist of four floating-point values with | |
16728 | unspecified mantissa and exponent sizes, scaled such that 0 represents | |
f37e7e3d | 16729 | zero intensity and 1 represents full intensity. @var{Color indices} |
8925f36f | 16730 | comprise a single fixed-point value, with unspecified precision to the |
f37e7e3d | 16731 | right of the binary point. @var{Depth} pixels comprise a single |
8925f36f AW |
16732 | floating-point value, with unspecified mantissa and exponent sizes, |
16733 | scaled such that 0.0 represents the minimum depth buffer value, and 1.0 | |
f37e7e3d DH |
16734 | represents the maximum depth buffer value. Finally, @var{stencil} pixels |
16735 | comprise a single fixed-point value, with unspecified precision to the | |
16736 | right of the binary point. | |
8925f36f AW |
16737 | |
16738 | The pixel transfer operations performed on the four basic pixel types | |
16739 | are as follows: | |
16740 | ||
16741 | @table @asis | |
16742 | @item @var{Color} | |
16743 | Each of the four color components is multiplied by a scale factor, then | |
f37e7e3d | 16744 | added to a bias factor. That is, the red component is multiplied by |
8925f36f AW |
16745 | @code{GL_RED_SCALE}, then added to @code{GL_RED_BIAS}; the green |
16746 | component is multiplied by @code{GL_GREEN_SCALE}, then added to | |
16747 | @code{GL_GREEN_BIAS}; the blue component is multiplied by | |
16748 | @code{GL_BLUE_SCALE}, then added to @code{GL_BLUE_BIAS}; and the alpha | |
16749 | component is multiplied by @code{GL_ALPHA_SCALE}, then added to | |
f37e7e3d DH |
16750 | @code{GL_ALPHA_BIAS}. After all four color components are scaled and |
16751 | biased, each is clamped to the range @r{[0,1]}. All color, scale, and | |
8925f36f AW |
16752 | bias values are specified with @code{glPixelTransfer}. |
16753 | ||
16754 | If @code{GL_MAP_COLOR} is true, each color component is scaled by the | |
16755 | size of the corresponding color-to-color map, then replaced by the | |
f37e7e3d | 16756 | contents of that map indexed by the scaled component. That is, the red |
8925f36f | 16757 | component is scaled by @code{GL_PIXEL_MAP_R_TO_R_SIZE}, then replaced by |
f37e7e3d | 16758 | the contents of @code{GL_PIXEL_MAP_R_TO_R} indexed by itself. The green |
8925f36f | 16759 | component is scaled by @code{GL_PIXEL_MAP_G_TO_G_SIZE}, then replaced by |
f37e7e3d | 16760 | the contents of @code{GL_PIXEL_MAP_G_TO_G} indexed by itself. The blue |
8925f36f | 16761 | component is scaled by @code{GL_PIXEL_MAP_B_TO_B_SIZE}, then replaced by |
f37e7e3d | 16762 | the contents of @code{GL_PIXEL_MAP_B_TO_B} indexed by itself. And the |
8925f36f AW |
16763 | alpha component is scaled by @code{GL_PIXEL_MAP_A_TO_A_SIZE}, then |
16764 | replaced by the contents of @code{GL_PIXEL_MAP_A_TO_A} indexed by | |
f37e7e3d DH |
16765 | itself. All components taken from the maps are then clamped to the range |
16766 | @r{[0,1]}. @code{GL_MAP_COLOR} is specified with @code{glPixelTransfer}. | |
16767 | The contents of the various maps are specified with @code{glPixelMap}. | |
8925f36f AW |
16768 | |
16769 | If the @code{ARB_imaging} extension is supported, each of the four color | |
16770 | components may be scaled and biased after transformation by the color | |
f37e7e3d | 16771 | matrix. That is, the red component is multiplied by |
8925f36f AW |
16772 | @code{GL_POST_COLOR_MATRIX_RED_SCALE}, then added to |
16773 | @code{GL_POST_COLOR_MATRIX_RED_BIAS}; the green component is multiplied | |
16774 | by @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}, then added to | |
16775 | @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}; the blue component is multiplied | |
16776 | by @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}, then added to | |
16777 | @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}; and the alpha component is | |
16778 | multiplied by @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}, then added to | |
f37e7e3d | 16779 | @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}. After all four color components |
3c9b6116 | 16780 | are scaled and biased, each is clamped to the range @r{[0,1]}. |
8925f36f AW |
16781 | |
16782 | Similarly, if the @code{ARB_imaging} extension is supported, each of the | |
16783 | four color components may be scaled and biased after processing by the | |
f37e7e3d | 16784 | enabled convolution filter. That is, the red component is multiplied by |
8925f36f AW |
16785 | @code{GL_POST_CONVOLUTION_RED_SCALE}, then added to |
16786 | @code{GL_POST_CONVOLUTION_RED_BIAS}; the green component is multiplied | |
16787 | by @code{GL_POST_CONVOLUTION_GREEN_SCALE}, then added to | |
16788 | @code{GL_POST_CONVOLUTION_GREEN_BIAS}; the blue component is multiplied | |
16789 | by @code{GL_POST_CONVOLUTION_BLUE_SCALE}, then added to | |
16790 | @code{GL_POST_CONVOLUTION_BLUE_BIAS}; and the alpha component is | |
16791 | multiplied by @code{GL_POST_CONVOLUTION_ALPHA_SCALE}, then added to | |
f37e7e3d | 16792 | @code{GL_POST_CONVOLUTION_ALPHA_BIAS}. After all four color components |
3c9b6116 | 16793 | are scaled and biased, each is clamped to the range @r{[0,1]}. |
8925f36f AW |
16794 | |
16795 | @item @var{Color index} | |
16796 | Each color index is shifted left by @code{GL_INDEX_SHIFT} bits; any bits | |
16797 | beyond the number of fraction bits carried by the fixed-point index are | |
f37e7e3d DH |
16798 | filled with zeros. If @code{GL_INDEX_SHIFT} is negative, the shift is to |
16799 | the right, again zero filled. Then @code{GL_INDEX_OFFSET} is added to | |
16800 | the index. @code{GL_INDEX_SHIFT} and @code{GL_INDEX_OFFSET} are | |
8925f36f AW |
16801 | specified with @code{glPixelTransfer}. |
16802 | ||
16803 | From this point, operation diverges depending on the required format of | |
f37e7e3d | 16804 | the resulting pixels. If the resulting pixels are to be written to a |
8925f36f AW |
16805 | color index buffer, or if they are being read back to client memory in |
16806 | @code{GL_COLOR_INDEX} format, the pixels continue to be treated as | |
f37e7e3d | 16807 | indices. If @code{GL_MAP_COLOR} is true, each index is masked by |
3c9b6116 AW |
16808 | @r{2^@var{n}-1}, where @r{@var{n}} is @code{GL_PIXEL_MAP_I_TO_I_SIZE}, |
16809 | then replaced by the contents of @code{GL_PIXEL_MAP_I_TO_I} indexed by | |
f37e7e3d DH |
16810 | the masked value. @code{GL_MAP_COLOR} is specified with |
16811 | @code{glPixelTransfer}. The contents of the index map is specified with | |
3c9b6116 | 16812 | @code{glPixelMap}. |
8925f36f AW |
16813 | |
16814 | If the resulting pixels are to be written to an RGBA color buffer, or if | |
16815 | they are read back to client memory in a format other than | |
16816 | @code{GL_COLOR_INDEX}, the pixels are converted from indices to colors | |
16817 | by referencing the four maps @code{GL_PIXEL_MAP_I_TO_R}, | |
16818 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
f37e7e3d | 16819 | @code{GL_PIXEL_MAP_I_TO_A}. Before being dereferenced, the index is |
3c9b6116 | 16820 | masked by @r{2^@var{n}-1}, where @r{@var{n}} is |
8925f36f AW |
16821 | @code{GL_PIXEL_MAP_I_TO_R_SIZE} for the red map, |
16822 | @code{GL_PIXEL_MAP_I_TO_G_SIZE} for the green map, | |
16823 | @code{GL_PIXEL_MAP_I_TO_B_SIZE} for the blue map, and | |
f37e7e3d DH |
16824 | @code{GL_PIXEL_MAP_I_TO_A_SIZE} for the alpha map. All components taken |
16825 | from the maps are then clamped to the range @r{[0,1]}. The contents of | |
3c9b6116 | 16826 | the four maps is specified with @code{glPixelMap}. |
8925f36f AW |
16827 | |
16828 | @item @var{Depth} | |
16829 | Each depth value is multiplied by @code{GL_DEPTH_SCALE}, added to | |
3c9b6116 | 16830 | @code{GL_DEPTH_BIAS}, then clamped to the range @r{[0,1]}. |
8925f36f AW |
16831 | |
16832 | @item @var{Stencil} | |
16833 | Each index is shifted @code{GL_INDEX_SHIFT} bits just as a color index | |
f37e7e3d | 16834 | is, then added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_STENCIL} is |
3c9b6116 AW |
16835 | true, each index is masked by @r{2^@var{n}-1}, where @r{@var{n}} is |
16836 | @code{GL_PIXEL_MAP_S_TO_S_SIZE}, then replaced by the contents of | |
8925f36f AW |
16837 | @code{GL_PIXEL_MAP_S_TO_S} indexed by the masked value. |
16838 | ||
16839 | @end table | |
16840 | ||
16841 | The following table gives the type, initial value, and range of valid | |
16842 | values for each of the pixel transfer parameters that are set with | |
16843 | @code{glPixelTransfer}. | |
16844 | ||
16845 | ||
16846 | ||
16847 | @table @asis | |
16848 | @item @strong{@var{pname}} | |
16849 | @strong{Type}, @strong{Initial Value}, @strong{Valid Range} | |
16850 | ||
16851 | @item @code{GL_MAP_COLOR} | |
16852 | boolean , false , true/false | |
16853 | ||
16854 | @item @code{GL_MAP_STENCIL} | |
16855 | boolean , false , true/false | |
16856 | ||
16857 | @item @code{GL_INDEX_SHIFT} | |
3c9b6116 | 16858 | integer , 0 , @r{(-∞,∞)} |
8925f36f AW |
16859 | |
16860 | @item @code{GL_INDEX_OFFSET} | |
3c9b6116 | 16861 | integer , 0 , @r{(-∞,∞)} |
8925f36f AW |
16862 | |
16863 | @item @code{GL_RED_SCALE} | |
3c9b6116 | 16864 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16865 | |
16866 | @item @code{GL_GREEN_SCALE} | |
3c9b6116 | 16867 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16868 | |
16869 | @item @code{GL_BLUE_SCALE} | |
3c9b6116 | 16870 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16871 | |
16872 | @item @code{GL_ALPHA_SCALE} | |
3c9b6116 | 16873 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16874 | |
16875 | @item @code{GL_DEPTH_SCALE} | |
3c9b6116 | 16876 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16877 | |
16878 | @item @code{GL_RED_BIAS} | |
3c9b6116 | 16879 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16880 | |
16881 | @item @code{GL_GREEN_BIAS} | |
3c9b6116 | 16882 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16883 | |
16884 | @item @code{GL_BLUE_BIAS} | |
3c9b6116 | 16885 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16886 | |
16887 | @item @code{GL_ALPHA_BIAS} | |
3c9b6116 | 16888 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16889 | |
16890 | @item @code{GL_DEPTH_BIAS} | |
3c9b6116 | 16891 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16892 | |
16893 | @item @code{GL_POST_COLOR_MATRIX_RED_SCALE} | |
3c9b6116 | 16894 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16895 | |
16896 | @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE} | |
3c9b6116 | 16897 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16898 | |
16899 | @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE} | |
3c9b6116 | 16900 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16901 | |
16902 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE} | |
3c9b6116 | 16903 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16904 | |
16905 | @item @code{GL_POST_COLOR_MATRIX_RED_BIAS} | |
3c9b6116 | 16906 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16907 | |
16908 | @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS} | |
3c9b6116 | 16909 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16910 | |
16911 | @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS} | |
3c9b6116 | 16912 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16913 | |
16914 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS} | |
3c9b6116 | 16915 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16916 | |
16917 | @item @code{GL_POST_CONVOLUTION_RED_SCALE} | |
3c9b6116 | 16918 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16919 | |
16920 | @item @code{GL_POST_CONVOLUTION_GREEN_SCALE} | |
3c9b6116 | 16921 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16922 | |
16923 | @item @code{GL_POST_CONVOLUTION_BLUE_SCALE} | |
3c9b6116 | 16924 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16925 | |
16926 | @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE} | |
3c9b6116 | 16927 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16928 | |
16929 | @item @code{GL_POST_CONVOLUTION_RED_BIAS} | |
3c9b6116 | 16930 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16931 | |
16932 | @item @code{GL_POST_CONVOLUTION_GREEN_BIAS} | |
3c9b6116 | 16933 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16934 | |
16935 | @item @code{GL_POST_CONVOLUTION_BLUE_BIAS} | |
3c9b6116 | 16936 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16937 | |
16938 | @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS} | |
3c9b6116 | 16939 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16940 | |
16941 | @end table | |
16942 | ||
16943 | @code{glPixelTransferf} can be used to set any pixel transfer parameter. | |
16944 | If the parameter type is boolean, 0 implies false and any other value | |
f37e7e3d | 16945 | implies true. If @var{pname} is an integer parameter, @var{param} is |
8925f36f AW |
16946 | rounded to the nearest integer. |
16947 | ||
16948 | Likewise, @code{glPixelTransferi} can be used to set any of the pixel | |
f37e7e3d DH |
16949 | transfer parameters. Boolean parameters are set to false if @var{param} |
16950 | is 0 and to true otherwise. @var{param} is converted to floating point | |
8925f36f AW |
16951 | before being assigned to real-valued parameters. |
16952 | ||
8925f36f AW |
16953 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
16954 | value. | |
16955 | ||
16956 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelTransfer} is | |
16957 | executed between the execution of @code{glBegin} and the corresponding | |
16958 | execution of @code{glEnd}. | |
16959 | ||
bb894c9d | 16960 | @end deftypefun |
8925f36f | 16961 | |
bb894c9d | 16962 | @deftypefun void glPixelZoom xfactor yfactor |
3c9b6116 AW |
16963 | Specify the pixel zoom factors. |
16964 | ||
8925f36f AW |
16965 | @table @asis |
16966 | @item @var{xfactor} | |
16967 | @itemx @var{yfactor} | |
3c9b6116 AW |
16968 | Specify the @r{@var{x}} and @r{@var{y}} zoom factors for pixel write |
16969 | operations. | |
8925f36f AW |
16970 | |
16971 | @end table | |
16972 | ||
3c9b6116 | 16973 | @code{glPixelZoom} specifies values for the @r{@var{x}} and @r{@var{y}} |
f37e7e3d | 16974 | zoom factors. During the execution of @code{glDrawPixels} or |
3c9b6116 AW |
16975 | @code{glCopyPixels}, if (@r{@var{xr}}, @r{@var{yr}}) is the current |
16976 | raster position, and a given element is in the @r{@var{m}}th row and | |
16977 | @r{@var{n}}th column of the pixel rectangle, then pixels whose centers | |
16978 | are in the rectangle with corners at | |
8925f36f | 16979 | |
3c9b6116 | 16980 | (@r{@var{xr}+@var{n}·@var{xfactor}}, @r{@var{yr}+@var{m}·@var{yfactor}}) |
8925f36f | 16981 | |
3c9b6116 AW |
16982 | (@r{@var{xr}+(@var{n}+1,)·@var{xfactor}}, |
16983 | @r{@var{yr}+(@var{m}+1,)·@var{yfactor}}) | |
8925f36f | 16984 | |
f37e7e3d | 16985 | are candidates for replacement. Any pixel whose center lies on the |
8925f36f AW |
16986 | bottom or left edge of this rectangular region is also modified. |
16987 | ||
f37e7e3d | 16988 | Pixel zoom factors are not limited to positive values. Negative zoom |
8925f36f AW |
16989 | factors reflect the resulting image about the current raster position. |
16990 | ||
8925f36f AW |
16991 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelZoom} is |
16992 | executed between the execution of @code{glBegin} and the corresponding | |
16993 | execution of @code{glEnd}. | |
16994 | ||
bb894c9d | 16995 | @end deftypefun |
8925f36f | 16996 | |
bb894c9d AW |
16997 | @deftypefun void glPointParameterf pname param |
16998 | @deftypefunx void glPointParameteri pname param | |
d172eed9 AW |
16999 | @deftypefunx void glPointParameterfv pname params |
17000 | @deftypefunx void glPointParameteriv pname params | |
3c9b6116 AW |
17001 | Specify point parameters. |
17002 | ||
8925f36f AW |
17003 | @table @asis |
17004 | @item @var{pname} | |
f37e7e3d | 17005 | Specifies a single-valued point parameter. @code{GL_POINT_SIZE_MIN}, |
8925f36f AW |
17006 | @code{GL_POINT_SIZE_MAX}, @code{GL_POINT_FADE_THRESHOLD_SIZE}, and |
17007 | @code{GL_POINT_SPRITE_COORD_ORIGIN} are accepted. | |
17008 | ||
17009 | @item @var{param} | |
17010 | Specifies the value that @var{pname} will be set to. | |
17011 | ||
17012 | @end table | |
17013 | ||
8925f36f AW |
17014 | The following values are accepted for @var{pname}: |
17015 | ||
17016 | @table @asis | |
17017 | @item @code{GL_POINT_SIZE_MIN} | |
17018 | ||
17019 | ||
17020 | @var{params} is a single floating-point value that specifies the minimum | |
f37e7e3d | 17021 | point size. The default value is 0.0. |
8925f36f AW |
17022 | |
17023 | @item @code{GL_POINT_SIZE_MAX} | |
17024 | ||
17025 | ||
17026 | @var{params} is a single floating-point value that specifies the maximum | |
f37e7e3d | 17027 | point size. The default value is 1.0. |
8925f36f AW |
17028 | |
17029 | @item @code{GL_POINT_FADE_THRESHOLD_SIZE} | |
17030 | ||
17031 | ||
17032 | @var{params} is a single floating-point value that specifies the | |
17033 | threshold value to which point sizes are clamped if they exceed the | |
f37e7e3d | 17034 | specified value. The default value is 1.0. |
8925f36f AW |
17035 | |
17036 | @item @code{GL_POINT_DISTANCE_ATTENUATION} | |
17037 | ||
17038 | ||
17039 | @var{params} is an array of three floating-point values that specify the | |
f37e7e3d | 17040 | coefficients used for scaling the computed point size. The default |
3c9b6116 | 17041 | values are @r{(1,00)}. |
8925f36f AW |
17042 | |
17043 | @item @code{GL_POINT_SPRITE_COORD_ORIGIN} | |
17044 | ||
17045 | ||
17046 | @var{params} is a single enum specifying the point sprite texture | |
17047 | coordinate origin, either @code{GL_LOWER_LEFT} or @code{GL_UPPER_LEFT}. | |
17048 | The default value is @code{GL_UPPER_LEFT}. | |
17049 | ||
17050 | @end table | |
17051 | ||
8925f36f AW |
17052 | @code{GL_INVALID_VALUE} is generated If the value specified for |
17053 | @code{GL_POINT_SIZE_MIN}, @code{GL_POINT_SIZE_MAX}, or | |
17054 | @code{GL_POINT_FADE_THRESHOLD_SIZE} is less than zero. | |
17055 | ||
17056 | @code{GL_INVALID_ENUM} is generated If the value specified for | |
17057 | @code{GL_POINT_SPRITE_COORD_ORIGIN} is not @code{GL_LOWER_LEFT} or | |
17058 | @code{GL_UPPER_LEFT}. | |
17059 | ||
17060 | If the value for @code{GL_POINT_SIZE_MIN} is greater than | |
17061 | @code{GL_POINT_SIZE_MAX}, the point size after clamping is undefined, | |
17062 | but no error is generated. | |
17063 | ||
17064 | ||
17065 | ||
bb894c9d | 17066 | @end deftypefun |
8925f36f | 17067 | |
bb894c9d | 17068 | @deftypefun void glPointSize size |
3c9b6116 AW |
17069 | Specify the diameter of rasterized points. |
17070 | ||
8925f36f AW |
17071 | @table @asis |
17072 | @item @var{size} | |
f37e7e3d | 17073 | Specifies the diameter of rasterized points. The initial value is 1. |
8925f36f AW |
17074 | |
17075 | @end table | |
17076 | ||
8925f36f | 17077 | @code{glPointSize} specifies the rasterized diameter of both aliased and |
f37e7e3d DH |
17078 | antialiased points. Using a point size other than 1 has different |
17079 | effects, depending on whether point antialiasing is enabled. To enable | |
8925f36f | 17080 | and disable point antialiasing, call @code{glEnable} and |
f37e7e3d | 17081 | @code{glDisable} with argument @code{GL_POINT_SMOOTH}. Point |
8925f36f AW |
17082 | antialiasing is initially disabled. |
17083 | ||
17084 | The specified point size is multiplied with a distance attenuation | |
17085 | factor and clamped to the specified point size range, and further | |
17086 | clamped to the implementation-dependent point size range to produce the | |
17087 | derived point size using | |
17088 | ||
3c9b6116 | 17089 | @r{@var{pointSize}=@var{clamp}(@var{size}×√(1/@var{a}+@var{b}×@var{d}+@var{c}×@var{d}^2,,,),,)} |
8925f36f | 17090 | |
3c9b6116 AW |
17091 | where @r{@var{d}} is the eye-coordinate distance from the eye to the |
17092 | vertex, and @r{@var{a}}, @r{@var{b}}, and @r{@var{c}} are the distance | |
17093 | attenuation coefficients (see @code{glPointParameter}). | |
8925f36f AW |
17094 | |
17095 | If multisampling is disabled, the computed point size is used as the | |
17096 | point's width. | |
17097 | ||
17098 | If multisampling is enabled, the point may be faded by modifying the | |
17099 | point alpha value (see @code{glSampleCoverage}) instead of allowing the | |
17100 | point width to go below a given threshold (see @code{glPointParameter}). | |
17101 | In this case, the width is further modified in the following manner: | |
17102 | ||
3c9b6116 | 17103 | @r{@var{pointWidth}=@{(@var{pointSize}), |
8925f36f AW |
17104 | (@var{threshold})(@var{pointSize}>=@var{threshold}), |
17105 | (@var{otherwise}),} | |
17106 | ||
17107 | The point alpha value is modified by computing: | |
17108 | ||
3c9b6116 | 17109 | @r{@var{pointAlpha}=@{(1), |
8925f36f AW |
17110 | ((@var{pointSize}/@var{threshold},)^2)(@var{pointSize}>=@var{threshold}), |
17111 | (@var{otherwise}),} | |
17112 | ||
17113 | If point antialiasing is disabled, the actual size is determined by | |
f37e7e3d | 17114 | rounding the supplied size to the nearest integer. (If the rounding |
8925f36f | 17115 | results in the value 0, it is as if the point size were 1.) If the |
3c9b6116 AW |
17116 | rounded size is odd, then the center point (@r{@var{x}}, @r{@var{y}}) of |
17117 | the pixel fragment that represents the point is computed as | |
8925f36f | 17118 | |
3c9b6116 | 17119 | @r{(⌊@var{x}_@var{w},⌋+.5,⌊@var{y}_@var{w},⌋+.5)} |
8925f36f | 17120 | |
f37e7e3d | 17121 | where @r{@var{w}} subscripts indicate window coordinates. All pixels |
8925f36f | 17122 | that lie within the square grid of the rounded size centered at |
f37e7e3d | 17123 | (@r{@var{x}}, @r{@var{y}}) make up the fragment. If the size is even, |
3c9b6116 | 17124 | the center point is |
8925f36f | 17125 | |
3c9b6116 | 17126 | @r{(⌊@var{x}_@var{w}+.5,⌋,⌊@var{y}_@var{w}+.5,⌋)} |
8925f36f AW |
17127 | |
17128 | and the rasterized fragment's centers are the half-integer window | |
17129 | coordinates within the square of the rounded size centered at | |
f37e7e3d | 17130 | @r{(@var{x},@var{y})}. All pixel fragments produced in rasterizing a |
8925f36f AW |
17131 | nonantialiased point are assigned the same associated data, that of the |
17132 | vertex corresponding to the point. | |
17133 | ||
17134 | If antialiasing is enabled, then point rasterization produces a fragment | |
17135 | for each pixel square that intersects the region lying within the circle | |
17136 | having diameter equal to the current point size and centered at the | |
f37e7e3d | 17137 | point's @r{(@var{x}_@var{w},@var{y}_@var{w})}. The coverage value for |
8925f36f | 17138 | each fragment is the window coordinate area of the intersection of the |
f37e7e3d DH |
17139 | circular region with the corresponding pixel square. This value is saved |
17140 | and used in the final rasterization step. The data associated with each | |
17141 | fragment is the data associated with the point being rasterized. | |
8925f36f | 17142 | |
f37e7e3d DH |
17143 | Not all sizes are supported when point antialiasing is enabled. If an |
17144 | unsupported size is requested, the nearest supported size is used. Only | |
8925f36f | 17145 | size 1 is guaranteed to be supported; others depend on the |
f37e7e3d | 17146 | implementation. To query the range of supported sizes and the size |
8925f36f AW |
17147 | difference between supported sizes within the range, call @code{glGet} |
17148 | with arguments @code{GL_SMOOTH_POINT_SIZE_RANGE} and | |
f37e7e3d | 17149 | @code{GL_SMOOTH_POINT_SIZE_GRANULARITY}. For aliased points, query the |
8925f36f AW |
17150 | supported ranges and granularity with @code{glGet} with arguments |
17151 | @code{GL_ALIASED_POINT_SIZE_RANGE}. | |
17152 | ||
8925f36f AW |
17153 | @code{GL_INVALID_VALUE} is generated if @var{size} is less than or equal |
17154 | to 0. | |
17155 | ||
17156 | @code{GL_INVALID_OPERATION} is generated if @code{glPointSize} is | |
17157 | executed between the execution of @code{glBegin} and the corresponding | |
17158 | execution of @code{glEnd}. | |
17159 | ||
bb894c9d | 17160 | @end deftypefun |
8925f36f | 17161 | |
bb894c9d | 17162 | @deftypefun void glPolygonMode face mode |
3c9b6116 AW |
17163 | Select a polygon rasterization mode. |
17164 | ||
8925f36f AW |
17165 | @table @asis |
17166 | @item @var{face} | |
f37e7e3d | 17167 | Specifies the polygons that @var{mode} applies to. Must be |
8925f36f AW |
17168 | @code{GL_FRONT} for front-facing polygons, @code{GL_BACK} for |
17169 | back-facing polygons, or @code{GL_FRONT_AND_BACK} for front- and | |
17170 | back-facing polygons. | |
17171 | ||
17172 | @item @var{mode} | |
f37e7e3d DH |
17173 | Specifies how polygons will be rasterized. Accepted values are |
17174 | @code{GL_POINT}, @code{GL_LINE}, and @code{GL_FILL}. The initial value | |
8925f36f AW |
17175 | is @code{GL_FILL} for both front- and back-facing polygons. |
17176 | ||
17177 | @end table | |
17178 | ||
8925f36f | 17179 | @code{glPolygonMode} controls the interpretation of polygons for |
f37e7e3d | 17180 | rasterization. @var{face} describes which polygons @var{mode} applies |
8925f36f | 17181 | to: front-facing polygons (@code{GL_FRONT}), back-facing polygons |
f37e7e3d DH |
17182 | (@code{GL_BACK}), or both (@code{GL_FRONT_AND_BACK}). The polygon mode |
17183 | affects only the final rasterization of polygons. In particular, a | |
8925f36f AW |
17184 | polygon's vertices are lit and the polygon is clipped and possibly |
17185 | culled before these modes are applied. | |
17186 | ||
17187 | Three modes are defined and can be specified in @var{mode}: | |
17188 | ||
17189 | @table @asis | |
17190 | @item @code{GL_POINT} | |
17191 | Polygon vertices that are marked as the start of a boundary edge are | |
f37e7e3d DH |
17192 | drawn as points. Point attributes such as @code{GL_POINT_SIZE} and |
17193 | @code{GL_POINT_SMOOTH} control the rasterization of the points. Polygon | |
8925f36f AW |
17194 | rasterization attributes other than @code{GL_POLYGON_MODE} have no |
17195 | effect. | |
17196 | ||
17197 | @item @code{GL_LINE} | |
f37e7e3d | 17198 | Boundary edges of the polygon are drawn as line segments. They are |
8925f36f AW |
17199 | treated as connected line segments for line stippling; the line stipple |
17200 | counter and pattern are not reset between segments (see | |
f37e7e3d DH |
17201 | @code{glLineStipple}). Line attributes such as @code{GL_LINE_WIDTH} and |
17202 | @code{GL_LINE_SMOOTH} control the rasterization of the lines. Polygon | |
8925f36f AW |
17203 | rasterization attributes other than @code{GL_POLYGON_MODE} have no |
17204 | effect. | |
17205 | ||
17206 | @item @code{GL_FILL} | |
f37e7e3d | 17207 | The interior of the polygon is filled. Polygon attributes such as |
8925f36f AW |
17208 | @code{GL_POLYGON_STIPPLE} and @code{GL_POLYGON_SMOOTH} control the |
17209 | rasterization of the polygon. | |
17210 | ||
17211 | @end table | |
17212 | ||
8925f36f AW |
17213 | @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{mode} |
17214 | is not an accepted value. | |
17215 | ||
17216 | @code{GL_INVALID_OPERATION} is generated if @code{glPolygonMode} is | |
17217 | executed between the execution of @code{glBegin} and the corresponding | |
17218 | execution of @code{glEnd}. | |
17219 | ||
bb894c9d | 17220 | @end deftypefun |
8925f36f | 17221 | |
bb894c9d | 17222 | @deftypefun void glPolygonOffset factor units |
3c9b6116 AW |
17223 | Set the scale and units used to calculate depth values. |
17224 | ||
8925f36f AW |
17225 | @table @asis |
17226 | @item @var{factor} | |
17227 | Specifies a scale factor that is used to create a variable depth offset | |
f37e7e3d | 17228 | for each polygon. The initial value is 0. |
8925f36f AW |
17229 | |
17230 | @item @var{units} | |
17231 | Is multiplied by an implementation-specific value to create a constant | |
f37e7e3d | 17232 | depth offset. The initial value is 0. |
8925f36f AW |
17233 | |
17234 | @end table | |
17235 | ||
8925f36f AW |
17236 | When @code{GL_POLYGON_OFFSET_FILL}, @code{GL_POLYGON_OFFSET_LINE}, or |
17237 | @code{GL_POLYGON_OFFSET_POINT} is enabled, each fragment's @var{depth} | |
17238 | value will be offset after it is interpolated from the @var{depth} | |
f37e7e3d | 17239 | values of the appropriate vertices. The value of the offset is |
3c9b6116 AW |
17240 | @r{@var{factor}×@var{DZ}+@var{r}×@var{units}}, where @r{@var{DZ}} is a |
17241 | measurement of the change in depth relative to the screen area of the | |
17242 | polygon, and @r{@var{r}} is the smallest value that is guaranteed to | |
f37e7e3d | 17243 | produce a resolvable offset for a given implementation. The offset is |
8925f36f AW |
17244 | added before the depth test is performed and before the value is written |
17245 | into the depth buffer. | |
17246 | ||
17247 | @code{glPolygonOffset} is useful for rendering hidden-line images, for | |
17248 | applying decals to surfaces, and for rendering solids with highlighted | |
17249 | edges. | |
17250 | ||
8925f36f AW |
17251 | @code{GL_INVALID_OPERATION} is generated if @code{glPolygonOffset} is |
17252 | executed between the execution of @code{glBegin} and the corresponding | |
17253 | execution of @code{glEnd}. | |
17254 | ||
bb894c9d | 17255 | @end deftypefun |
8925f36f | 17256 | |
bb894c9d | 17257 | @deftypefun void glPolygonStipple pattern |
3c9b6116 AW |
17258 | Set the polygon stippling pattern. |
17259 | ||
8925f36f AW |
17260 | @table @asis |
17261 | @item @var{pattern} | |
3c9b6116 AW |
17262 | Specifies a pointer to a @r{32×32} stipple pattern that will be unpacked |
17263 | from memory in the same way that @code{glDrawPixels} unpacks pixels. | |
8925f36f AW |
17264 | |
17265 | @end table | |
17266 | ||
8925f36f AW |
17267 | Polygon stippling, like line stippling (see @code{glLineStipple}), masks |
17268 | out certain fragments produced by rasterization, creating a pattern. | |
17269 | Stippling is independent of polygon antialiasing. | |
17270 | ||
3c9b6116 AW |
17271 | @var{pattern} is a pointer to a @r{32×32} stipple pattern that is stored |
17272 | in memory just like the pixel data supplied to a @code{glDrawPixels} | |
17273 | call with height and @var{width} both equal to 32, a pixel format of | |
f37e7e3d | 17274 | @code{GL_COLOR_INDEX}, and data type of @code{GL_BITMAP}. That is, the |
3c9b6116 | 17275 | stipple pattern is represented as a @r{32×32} array of 1-bit color |
f37e7e3d | 17276 | indices packed in unsigned bytes. @code{glPixelStore} parameters like |
3c9b6116 | 17277 | @code{GL_UNPACK_SWAP_BYTES} and @code{GL_UNPACK_LSB_FIRST} affect the |
f37e7e3d DH |
17278 | assembling of the bits into a stipple pattern. Pixel transfer operations |
17279 | (shift, offset, pixel map) are not applied to the stipple image, | |
17280 | however. | |
8925f36f AW |
17281 | |
17282 | If a non-zero named buffer object is bound to the | |
17283 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
17284 | stipple pattern is specified, @var{pattern} is treated as a byte offset | |
17285 | into the buffer object's data store. | |
17286 | ||
17287 | To enable and disable polygon stippling, call @code{glEnable} and | |
f37e7e3d DH |
17288 | @code{glDisable} with argument @code{GL_POLYGON_STIPPLE}. Polygon |
17289 | stippling is initially disabled. If it's enabled, a rasterized polygon | |
3c9b6116 AW |
17290 | fragment with window coordinates @r{@var{x}_@var{w}} and |
17291 | @r{@var{y}_@var{w}} is sent to the next stage of the GL if and only if | |
17292 | the (@r{@var{x}_@var{w}%32})th bit in the (@r{@var{y}_@var{w}%32})th row | |
f37e7e3d | 17293 | of the stipple pattern is 1 (one). When polygon stippling is disabled, |
3c9b6116 AW |
17294 | it is as if the stipple pattern consists of all 1's. |
17295 | ||
8925f36f AW |
17296 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object |
17297 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
17298 | object's data store is currently mapped. | |
17299 | ||
17300 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
17301 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
17302 | would be unpacked from the buffer object such that the memory reads | |
17303 | required would exceed the data store size. | |
17304 | ||
17305 | @code{GL_INVALID_OPERATION} is generated if @code{glPolygonStipple} is | |
17306 | executed between the execution of @code{glBegin} and the corresponding | |
17307 | execution of @code{glEnd}. | |
17308 | ||
bb894c9d | 17309 | @end deftypefun |
8925f36f | 17310 | |
bb894c9d | 17311 | @deftypefun void glPrioritizeTextures n textures priorities |
3c9b6116 AW |
17312 | Set texture residence priority. |
17313 | ||
8925f36f AW |
17314 | @table @asis |
17315 | @item @var{n} | |
17316 | Specifies the number of textures to be prioritized. | |
17317 | ||
17318 | @item @var{textures} | |
17319 | Specifies an array containing the names of the textures to be | |
17320 | prioritized. | |
17321 | ||
17322 | @item @var{priorities} | |
f37e7e3d | 17323 | Specifies an array containing the texture priorities. A priority given |
8925f36f AW |
17324 | in an element of @var{priorities} applies to the texture named by the |
17325 | corresponding element of @var{textures}. | |
17326 | ||
17327 | @end table | |
17328 | ||
8925f36f AW |
17329 | @code{glPrioritizeTextures} assigns the @var{n} texture priorities given |
17330 | in @var{priorities} to the @var{n} textures named in @var{textures}. | |
17331 | ||
17332 | The GL establishes a ``working set'' of textures that are resident in | |
f37e7e3d DH |
17333 | texture memory. These textures may be bound to a texture target much |
17334 | more efficiently than textures that are not resident. By specifying a | |
8925f36f AW |
17335 | priority for each texture, @code{glPrioritizeTextures} allows |
17336 | applications to guide the GL implementation in determining which | |
17337 | textures should be resident. | |
17338 | ||
17339 | The priorities given in @var{priorities} are clamped to the range | |
f37e7e3d DH |
17340 | @r{[0,1]} before they are assigned. 0 indicates the lowest priority; |
17341 | textures with priority 0 are least likely to be resident. 1 indicates | |
8925f36f | 17342 | the highest priority; textures with priority 1 are most likely to be |
f37e7e3d DH |
17343 | resident. However, textures are not guaranteed to be resident until they |
17344 | are used. | |
8925f36f AW |
17345 | |
17346 | @code{glPrioritizeTextures} silently ignores attempts to prioritize | |
17347 | texture 0 or any texture name that does not correspond to an existing | |
17348 | texture. | |
17349 | ||
17350 | @code{glPrioritizeTextures} does not require that any of the textures | |
17351 | named by @var{textures} be bound to a texture target. | |
17352 | @code{glTexParameter} may also be used to set a texture's priority, but | |
f37e7e3d | 17353 | only if the texture is currently bound. This is the only way to set the |
8925f36f AW |
17354 | priority of a default texture. |
17355 | ||
8925f36f AW |
17356 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
17357 | ||
17358 | @code{GL_INVALID_OPERATION} is generated if @code{glPrioritizeTextures} | |
17359 | is executed between the execution of @code{glBegin} and the | |
17360 | corresponding execution of @code{glEnd}. | |
17361 | ||
bb894c9d | 17362 | @end deftypefun |
8925f36f | 17363 | |
bb894c9d AW |
17364 | @deftypefun void glPushAttrib mask |
17365 | @deftypefunx void glPopAttrib | |
3c9b6116 AW |
17366 | Push and pop the server attribute stack. |
17367 | ||
8925f36f AW |
17368 | @table @asis |
17369 | @item @var{mask} | |
f37e7e3d | 17370 | Specifies a mask that indicates which attributes to save. Values for |
8925f36f AW |
17371 | @var{mask} are listed below. |
17372 | ||
17373 | @end table | |
17374 | ||
8925f36f | 17375 | @code{glPushAttrib} takes one argument, a mask that indicates which |
f37e7e3d DH |
17376 | groups of state variables to save on the attribute stack. Symbolic |
17377 | constants are used to set bits in the mask. @var{mask} is typically | |
8925f36f | 17378 | constructed by specifying the bitwise-or of several of these constants |
f37e7e3d DH |
17379 | together. The special mask @code{GL_ALL_ATTRIB_BITS} can be used to save |
17380 | all stackable states. | |
8925f36f AW |
17381 | |
17382 | The symbolic mask constants and their associated GL state are as follows | |
17383 | (the second column lists which attributes are saved): | |
17384 | ||
17385 | ||
17386 | ||
17387 | @table @asis | |
17388 | @item @code{GL_ACCUM_BUFFER_BIT} | |
17389 | Accumulation buffer clear value | |
17390 | ||
17391 | @item @code{GL_COLOR_BUFFER_BIT} | |
17392 | @code{GL_ALPHA_TEST} enable bit | |
17393 | ||
17394 | @item | |
17395 | Alpha test function and reference value | |
17396 | ||
17397 | @item | |
17398 | @code{GL_BLEND} enable bit | |
17399 | ||
17400 | @item | |
17401 | Blending source and destination functions | |
17402 | ||
17403 | @item | |
17404 | Constant blend color | |
17405 | ||
17406 | @item | |
17407 | Blending equation | |
17408 | ||
17409 | @item | |
17410 | @code{GL_DITHER} enable bit | |
17411 | ||
17412 | @item | |
17413 | @code{GL_DRAW_BUFFER} setting | |
17414 | ||
17415 | @item | |
17416 | @code{GL_COLOR_LOGIC_OP} enable bit | |
17417 | ||
17418 | @item | |
17419 | @code{GL_INDEX_LOGIC_OP} enable bit | |
17420 | ||
17421 | @item | |
17422 | Logic op function | |
17423 | ||
17424 | @item | |
17425 | Color mode and index mode clear values | |
17426 | ||
17427 | @item | |
17428 | Color mode and index mode writemasks | |
17429 | ||
17430 | @item @code{GL_CURRENT_BIT} | |
17431 | Current RGBA color | |
17432 | ||
17433 | @item | |
17434 | Current color index | |
17435 | ||
17436 | @item | |
17437 | Current normal vector | |
17438 | ||
17439 | @item | |
17440 | Current texture coordinates | |
17441 | ||
17442 | @item | |
17443 | Current raster position | |
17444 | ||
17445 | @item | |
17446 | @code{GL_CURRENT_RASTER_POSITION_VALID} flag | |
17447 | ||
17448 | @item | |
17449 | RGBA color associated with current raster position | |
17450 | ||
17451 | @item | |
17452 | Color index associated with current raster position | |
17453 | ||
17454 | @item | |
17455 | Texture coordinates associated with current raster position | |
17456 | ||
17457 | @item | |
17458 | @code{GL_EDGE_FLAG} flag | |
17459 | ||
17460 | @item @code{GL_DEPTH_BUFFER_BIT} | |
17461 | @code{GL_DEPTH_TEST} enable bit | |
17462 | ||
17463 | @item | |
17464 | Depth buffer test function | |
17465 | ||
17466 | @item | |
17467 | Depth buffer clear value | |
17468 | ||
17469 | @item | |
17470 | @code{GL_DEPTH_WRITEMASK} enable bit | |
17471 | ||
17472 | @item @code{GL_ENABLE_BIT} | |
17473 | @code{GL_ALPHA_TEST} flag | |
17474 | ||
17475 | @item | |
17476 | @code{GL_AUTO_NORMAL} flag | |
17477 | ||
17478 | @item | |
17479 | @code{GL_BLEND} flag | |
17480 | ||
17481 | @item | |
17482 | Enable bits for the user-definable clipping planes | |
17483 | ||
17484 | @item | |
17485 | @code{GL_COLOR_MATERIAL} | |
17486 | ||
17487 | @item | |
17488 | @code{GL_CULL_FACE} flag | |
17489 | ||
17490 | @item | |
17491 | @code{GL_DEPTH_TEST} flag | |
17492 | ||
17493 | @item | |
17494 | @code{GL_DITHER} flag | |
17495 | ||
17496 | @item | |
17497 | @code{GL_FOG} flag | |
17498 | ||
17499 | @item | |
17500 | @code{GL_LIGHT}@var{i} where @code{0} <= @var{i} < @code{GL_MAX_LIGHTS} | |
17501 | ||
17502 | @item | |
17503 | @code{GL_LIGHTING} flag | |
17504 | ||
17505 | @item | |
17506 | @code{GL_LINE_SMOOTH} flag | |
17507 | ||
17508 | @item | |
17509 | @code{GL_LINE_STIPPLE} flag | |
17510 | ||
17511 | @item | |
17512 | @code{GL_COLOR_LOGIC_OP} flag | |
17513 | ||
17514 | @item | |
17515 | @code{GL_INDEX_LOGIC_OP} flag | |
17516 | ||
17517 | @item | |
17518 | @code{GL_MAP1_}@var{x} where @var{x} is a map type | |
17519 | ||
17520 | @item | |
17521 | @code{GL_MAP2_}@var{x} where @var{x} is a map type | |
17522 | ||
17523 | @item | |
17524 | @code{GL_MULTISAMPLE} flag | |
17525 | ||
17526 | @item | |
17527 | @code{GL_NORMALIZE} flag | |
17528 | ||
17529 | @item | |
17530 | @code{GL_POINT_SMOOTH} flag | |
17531 | ||
17532 | @item | |
17533 | @code{GL_POLYGON_OFFSET_LINE} flag | |
17534 | ||
17535 | @item | |
17536 | @code{GL_POLYGON_OFFSET_FILL} flag | |
17537 | ||
17538 | @item | |
17539 | @code{GL_POLYGON_OFFSET_POINT} flag | |
17540 | ||
17541 | @item | |
17542 | @code{GL_POLYGON_SMOOTH} flag | |
17543 | ||
17544 | @item | |
17545 | @code{GL_POLYGON_STIPPLE} flag | |
17546 | ||
17547 | @item | |
17548 | @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag | |
17549 | ||
17550 | @item | |
17551 | @code{GL_SAMPLE_ALPHA_TO_ONE} flag | |
17552 | ||
17553 | @item | |
17554 | @code{GL_SAMPLE_COVERAGE} flag | |
17555 | ||
17556 | @item | |
17557 | @code{GL_SCISSOR_TEST} flag | |
17558 | ||
17559 | @item | |
17560 | @code{GL_STENCIL_TEST} flag | |
17561 | ||
17562 | @item | |
17563 | @code{GL_TEXTURE_1D} flag | |
17564 | ||
17565 | @item | |
17566 | @code{GL_TEXTURE_2D} flag | |
17567 | ||
17568 | @item | |
17569 | @code{GL_TEXTURE_3D} flag | |
17570 | ||
17571 | @item | |
17572 | Flags @code{GL_TEXTURE_GEN_}@var{x} where @var{x} is S, T, R, or Q | |
17573 | ||
17574 | @item @code{GL_EVAL_BIT} | |
17575 | @code{GL_MAP1_}@var{x} enable bits, where @var{x} is a map type | |
17576 | ||
17577 | @item | |
17578 | @code{GL_MAP2_}@var{x} enable bits, where @var{x} is a map type | |
17579 | ||
17580 | @item | |
17581 | 1D grid endpoints and divisions | |
17582 | ||
17583 | @item | |
17584 | 2D grid endpoints and divisions | |
17585 | ||
17586 | @item | |
17587 | @code{GL_AUTO_NORMAL} enable bit | |
17588 | ||
17589 | @item @code{GL_FOG_BIT} | |
17590 | @code{GL_FOG} enable bit | |
17591 | ||
17592 | @item | |
17593 | Fog color | |
17594 | ||
17595 | @item | |
17596 | Fog density | |
17597 | ||
17598 | @item | |
17599 | Linear fog start | |
17600 | ||
17601 | @item | |
17602 | Linear fog end | |
17603 | ||
17604 | @item | |
17605 | Fog index | |
17606 | ||
17607 | @item | |
17608 | @code{GL_FOG_MODE} value | |
17609 | ||
17610 | @item @code{GL_HINT_BIT} | |
17611 | @code{GL_PERSPECTIVE_CORRECTION_HINT} setting | |
17612 | ||
17613 | @item | |
17614 | @code{GL_POINT_SMOOTH_HINT} setting | |
17615 | ||
17616 | @item | |
17617 | @code{GL_LINE_SMOOTH_HINT} setting | |
17618 | ||
17619 | @item | |
17620 | @code{GL_POLYGON_SMOOTH_HINT} setting | |
17621 | ||
17622 | @item | |
17623 | @code{GL_FOG_HINT} setting | |
17624 | ||
17625 | @item | |
17626 | @code{GL_GENERATE_MIPMAP_HINT} setting | |
17627 | ||
17628 | @item | |
17629 | @code{GL_TEXTURE_COMPRESSION_HINT} setting | |
17630 | ||
17631 | @item @code{GL_LIGHTING_BIT} | |
17632 | @code{GL_COLOR_MATERIAL} enable bit | |
17633 | ||
17634 | @item | |
17635 | @code{GL_COLOR_MATERIAL_FACE} value | |
17636 | ||
17637 | @item | |
17638 | Color material parameters that are tracking the current color | |
17639 | ||
17640 | @item | |
17641 | Ambient scene color | |
17642 | ||
17643 | @item | |
17644 | @code{GL_LIGHT_MODEL_LOCAL_VIEWER} value | |
17645 | ||
17646 | @item | |
17647 | @code{GL_LIGHT_MODEL_TWO_SIDE} setting | |
17648 | ||
17649 | @item | |
17650 | @code{GL_LIGHTING} enable bit | |
17651 | ||
17652 | @item | |
17653 | Enable bit for each light | |
17654 | ||
17655 | @item | |
17656 | Ambient, diffuse, and specular intensity for each light | |
17657 | ||
17658 | @item | |
17659 | Direction, position, exponent, and cutoff angle for each light | |
17660 | ||
17661 | @item | |
17662 | Constant, linear, and quadratic attenuation factors for each light | |
17663 | ||
17664 | @item | |
17665 | Ambient, diffuse, specular, and emissive color for each material | |
17666 | ||
17667 | @item | |
17668 | Ambient, diffuse, and specular color indices for each material | |
17669 | ||
17670 | @item | |
17671 | Specular exponent for each material | |
17672 | ||
17673 | @item | |
17674 | @code{GL_SHADE_MODEL} setting | |
17675 | ||
17676 | @item @code{GL_LINE_BIT} | |
17677 | @code{GL_LINE_SMOOTH} flag | |
17678 | ||
17679 | @item | |
17680 | @code{GL_LINE_STIPPLE} enable bit | |
17681 | ||
17682 | @item | |
17683 | Line stipple pattern and repeat counter | |
17684 | ||
17685 | @item | |
17686 | Line width | |
17687 | ||
17688 | @item @code{GL_LIST_BIT} | |
17689 | @code{GL_LIST_BASE} setting | |
17690 | ||
17691 | @item @code{GL_MULTISAMPLE_BIT} | |
17692 | @code{GL_MULTISAMPLE} flag | |
17693 | ||
17694 | @item | |
17695 | @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag | |
17696 | ||
17697 | @item | |
17698 | @code{GL_SAMPLE_ALPHA_TO_ONE} flag | |
17699 | ||
17700 | @item | |
17701 | @code{GL_SAMPLE_COVERAGE} flag | |
17702 | ||
17703 | @item | |
17704 | @code{GL_SAMPLE_COVERAGE_VALUE} value | |
17705 | ||
17706 | @item | |
17707 | @code{GL_SAMPLE_COVERAGE_INVERT} value | |
17708 | ||
17709 | @item @code{GL_PIXEL_MODE_BIT} | |
17710 | @code{GL_RED_BIAS} and @code{GL_RED_SCALE} settings | |
17711 | ||
17712 | @item | |
17713 | @code{GL_GREEN_BIAS} and @code{GL_GREEN_SCALE} values | |
17714 | ||
17715 | @item | |
17716 | @code{GL_BLUE_BIAS} and @code{GL_BLUE_SCALE} | |
17717 | ||
17718 | @item | |
17719 | @code{GL_ALPHA_BIAS} and @code{GL_ALPHA_SCALE} | |
17720 | ||
17721 | @item | |
17722 | @code{GL_DEPTH_BIAS} and @code{GL_DEPTH_SCALE} | |
17723 | ||
17724 | @item | |
17725 | @code{GL_INDEX_OFFSET} and @code{GL_INDEX_SHIFT} values | |
17726 | ||
17727 | @item | |
17728 | @code{GL_MAP_COLOR} and @code{GL_MAP_STENCIL} flags | |
17729 | ||
17730 | @item | |
17731 | @code{GL_ZOOM_X} and @code{GL_ZOOM_Y} factors | |
17732 | ||
17733 | @item | |
17734 | @code{GL_READ_BUFFER} setting | |
17735 | ||
17736 | @item @code{GL_POINT_BIT} | |
17737 | @code{GL_POINT_SMOOTH} flag | |
17738 | ||
17739 | @item | |
17740 | Point size | |
17741 | ||
17742 | @item @code{GL_POLYGON_BIT} | |
17743 | @code{GL_CULL_FACE} enable bit | |
17744 | ||
17745 | @item | |
17746 | @code{GL_CULL_FACE_MODE} value | |
17747 | ||
17748 | @item | |
17749 | @code{GL_FRONT_FACE} indicator | |
17750 | ||
17751 | @item | |
17752 | @code{GL_POLYGON_MODE} setting | |
17753 | ||
17754 | @item | |
17755 | @code{GL_POLYGON_SMOOTH} flag | |
17756 | ||
17757 | @item | |
17758 | @code{GL_POLYGON_STIPPLE} enable bit | |
17759 | ||
17760 | @item | |
17761 | @code{GL_POLYGON_OFFSET_FILL} flag | |
17762 | ||
17763 | @item | |
17764 | @code{GL_POLYGON_OFFSET_LINE} flag | |
17765 | ||
17766 | @item | |
17767 | @code{GL_POLYGON_OFFSET_POINT} flag | |
17768 | ||
17769 | @item | |
17770 | @code{GL_POLYGON_OFFSET_FACTOR} | |
17771 | ||
17772 | @item | |
17773 | @code{GL_POLYGON_OFFSET_UNITS} | |
17774 | ||
17775 | @item @code{GL_POLYGON_STIPPLE_BIT} | |
17776 | Polygon stipple image | |
17777 | ||
17778 | @item @code{GL_SCISSOR_BIT} | |
17779 | @code{GL_SCISSOR_TEST} flag | |
17780 | ||
17781 | @item | |
17782 | Scissor box | |
17783 | ||
17784 | @item @code{GL_STENCIL_BUFFER_BIT} | |
17785 | @code{GL_STENCIL_TEST} enable bit | |
17786 | ||
17787 | @item | |
17788 | Stencil function and reference value | |
17789 | ||
17790 | @item | |
17791 | Stencil value mask | |
17792 | ||
17793 | @item | |
17794 | Stencil fail, pass, and depth buffer pass actions | |
17795 | ||
17796 | @item | |
17797 | Stencil buffer clear value | |
17798 | ||
17799 | @item | |
17800 | Stencil buffer writemask | |
17801 | ||
17802 | @item @code{GL_TEXTURE_BIT} | |
17803 | Enable bits for the four texture coordinates | |
17804 | ||
17805 | @item | |
17806 | Border color for each texture image | |
17807 | ||
17808 | @item | |
17809 | Minification function for each texture image | |
17810 | ||
17811 | @item | |
17812 | Magnification function for each texture image | |
17813 | ||
17814 | @item | |
17815 | Texture coordinates and wrap mode for each texture image | |
17816 | ||
17817 | @item | |
17818 | Color and mode for each texture environment | |
17819 | ||
17820 | @item | |
17821 | Enable bits @code{GL_TEXTURE_GEN_}@var{x}, @var{x} is S, T, R, and Q | |
17822 | ||
17823 | @item | |
17824 | @code{GL_TEXTURE_GEN_MODE} setting for S, T, R, and Q | |
17825 | ||
17826 | @item | |
17827 | @code{glTexGen} plane equations for S, T, R, and Q | |
17828 | ||
17829 | @item | |
17830 | Current texture bindings (for example, @code{GL_TEXTURE_BINDING_2D}) | |
17831 | ||
17832 | @item @code{GL_TRANSFORM_BIT} | |
17833 | Coefficients of the six clipping planes | |
17834 | ||
17835 | @item | |
17836 | Enable bits for the user-definable clipping planes | |
17837 | ||
17838 | @item | |
17839 | @code{GL_MATRIX_MODE} value | |
17840 | ||
17841 | @item | |
17842 | @code{GL_NORMALIZE} flag | |
17843 | ||
17844 | @item | |
17845 | @code{GL_RESCALE_NORMAL} flag | |
17846 | ||
17847 | @item @code{GL_VIEWPORT_BIT} | |
17848 | Depth range (near and far) | |
17849 | ||
17850 | @item | |
17851 | Viewport origin and extent | |
17852 | ||
17853 | @end table | |
17854 | ||
17855 | @code{glPopAttrib} restores the values of the state variables saved with | |
f37e7e3d | 17856 | the last @code{glPushAttrib} command. Those not saved are left |
8925f36f AW |
17857 | unchanged. |
17858 | ||
17859 | It is an error to push attributes onto a full stack or to pop attributes | |
f37e7e3d | 17860 | off an empty stack. In either case, the error flag is set and no other |
8925f36f AW |
17861 | change is made to GL state. |
17862 | ||
17863 | Initially, the attribute stack is empty. | |
17864 | ||
8925f36f AW |
17865 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushAttrib} is called |
17866 | while the attribute stack is full. | |
17867 | ||
17868 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopAttrib} is called | |
17869 | while the attribute stack is empty. | |
17870 | ||
17871 | @code{GL_INVALID_OPERATION} is generated if @code{glPushAttrib} or | |
17872 | @code{glPopAttrib} is executed between the execution of @code{glBegin} | |
17873 | and the corresponding execution of @code{glEnd}. | |
17874 | ||
bb894c9d | 17875 | @end deftypefun |
8925f36f | 17876 | |
bb894c9d AW |
17877 | @deftypefun void glPushClientAttrib mask |
17878 | @deftypefunx void glPopClientAttrib | |
3c9b6116 AW |
17879 | Push and pop the client attribute stack. |
17880 | ||
8925f36f AW |
17881 | @table @asis |
17882 | @item @var{mask} | |
f37e7e3d | 17883 | Specifies a mask that indicates which attributes to save. Values for |
8925f36f AW |
17884 | @var{mask} are listed below. |
17885 | ||
17886 | @end table | |
17887 | ||
8925f36f AW |
17888 | @code{glPushClientAttrib} takes one argument, a mask that indicates |
17889 | which groups of client-state variables to save on the client attribute | |
f37e7e3d | 17890 | stack. Symbolic constants are used to set bits in the mask. @var{mask} |
8925f36f | 17891 | is typically constructed by specifying the bitwise-or of several of |
f37e7e3d | 17892 | these constants together. The special mask |
8925f36f AW |
17893 | @code{GL_CLIENT_ALL_ATTRIB_BITS} can be used to save all stackable |
17894 | client state. | |
17895 | ||
17896 | The symbolic mask constants and their associated GL client state are as | |
17897 | follows (the second column lists which attributes are saved): | |
17898 | ||
17899 | @code{GL_CLIENT_PIXEL_STORE_BIT} Pixel storage modes | |
17900 | @code{GL_CLIENT_VERTEX_ARRAY_BIT} Vertex arrays (and enables) | |
17901 | ||
17902 | @code{glPopClientAttrib} restores the values of the client-state | |
f37e7e3d DH |
17903 | variables saved with the last @code{glPushClientAttrib}. Those not saved |
17904 | are left unchanged. | |
8925f36f AW |
17905 | |
17906 | It is an error to push attributes onto a full client attribute stack or | |
f37e7e3d | 17907 | to pop attributes off an empty stack. In either case, the error flag is |
8925f36f AW |
17908 | set, and no other change is made to GL state. |
17909 | ||
17910 | Initially, the client attribute stack is empty. | |
17911 | ||
8925f36f AW |
17912 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushClientAttrib} is |
17913 | called while the attribute stack is full. | |
17914 | ||
17915 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopClientAttrib} is | |
17916 | called while the attribute stack is empty. | |
17917 | ||
bb894c9d | 17918 | @end deftypefun |
8925f36f | 17919 | |
bb894c9d AW |
17920 | @deftypefun void glPushMatrix |
17921 | @deftypefunx void glPopMatrix | |
3c9b6116 AW |
17922 | Push and pop the current matrix stack. |
17923 | ||
f37e7e3d DH |
17924 | There is a stack of matrices for each of the matrix modes. In |
17925 | @code{GL_MODELVIEW} mode, the stack depth is at least 32. In the other | |
8925f36f | 17926 | modes, @code{GL_COLOR}, @code{GL_PROJECTION}, and @code{GL_TEXTURE}, the |
f37e7e3d DH |
17927 | depth is at least 2. The current matrix in any mode is the matrix on the |
17928 | top of the stack for that mode. | |
8925f36f AW |
17929 | |
17930 | @code{glPushMatrix} pushes the current matrix stack down by one, | |
f37e7e3d | 17931 | duplicating the current matrix. That is, after a @code{glPushMatrix} |
8925f36f AW |
17932 | call, the matrix on top of the stack is identical to the one below it. |
17933 | ||
17934 | @code{glPopMatrix} pops the current matrix stack, replacing the current | |
17935 | matrix with the one below it on the stack. | |
17936 | ||
17937 | Initially, each of the stacks contains one matrix, an identity matrix. | |
17938 | ||
17939 | It is an error to push a full matrix stack or to pop a matrix stack that | |
f37e7e3d DH |
17940 | contains only a single matrix. In either case, the error flag is set and |
17941 | no other change is made to GL state. | |
8925f36f | 17942 | |
8925f36f AW |
17943 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushMatrix} is called |
17944 | while the current matrix stack is full. | |
17945 | ||
17946 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopMatrix} is called | |
17947 | while the current matrix stack contains only a single matrix. | |
17948 | ||
17949 | @code{GL_INVALID_OPERATION} is generated if @code{glPushMatrix} or | |
17950 | @code{glPopMatrix} is executed between the execution of @code{glBegin} | |
17951 | and the corresponding execution of @code{glEnd}. | |
17952 | ||
bb894c9d | 17953 | @end deftypefun |
8925f36f | 17954 | |
bb894c9d AW |
17955 | @deftypefun void glPushName name |
17956 | @deftypefunx void glPopName | |
3c9b6116 AW |
17957 | Push and pop the name stack. |
17958 | ||
8925f36f AW |
17959 | @table @asis |
17960 | @item @var{name} | |
17961 | Specifies a name that will be pushed onto the name stack. | |
17962 | ||
17963 | @end table | |
17964 | ||
8925f36f | 17965 | The name stack is used during selection mode to allow sets of rendering |
f37e7e3d | 17966 | commands to be uniquely identified. It consists of an ordered set of |
8925f36f AW |
17967 | unsigned integers and is initially empty. |
17968 | ||
17969 | @code{glPushName} causes @var{name} to be pushed onto the name stack. | |
17970 | @code{glPopName} pops one name off the top of the stack. | |
17971 | ||
17972 | The maximum name stack depth is implementation-dependent; call | |
17973 | @code{GL_MAX_NAME_STACK_DEPTH} to find out the value for a particular | |
f37e7e3d DH |
17974 | implementation. It is an error to push a name onto a full stack or to |
17975 | pop a name off an empty stack. It is also an error to manipulate the | |
8925f36f | 17976 | name stack between the execution of @code{glBegin} and the corresponding |
f37e7e3d | 17977 | execution of @code{glEnd}. In any of these cases, the error flag is set |
8925f36f AW |
17978 | and no other change is made to GL state. |
17979 | ||
17980 | The name stack is always empty while the render mode is not | |
f37e7e3d | 17981 | @code{GL_SELECT}. Calls to @code{glPushName} or @code{glPopName} while |
8925f36f AW |
17982 | the render mode is not @code{GL_SELECT} are ignored. |
17983 | ||
8925f36f AW |
17984 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushName} is called |
17985 | while the name stack is full. | |
17986 | ||
17987 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopName} is called | |
17988 | while the name stack is empty. | |
17989 | ||
17990 | @code{GL_INVALID_OPERATION} is generated if @code{glPushName} or | |
17991 | @code{glPopName} is executed between a call to @code{glBegin} and the | |
17992 | corresponding call to @code{glEnd}. | |
17993 | ||
bb894c9d | 17994 | @end deftypefun |
8925f36f | 17995 | |
d172eed9 AW |
17996 | @deftypefun void glRasterPos2s x y |
17997 | @deftypefunx void glRasterPos2i x y | |
ca09631c | 17998 | @deftypefunx void glRasterPos2f x y |
d172eed9 AW |
17999 | @deftypefunx void glRasterPos2d x y |
18000 | @deftypefunx void glRasterPos3s x y z | |
bb894c9d | 18001 | @deftypefunx void glRasterPos3i x y z |
ca09631c | 18002 | @deftypefunx void glRasterPos3f x y z |
d172eed9 AW |
18003 | @deftypefunx void glRasterPos3d x y z |
18004 | @deftypefunx void glRasterPos4s x y z w | |
bb894c9d | 18005 | @deftypefunx void glRasterPos4i x y z w |
ca09631c | 18006 | @deftypefunx void glRasterPos4f x y z w |
d172eed9 AW |
18007 | @deftypefunx void glRasterPos4d x y z w |
18008 | @deftypefunx void glRasterPos2sv v | |
18009 | @deftypefunx void glRasterPos2iv v | |
18010 | @deftypefunx void glRasterPos2fv v | |
18011 | @deftypefunx void glRasterPos2dv v | |
18012 | @deftypefunx void glRasterPos3sv v | |
18013 | @deftypefunx void glRasterPos3iv v | |
18014 | @deftypefunx void glRasterPos3fv v | |
18015 | @deftypefunx void glRasterPos3dv v | |
18016 | @deftypefunx void glRasterPos4sv v | |
18017 | @deftypefunx void glRasterPos4iv v | |
18018 | @deftypefunx void glRasterPos4fv v | |
18019 | @deftypefunx void glRasterPos4dv v | |
3c9b6116 AW |
18020 | Specify the raster position for pixel operations. |
18021 | ||
8925f36f AW |
18022 | @table @asis |
18023 | @item @var{x} | |
18024 | @itemx @var{y} | |
18025 | @itemx @var{z} | |
18026 | @itemx @var{w} | |
3c9b6116 AW |
18027 | Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}} |
18028 | object coordinates (if present) for the raster position. | |
8925f36f AW |
18029 | |
18030 | @end table | |
18031 | ||
f37e7e3d | 18032 | The GL maintains a 3D position in window coordinates. This position, |
8925f36f | 18033 | called the raster position, is used to position pixel and bitmap write |
f37e7e3d | 18034 | operations. It is maintained with subpixel accuracy. See |
8925f36f AW |
18035 | @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}. |
18036 | ||
18037 | The current raster position consists of three window coordinates | |
3c9b6116 AW |
18038 | (@r{@var{x}}, @r{@var{y}}, @r{@var{z}}), a clip coordinate value |
18039 | (@r{@var{w}}), an eye coordinate distance, a valid bit, and associated | |
f37e7e3d DH |
18040 | color data and texture coordinates. The @r{@var{w}} coordinate is a clip |
18041 | coordinate, because @r{@var{w}} is not projected to window coordinates. | |
18042 | @code{glRasterPos4} specifies object coordinates @r{@var{x}}, | |
18043 | @r{@var{y}}, @r{@var{z}}, and @r{@var{w}} explicitly. | |
3c9b6116 AW |
18044 | @code{glRasterPos3} specifies object coordinate @r{@var{x}}, |
18045 | @r{@var{y}}, and @r{@var{z}} explicitly, while @r{@var{w}} is implicitly | |
f37e7e3d | 18046 | set to 1. @code{glRasterPos2} uses the argument values for @r{@var{x}} |
3c9b6116 AW |
18047 | and @r{@var{y}} while implicitly setting @r{@var{z}} and @r{@var{w}} to |
18048 | 0 and 1. | |
8925f36f AW |
18049 | |
18050 | The object coordinates presented by @code{glRasterPos} are treated just | |
18051 | like those of a @code{glVertex} command: They are transformed by the | |
18052 | current modelview and projection matrices and passed to the clipping | |
f37e7e3d | 18053 | stage. If the vertex is not culled, then it is projected and scaled to |
8925f36f | 18054 | window coordinates, which become the new current raster position, and |
f37e7e3d | 18055 | the @code{GL_CURRENT_RASTER_POSITION_VALID} flag is set. If the vertex |
8925f36f AW |
18056 | @var{is} culled, then the valid bit is cleared and the current raster |
18057 | position and associated color and texture coordinates are undefined. | |
18058 | ||
18059 | The current raster position also includes some associated color data and | |
f37e7e3d | 18060 | texture coordinates. If lighting is enabled, then |
8925f36f AW |
18061 | @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or |
18062 | @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color | |
18063 | produced by the lighting calculation (see @code{glLight}, | |
f37e7e3d | 18064 | @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled, |
8925f36f AW |
18065 | current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or |
18066 | color index (in color index mode, state variable | |
18067 | @code{GL_CURRENT_INDEX}) is used to update the current raster color. | |
18068 | @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise | |
18069 | updated. | |
18070 | ||
18071 | Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a | |
18072 | function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture | |
18073 | matrix and the texture generation functions (see @code{glTexGen}). | |
18074 | Finally, the distance from the origin of the eye coordinate system to | |
18075 | the vertex as transformed by only the modelview matrix replaces | |
18076 | @code{GL_CURRENT_RASTER_DISTANCE}. | |
18077 | ||
18078 | Initially, the current raster position is (0, 0, 0, 1), the current | |
18079 | raster distance is 0, the valid bit is set, the associated RGBA color is | |
18080 | (1, 1, 1, 1), the associated color index is 1, and the associated | |
f37e7e3d | 18081 | texture coordinates are (0, 0, 0, 1). In RGBA mode, |
8925f36f AW |
18082 | @code{GL_CURRENT_RASTER_INDEX} is always 1; in color index mode, the |
18083 | current raster RGBA color always maintains its initial value. | |
18084 | ||
8925f36f AW |
18085 | @code{GL_INVALID_OPERATION} is generated if @code{glRasterPos} is |
18086 | executed between the execution of @code{glBegin} and the corresponding | |
18087 | execution of @code{glEnd}. | |
18088 | ||
bb894c9d | 18089 | @end deftypefun |
8925f36f | 18090 | |
bb894c9d | 18091 | @deftypefun void glReadBuffer mode |
3c9b6116 AW |
18092 | Select a color buffer source for pixels. |
18093 | ||
8925f36f AW |
18094 | @table @asis |
18095 | @item @var{mode} | |
f37e7e3d | 18096 | Specifies a color buffer. Accepted values are @code{GL_FRONT_LEFT}, |
8925f36f AW |
18097 | @code{GL_FRONT_RIGHT}, @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT}, |
18098 | @code{GL_FRONT}, @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT}, and | |
18099 | @code{GL_AUX}@var{i}, where @var{i} is between 0 and the value of | |
18100 | @code{GL_AUX_BUFFERS} minus 1. | |
18101 | ||
18102 | @end table | |
18103 | ||
8925f36f AW |
18104 | @code{glReadBuffer} specifies a color buffer as the source for |
18105 | subsequent @code{glReadPixels}, @code{glCopyTexImage1D}, | |
18106 | @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D}, | |
18107 | @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D}, and | |
f37e7e3d DH |
18108 | @code{glCopyPixels} commands. @var{mode} accepts one of twelve or more |
18109 | predefined values. (@code{GL_AUX0} through @code{GL_AUX3} are always | |
8925f36f AW |
18110 | defined.) In a fully configured system, @code{GL_FRONT}, @code{GL_LEFT}, |
18111 | and @code{GL_FRONT_LEFT} all name the front left buffer, | |
18112 | @code{GL_FRONT_RIGHT} and @code{GL_RIGHT} name the front right buffer, | |
18113 | and @code{GL_BACK_LEFT} and @code{GL_BACK} name the back left buffer. | |
18114 | ||
18115 | Nonstereo double-buffered configurations have only a front left and a | |
f37e7e3d DH |
18116 | back left buffer. Single-buffered configurations have a front left and a |
18117 | front right buffer if stereo, and only a front left buffer if nonstereo. | |
18118 | It is an error to specify a nonexistent buffer to @code{glReadBuffer}. | |
8925f36f AW |
18119 | |
18120 | @var{mode} is initially @code{GL_FRONT} in single-buffered | |
18121 | configurations and @code{GL_BACK} in double-buffered configurations. | |
18122 | ||
8925f36f AW |
18123 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the |
18124 | twelve (or more) accepted values. | |
18125 | ||
18126 | @code{GL_INVALID_OPERATION} is generated if @var{mode} specifies a | |
18127 | buffer that does not exist. | |
18128 | ||
18129 | @code{GL_INVALID_OPERATION} is generated if @code{glReadBuffer} is | |
18130 | executed between the execution of @code{glBegin} and the corresponding | |
18131 | execution of @code{glEnd}. | |
18132 | ||
bb894c9d | 18133 | @end deftypefun |
8925f36f | 18134 | |
bb894c9d | 18135 | @deftypefun void glReadPixels x y width height format type data |
3c9b6116 AW |
18136 | Read a block of pixels from the frame buffer. |
18137 | ||
8925f36f AW |
18138 | @table @asis |
18139 | @item @var{x} | |
18140 | @itemx @var{y} | |
18141 | Specify the window coordinates of the first pixel that is read from the | |
f37e7e3d | 18142 | frame buffer. This location is the lower left corner of a rectangular |
8925f36f AW |
18143 | block of pixels. |
18144 | ||
18145 | @item @var{width} | |
18146 | @itemx @var{height} | |
f37e7e3d | 18147 | Specify the dimensions of the pixel rectangle. @var{width} and |
8925f36f AW |
18148 | @var{height} of one correspond to a single pixel. |
18149 | ||
18150 | @item @var{format} | |
f37e7e3d | 18151 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
18152 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, |
18153 | @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN}, | |
18154 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
18155 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
18156 | @code{GL_LUMINANCE_ALPHA}. | |
18157 | ||
18158 | @item @var{type} | |
f37e7e3d | 18159 | Specifies the data type of the pixel data. Must be one of |
8925f36f AW |
18160 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
18161 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
18162 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
18163 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
18164 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
18165 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
18166 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
18167 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
18168 | or @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
18169 | ||
18170 | @item @var{data} | |
18171 | Returns the pixel data. | |
18172 | ||
18173 | @end table | |
18174 | ||
8925f36f AW |
18175 | @code{glReadPixels} returns pixel data from the frame buffer, starting |
18176 | with the pixel whose lower left corner is at location (@var{x}, | |
f37e7e3d | 18177 | @var{y}), into client memory starting at location @var{data}. Several |
8925f36f | 18178 | parameters control the processing of the pixel data before it is placed |
f37e7e3d DH |
18179 | into client memory. These parameters are set with three commands: |
18180 | @code{glPixelStore}, @code{glPixelTransfer}, and @code{glPixelMap}. This | |
8925f36f AW |
18181 | reference page describes the effects on @code{glReadPixels} of most, but |
18182 | not all of the parameters specified by these three commands. | |
18183 | ||
18184 | If a non-zero named buffer object is bound to the | |
18185 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
18186 | block of pixels is requested, @var{data} is treated as a byte offset | |
18187 | into the buffer object's data store rather than a pointer to client | |
18188 | memory. | |
18189 | ||
18190 | When the @code{ARB_imaging} extension is supported, the pixel data may | |
18191 | be processed by additional operations including color table lookup, | |
18192 | color matrix transformations, convolutions, histograms, and minimum and | |
18193 | maximum pixel value computations. | |
18194 | ||
18195 | @code{glReadPixels} returns values from each pixel with lower left | |
3c9b6116 | 18196 | corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for |
f37e7e3d DH |
18197 | @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel |
18198 | is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels | |
3c9b6116 AW |
18199 | are returned in row order from the lowest to the highest row, left to |
18200 | right in each row. | |
8925f36f AW |
18201 | |
18202 | @var{format} specifies the format for the returned pixel values; | |
18203 | accepted values are: | |
18204 | ||
18205 | @table @asis | |
18206 | @item @code{GL_COLOR_INDEX} | |
18207 | Color indices are read from the color buffer selected by | |
f37e7e3d | 18208 | @code{glReadBuffer}. Each index is converted to fixed point, shifted |
8925f36f | 18209 | left or right depending on the value and sign of @code{GL_INDEX_SHIFT}, |
f37e7e3d | 18210 | and added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_COLOR} is |
8925f36f AW |
18211 | @code{GL_TRUE}, indices are replaced by their mappings in the table |
18212 | @code{GL_PIXEL_MAP_I_TO_I}. | |
18213 | ||
18214 | @item @code{GL_STENCIL_INDEX} | |
f37e7e3d DH |
18215 | Stencil values are read from the stencil buffer. Each index is converted |
18216 | to fixed point, shifted left or right depending on the value and sign of | |
18217 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET}. If | |
18218 | @code{GL_MAP_STENCIL} is @code{GL_TRUE}, indices are replaced by their | |
18219 | mappings in the table @code{GL_PIXEL_MAP_S_TO_S}. | |
8925f36f AW |
18220 | |
18221 | @item @code{GL_DEPTH_COMPONENT} | |
f37e7e3d DH |
18222 | Depth values are read from the depth buffer. Each component is converted |
18223 | to floating point such that the minimum depth value maps to 0 and the | |
18224 | maximum value maps to 1. Each component is then multiplied by | |
8925f36f | 18225 | @code{GL_DEPTH_SCALE}, added to @code{GL_DEPTH_BIAS}, and finally |
3c9b6116 | 18226 | clamped to the range @r{[0,1]}. |
8925f36f AW |
18227 | |
18228 | @item @code{GL_RED} | |
18229 | @item @code{GL_GREEN} | |
18230 | @item @code{GL_BLUE} | |
18231 | @item @code{GL_ALPHA} | |
18232 | @item @code{GL_RGB} | |
18233 | @item @code{GL_BGR} | |
18234 | @item @code{GL_RGBA} | |
18235 | @item @code{GL_BGRA} | |
18236 | @item @code{GL_LUMINANCE} | |
18237 | @item @code{GL_LUMINANCE_ALPHA} | |
18238 | Processing differs depending on whether color buffers store color | |
f37e7e3d DH |
18239 | indices or RGBA color components. If color indices are stored, they are |
18240 | read from the color buffer selected by @code{glReadBuffer}. Each index | |
8925f36f AW |
18241 | is converted to fixed point, shifted left or right depending on the |
18242 | value and sign of @code{GL_INDEX_SHIFT}, and added to | |
f37e7e3d | 18243 | @code{GL_INDEX_OFFSET}. Indices are then replaced by the red, green, |
8925f36f AW |
18244 | blue, and alpha values obtained by indexing the tables |
18245 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
f37e7e3d | 18246 | @code{GL_PIXEL_MAP_I_TO_B}, and @code{GL_PIXEL_MAP_I_TO_A}. Each table |
3c9b6116 | 18247 | must be of size @r{2^@var{n}}, but @r{@var{n}} may be different for |
f37e7e3d | 18248 | different tables. Before an index is used to look up a value in a table |
3c9b6116 | 18249 | of size @r{2^@var{n}}, it must be masked against @r{2^@var{n}-1}. |
8925f36f AW |
18250 | |
18251 | If RGBA color components are stored in the color buffers, they are read | |
f37e7e3d | 18252 | from the color buffer selected by @code{glReadBuffer}. Each color |
8925f36f | 18253 | component is converted to floating point such that zero intensity maps |
f37e7e3d DH |
18254 | to 0.0 and full intensity maps to 1.0. Each component is then multiplied |
18255 | by @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is | |
18256 | RED, GREEN, BLUE, or ALPHA. Finally, if @code{GL_MAP_COLOR} is | |
18257 | @code{GL_TRUE}, each component is clamped to the range @r{[0,1]}, scaled | |
18258 | to the size of its corresponding table, and is then replaced by its | |
18259 | mapping in the table @code{GL_PIXEL_MAP_c_TO_c}, where @var{c} is R, G, | |
18260 | B, or A. | |
18261 | ||
18262 | Unneeded data is then discarded. For example, @code{GL_RED} discards the | |
18263 | green, blue, and alpha components, while @code{GL_RGB} discards only the | |
18264 | alpha component. @code{GL_LUMINANCE} computes a single-component value | |
18265 | as the sum of the red, green, and blue components, and | |
8925f36f | 18266 | @code{GL_LUMINANCE_ALPHA} does the same, while keeping alpha as a second |
f37e7e3d | 18267 | value. The final values are clamped to the range @r{[0,1]}. |
8925f36f AW |
18268 | |
18269 | @end table | |
18270 | ||
18271 | The shift, scale, bias, and lookup factors just described are all | |
f37e7e3d | 18272 | specified by @code{glPixelTransfer}. The lookup table contents |
8925f36f AW |
18273 | themselves are specified by @code{glPixelMap}. |
18274 | ||
18275 | Finally, the indices or components are converted to the proper format, | |
f37e7e3d | 18276 | as specified by @var{type}. If @var{format} is @code{GL_COLOR_INDEX} or |
8925f36f | 18277 | @code{GL_STENCIL_INDEX} and @var{type} is not @code{GL_FLOAT}, each |
f37e7e3d | 18278 | index is masked with the mask value given in the following table. If |
8925f36f AW |
18279 | @var{type} is @code{GL_FLOAT}, then each integer index is converted to |
18280 | single-precision floating-point format. | |
18281 | ||
18282 | If @var{format} is @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, | |
18283 | @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, | |
18284 | @code{GL_BGRA}, @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA} and | |
18285 | @var{type} is not @code{GL_FLOAT}, each component is multiplied by the | |
f37e7e3d | 18286 | multiplier shown in the following table. If type is @code{GL_FLOAT}, |
8925f36f AW |
18287 | then each component is passed as is (or converted to the client's |
18288 | single-precision floating-point format if it is different from the one | |
18289 | used by the GL). | |
18290 | ||
18291 | ||
18292 | ||
18293 | @table @asis | |
18294 | @item @var{type} | |
18295 | @strong{Index Mask}, @strong{Component Conversion} | |
18296 | ||
18297 | @item @code{GL_UNSIGNED_BYTE} | |
3c9b6116 | 18298 | @r{2^8-1}, @r{(2^8-1,)@var{c}} |
8925f36f AW |
18299 | |
18300 | @item @code{GL_BYTE} | |
3c9b6116 | 18301 | @r{2^7-1}, @r{(2^8-1,)@var{c}-1,/2} |
8925f36f AW |
18302 | |
18303 | @item @code{GL_BITMAP} | |
3c9b6116 | 18304 | @r{1}, @r{1} |
8925f36f AW |
18305 | |
18306 | @item @code{GL_UNSIGNED_SHORT} | |
3c9b6116 | 18307 | @r{2^16-1}, @r{(2^16-1,)@var{c}} |
8925f36f AW |
18308 | |
18309 | @item @code{GL_SHORT} | |
3c9b6116 | 18310 | @r{2^15-1}, @r{(2^16-1,)@var{c}-1,/2} |
8925f36f AW |
18311 | |
18312 | @item @code{GL_UNSIGNED_INT} | |
3c9b6116 | 18313 | @r{2^32-1}, @r{(2^32-1,)@var{c}} |
8925f36f AW |
18314 | |
18315 | @item @code{GL_INT} | |
3c9b6116 | 18316 | @r{2^31-1}, @r{(2^32-1,)@var{c}-1,/2} |
8925f36f AW |
18317 | |
18318 | @item @code{GL_FLOAT} | |
3c9b6116 | 18319 | none , @r{@var{c}} |
8925f36f AW |
18320 | |
18321 | @end table | |
18322 | ||
f37e7e3d | 18323 | Return values are placed in memory as follows. If @var{format} is |
8925f36f AW |
18324 | @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, |
18325 | @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN}, | |
18326 | @code{GL_BLUE}, @code{GL_ALPHA}, or @code{GL_LUMINANCE}, a single value | |
3c9b6116 AW |
18327 | is returned and the data for the @r{@var{i}}th pixel in the |
18328 | @r{@var{j}}th row is placed in location | |
f37e7e3d | 18329 | @r{(@var{j},)@var{width}+@var{i}}. @code{GL_RGB} and @code{GL_BGR} |
8925f36f AW |
18330 | return three values, @code{GL_RGBA} and @code{GL_BGRA} return four |
18331 | values, and @code{GL_LUMINANCE_ALPHA} returns two values for each pixel, | |
18332 | with all values corresponding to a single pixel occupying contiguous | |
f37e7e3d DH |
18333 | space in @var{data}. Storage parameters set by @code{glPixelStore}, such |
18334 | as @code{GL_PACK_LSB_FIRST} and @code{GL_PACK_SWAP_BYTES}, affect the | |
18335 | way that data is written into memory. See @code{glPixelStore} for a | |
8925f36f AW |
18336 | description. |
18337 | ||
8925f36f AW |
18338 | @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not |
18339 | an accepted value. | |
18340 | ||
18341 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
18342 | and @var{format} is not @code{GL_COLOR_INDEX} or | |
18343 | @code{GL_STENCIL_INDEX}. | |
18344 | ||
18345 | @code{GL_INVALID_VALUE} is generated if either @var{width} or | |
18346 | @var{height} is negative. | |
18347 | ||
18348 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
18349 | @code{GL_COLOR_INDEX} and the color buffers store RGBA color components. | |
18350 | ||
18351 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
18352 | @code{GL_STENCIL_INDEX} and there is no stencil buffer. | |
18353 | ||
18354 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
18355 | @code{GL_DEPTH_COMPONENT} and there is no depth buffer. | |
18356 | ||
18357 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
18358 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
18359 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
18360 | and @var{format} is not @code{GL_RGB}. | |
18361 | ||
18362 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
18363 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
18364 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
18365 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
18366 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
18367 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
18368 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
18369 | ||
18370 | The formats @code{GL_BGR}, and @code{GL_BGRA} and types | |
18371 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
18372 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
18373 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
18374 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
18375 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
18376 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
18377 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} are available only if the GL | |
18378 | version is 1.2 or greater. | |
18379 | ||
18380 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
18381 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
18382 | object's data store is currently mapped. | |
18383 | ||
18384 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
18385 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
18386 | would be packed to the buffer object such that the memory writes | |
18387 | required would exceed the data store size. | |
18388 | ||
18389 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
18390 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{data} | |
18391 | is not evenly divisible into the number of bytes needed to store in | |
18392 | memory a datum indicated by @var{type}. | |
18393 | ||
18394 | @code{GL_INVALID_OPERATION} is generated if @code{glReadPixels} is | |
18395 | executed between the execution of @code{glBegin} and the corresponding | |
18396 | execution of @code{glEnd}. | |
18397 | ||
bb894c9d | 18398 | @end deftypefun |
8925f36f | 18399 | |
d172eed9 AW |
18400 | @deftypefun void glRectd x1 y1 x2 y2 |
18401 | @deftypefunx void glRectf x1 y1 x2 y2 | |
bb894c9d | 18402 | @deftypefunx void glRecti x1 y1 x2 y2 |
d172eed9 AW |
18403 | @deftypefunx void glRects x1 y1 x2 y2 |
18404 | @deftypefunx void glRectdv v1 v2 | |
18405 | @deftypefunx void glRectfv v1 v2 | |
18406 | @deftypefunx void glRectiv v1 v2 | |
18407 | @deftypefunx void glRectsv v1 v2 | |
3c9b6116 AW |
18408 | Draw a rectangle. |
18409 | ||
8925f36f AW |
18410 | @table @asis |
18411 | @item @var{x1} | |
18412 | @itemx @var{y1} | |
18413 | Specify one vertex of a rectangle. | |
18414 | ||
18415 | @item @var{x2} | |
18416 | @itemx @var{y2} | |
18417 | Specify the opposite vertex of the rectangle. | |
18418 | ||
18419 | @end table | |
18420 | ||
8925f36f | 18421 | @code{glRect} supports efficient specification of rectangles as two |
f37e7e3d | 18422 | corner points. Each rectangle command takes four arguments, organized |
3c9b6116 AW |
18423 | either as two consecutive pairs of @r{(@var{x},@var{y})} coordinates or |
18424 | as two pointers to arrays, each containing an @r{(@var{x},@var{y})} | |
f37e7e3d | 18425 | pair. The resulting rectangle is defined in the @r{@var{z}=0} plane. |
8925f36f AW |
18426 | |
18427 | @code{glRect}(@var{x1}, @var{y1}, @var{x2}, @var{y2}) is exactly | |
18428 | equivalent to the following sequence: Note that if the second vertex is | |
18429 | above and to the right of the first vertex, the rectangle is constructed | |
18430 | with a counterclockwise winding. | |
18431 | ||
18432 | @example | |
18433 | ||
18434 | glBegin(@code{GL_POLYGON}); | |
18435 | glVertex2(@var{x1}, @var{y1}); | |
18436 | glVertex2(@var{x2}, @var{y1}); | |
18437 | glVertex2(@var{x2}, @var{y2}); | |
18438 | glVertex2(@var{x1}, @var{y2}); | |
18439 | glEnd(); | |
18440 | @end example | |
18441 | ||
8925f36f AW |
18442 | @code{GL_INVALID_OPERATION} is generated if @code{glRect} is executed |
18443 | between the execution of @code{glBegin} and the corresponding execution | |
18444 | of @code{glEnd}. | |
18445 | ||
bb894c9d | 18446 | @end deftypefun |
8925f36f | 18447 | |
bb894c9d | 18448 | @deftypefun GLint glRenderMode mode |
3c9b6116 AW |
18449 | Set rasterization mode. |
18450 | ||
8925f36f AW |
18451 | @table @asis |
18452 | @item @var{mode} | |
f37e7e3d DH |
18453 | Specifies the rasterization mode. Three values are accepted: |
18454 | @code{GL_RENDER}, @code{GL_SELECT}, and @code{GL_FEEDBACK}. The initial | |
8925f36f AW |
18455 | value is @code{GL_RENDER}. |
18456 | ||
18457 | @end table | |
18458 | ||
f37e7e3d | 18459 | @code{glRenderMode} sets the rasterization mode. It takes one argument, |
8925f36f AW |
18460 | @var{mode}, which can assume one of three predefined values: |
18461 | ||
18462 | @table @asis | |
18463 | @item @code{GL_RENDER} | |
f37e7e3d DH |
18464 | Render mode. Primitives are rasterized, producing pixel fragments, which |
18465 | are written into the frame buffer. This is the normal mode and also the | |
18466 | default mode. | |
8925f36f AW |
18467 | |
18468 | @item @code{GL_SELECT} | |
f37e7e3d DH |
18469 | Selection mode. No pixel fragments are produced, and no change to the |
18470 | frame buffer contents is made. Instead, a record of the names of | |
8925f36f AW |
18471 | primitives that would have been drawn if the render mode had been |
18472 | @code{GL_RENDER} is returned in a select buffer, which must be created | |
18473 | (see @code{glSelectBuffer}) before selection mode is entered. | |
18474 | ||
18475 | @item @code{GL_FEEDBACK} | |
f37e7e3d DH |
18476 | Feedback mode. No pixel fragments are produced, and no change to the |
18477 | frame buffer contents is made. Instead, the coordinates and attributes | |
8925f36f AW |
18478 | of vertices that would have been drawn if the render mode had been |
18479 | @code{GL_RENDER} is returned in a feedback buffer, which must be created | |
18480 | (see @code{glFeedbackBuffer}) before feedback mode is entered. | |
18481 | ||
18482 | @end table | |
18483 | ||
18484 | The return value of @code{glRenderMode} is determined by the render mode | |
18485 | at the time @code{glRenderMode} is called, rather than by @var{mode}. | |
18486 | The values returned for the three render modes are as follows: | |
18487 | ||
18488 | @table @asis | |
18489 | @item @code{GL_RENDER} | |
18490 | 0. | |
18491 | ||
18492 | @item @code{GL_SELECT} | |
18493 | The number of hit records transferred to the select buffer. | |
18494 | ||
18495 | @item @code{GL_FEEDBACK} | |
18496 | The number of values (not vertices) transferred to the feedback buffer. | |
18497 | ||
18498 | @end table | |
18499 | ||
18500 | See the @code{glSelectBuffer} and @code{glFeedbackBuffer} reference | |
18501 | pages for more details concerning selection and feedback operation. | |
18502 | ||
8925f36f AW |
18503 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the |
18504 | three accepted values. | |
18505 | ||
18506 | @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is | |
18507 | called while the render mode is @code{GL_SELECT}, or if | |
18508 | @code{glRenderMode} is called with argument @code{GL_SELECT} before | |
18509 | @code{glSelectBuffer} is called at least once. | |
18510 | ||
18511 | @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is | |
18512 | called while the render mode is @code{GL_FEEDBACK}, or if | |
18513 | @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before | |
18514 | @code{glFeedbackBuffer} is called at least once. | |
18515 | ||
18516 | @code{GL_INVALID_OPERATION} is generated if @code{glRenderMode} is | |
18517 | executed between the execution of @code{glBegin} and the corresponding | |
18518 | execution of @code{glEnd}. | |
18519 | ||
bb894c9d | 18520 | @end deftypefun |
8925f36f | 18521 | |
bb894c9d | 18522 | @deftypefun void glResetHistogram target |
3c9b6116 AW |
18523 | Reset histogram table entries to zero. |
18524 | ||
8925f36f AW |
18525 | @table @asis |
18526 | @item @var{target} | |
18527 | Must be @code{GL_HISTOGRAM}. | |
18528 | ||
18529 | @end table | |
18530 | ||
8925f36f AW |
18531 | @code{glResetHistogram} resets all the elements of the current histogram |
18532 | table to zero. | |
18533 | ||
8925f36f AW |
18534 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
18535 | @code{GL_HISTOGRAM}. | |
18536 | ||
18537 | @code{GL_INVALID_OPERATION} is generated if @code{glResetHistogram} is | |
18538 | executed between the execution of @code{glBegin} and the corresponding | |
18539 | execution of @code{glEnd}. | |
18540 | ||
bb894c9d | 18541 | @end deftypefun |
8925f36f | 18542 | |
bb894c9d | 18543 | @deftypefun void glResetMinmax target |
3c9b6116 AW |
18544 | Reset minmax table entries to initial values. |
18545 | ||
8925f36f AW |
18546 | @table @asis |
18547 | @item @var{target} | |
18548 | Must be @code{GL_MINMAX}. | |
18549 | ||
18550 | @end table | |
18551 | ||
8925f36f AW |
18552 | @code{glResetMinmax} resets the elements of the current minmax table to |
18553 | their initial values: the ``maximum'' element receives the minimum | |
18554 | possible component values, and the ``minimum'' element receives the | |
18555 | maximum possible component values. | |
18556 | ||
8925f36f AW |
18557 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
18558 | @code{GL_MINMAX}. | |
18559 | ||
18560 | @code{GL_INVALID_OPERATION} is generated if @code{glResetMinmax} is | |
18561 | executed between the execution of @code{glBegin} and the corresponding | |
18562 | execution of @code{glEnd}. | |
18563 | ||
bb894c9d | 18564 | @end deftypefun |
8925f36f | 18565 | |
d172eed9 AW |
18566 | @deftypefun void glRotated angle x y z |
18567 | @deftypefunx void glRotatef angle x y z | |
3c9b6116 AW |
18568 | Multiply the current matrix by a rotation matrix. |
18569 | ||
8925f36f AW |
18570 | @table @asis |
18571 | @item @var{angle} | |
18572 | Specifies the angle of rotation, in degrees. | |
18573 | ||
18574 | @item @var{x} | |
18575 | @itemx @var{y} | |
18576 | @itemx @var{z} | |
18577 | Specify the @var{x}, @var{y}, and @var{z} coordinates of a vector, | |
18578 | respectively. | |
18579 | ||
18580 | @end table | |
18581 | ||
8925f36f | 18582 | @code{glRotate} produces a rotation of @var{angle} degrees around the |
f37e7e3d | 18583 | vector @r{(@var{x},@var{y}@var{z})}. The current matrix (see |
8925f36f AW |
18584 | @code{glMatrixMode}) is multiplied by a rotation matrix with the product |
18585 | replacing the current matrix, as if @code{glMultMatrix} were called with | |
18586 | the following matrix as its argument: | |
18587 | ||
3c9b6116 | 18588 | @r{((@var{x}^2(1-@var{c},)+@var{c} |
8925f36f AW |
18589 | @var{x}@var{y}(1-@var{c},)-@var{z}@var{s} |
18590 | @var{x}@var{z}(1-@var{c},)+@var{y}@var{s} 0), | |
18591 | (@var{y}@var{x}(1-@var{c},)+@var{z}@var{s} | |
18592 | @var{y}^2(1-@var{c},)+@var{c} | |
18593 | @var{y}@var{z}(1-@var{c},)-@var{x}@var{s} 0), | |
18594 | (@var{x}@var{z}(1-@var{c},)-@var{y}@var{s} | |
18595 | @var{y}@var{z}(1-@var{c},)+@var{x}@var{s} | |
18596 | @var{z}^2(1-@var{c},)+@var{c} 0), (0 0 0 1),)} | |
18597 | ||
18598 | ||
18599 | ||
3c9b6116 AW |
18600 | Where @r{@var{c}=@var{cos}(@var{angle},)}, |
18601 | @r{@var{s}=@var{sin}(@var{angle},)}, and | |
18602 | @r{∥(@var{x},@var{y}@var{z}),∥=1} (if not, the GL will normalize this | |
8925f36f AW |
18603 | vector). |
18604 | ||
18605 | ||
18606 | ||
18607 | ||
18608 | ||
18609 | If the matrix mode is either @code{GL_MODELVIEW} or | |
18610 | @code{GL_PROJECTION}, all objects drawn after @code{glRotate} is called | |
f37e7e3d | 18611 | are rotated. Use @code{glPushMatrix} and @code{glPopMatrix} to save and |
8925f36f AW |
18612 | restore the unrotated coordinate system. |
18613 | ||
8925f36f AW |
18614 | @code{GL_INVALID_OPERATION} is generated if @code{glRotate} is executed |
18615 | between the execution of @code{glBegin} and the corresponding execution | |
18616 | of @code{glEnd}. | |
18617 | ||
bb894c9d | 18618 | @end deftypefun |
8925f36f | 18619 | |
bb894c9d | 18620 | @deftypefun void glSampleCoverage value invert |
3c9b6116 AW |
18621 | Specify multisample coverage parameters. |
18622 | ||
8925f36f AW |
18623 | @table @asis |
18624 | @item @var{value} | |
f37e7e3d DH |
18625 | Specify a single floating-point sample coverage value. The value is |
18626 | clamped to the range @r{[0,1]}. The initial value is 1.0. | |
8925f36f AW |
18627 | |
18628 | @item @var{invert} | |
18629 | Specify a single boolean value representing if the coverage masks should | |
f37e7e3d | 18630 | be inverted. @code{GL_TRUE} and @code{GL_FALSE} are accepted. The |
8925f36f AW |
18631 | initial value is @code{GL_FALSE}. |
18632 | ||
18633 | @end table | |
18634 | ||
8925f36f AW |
18635 | Multisampling samples a pixel multiple times at various |
18636 | implementation-dependent subpixel locations to generate antialiasing | |
f37e7e3d | 18637 | effects. Multisampling transparently antialiases points, lines, |
8925f36f AW |
18638 | polygons, bitmaps, and images if it is enabled. |
18639 | ||
18640 | @var{value} is used in constructing a temporary mask used in determining | |
f37e7e3d | 18641 | which samples will be used in resolving the final fragment color. This |
8925f36f | 18642 | mask is bitwise-anded with the coverage mask generated from the |
f37e7e3d | 18643 | multisampling computation. If the @var{invert} flag is set, the |
8925f36f AW |
18644 | temporary mask is inverted (all bits flipped) and then the bitwise-and |
18645 | is computed. | |
18646 | ||
18647 | If an implementation does not have any multisample buffers available, or | |
18648 | multisampling is disabled, rasterization occurs with only a single | |
18649 | sample computing a pixel's final RGB color. | |
18650 | ||
18651 | Provided an implementation supports multisample buffers, and | |
18652 | multisampling is enabled, then a pixel's final color is generated by | |
f37e7e3d | 18653 | combining several samples per pixel. Each sample contains color, depth, |
8925f36f AW |
18654 | and stencil information, allowing those operations to be performed on |
18655 | each sample. | |
18656 | ||
8925f36f AW |
18657 | @code{GL_INVALID_OPERATION} is generated if @code{glSampleCoverage} is |
18658 | executed between the execution of @code{glBegin} and the corresponding | |
18659 | execution of @code{glEnd}. | |
18660 | ||
bb894c9d | 18661 | @end deftypefun |
8925f36f | 18662 | |
d172eed9 AW |
18663 | @deftypefun void glScaled x y z |
18664 | @deftypefunx void glScalef x y z | |
3c9b6116 AW |
18665 | Multiply the current matrix by a general scaling matrix. |
18666 | ||
8925f36f AW |
18667 | @table @asis |
18668 | @item @var{x} | |
18669 | @itemx @var{y} | |
18670 | @itemx @var{z} | |
18671 | Specify scale factors along the @var{x}, @var{y}, and @var{z} axes, | |
18672 | respectively. | |
18673 | ||
18674 | @end table | |
18675 | ||
8925f36f | 18676 | @code{glScale} produces a nonuniform scaling along the @var{x}, @var{y}, |
f37e7e3d DH |
18677 | and @var{z} axes. The three parameters indicate the desired scale factor |
18678 | along each of the three axes. | |
8925f36f AW |
18679 | |
18680 | The current matrix (see @code{glMatrixMode}) is multiplied by this scale | |
18681 | matrix, and the product replaces the current matrix as if | |
18682 | @code{glMultMatrix} were called with the following matrix as its | |
18683 | argument: | |
18684 | ||
3c9b6116 | 18685 | @r{((@var{x} 0 0 0), (0 @var{y} 0 0), (0 0 @var{z} 0), (0 0 0 1),)} |
8925f36f AW |
18686 | |
18687 | If the matrix mode is either @code{GL_MODELVIEW} or | |
18688 | @code{GL_PROJECTION}, all objects drawn after @code{glScale} is called | |
18689 | are scaled. | |
18690 | ||
18691 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
18692 | unscaled coordinate system. | |
18693 | ||
8925f36f AW |
18694 | @code{GL_INVALID_OPERATION} is generated if @code{glScale} is executed |
18695 | between the execution of @code{glBegin} and the corresponding execution | |
18696 | of @code{glEnd}. | |
18697 | ||
bb894c9d | 18698 | @end deftypefun |
8925f36f | 18699 | |
bb894c9d | 18700 | @deftypefun void glScissor x y width height |
3c9b6116 AW |
18701 | Define the scissor box. |
18702 | ||
8925f36f AW |
18703 | @table @asis |
18704 | @item @var{x} | |
18705 | @itemx @var{y} | |
f37e7e3d | 18706 | Specify the lower left corner of the scissor box. Initially (0, 0). |
8925f36f AW |
18707 | |
18708 | @item @var{width} | |
18709 | @itemx @var{height} | |
f37e7e3d | 18710 | Specify the width and height of the scissor box. When a GL context is |
8925f36f AW |
18711 | first attached to a window, @var{width} and @var{height} are set to the |
18712 | dimensions of that window. | |
18713 | ||
18714 | @end table | |
18715 | ||
8925f36f | 18716 | @code{glScissor} defines a rectangle, called the scissor box, in window |
f37e7e3d DH |
18717 | coordinates. The first two arguments, @var{x} and @var{y}, specify the |
18718 | lower left corner of the box. @var{width} and @var{height} specify the | |
8925f36f AW |
18719 | width and height of the box. |
18720 | ||
18721 | To enable and disable the scissor test, call @code{glEnable} and | |
f37e7e3d DH |
18722 | @code{glDisable} with argument @code{GL_SCISSOR_TEST}. The test is |
18723 | initially disabled. While the test is enabled, only pixels that lie | |
18724 | within the scissor box can be modified by drawing commands. Window | |
8925f36f | 18725 | coordinates have integer values at the shared corners of frame buffer |
f37e7e3d | 18726 | pixels. @code{glScissor(0,0,1,1)} allows modification of only the lower |
8925f36f AW |
18727 | left pixel in the window, and @code{glScissor(0,0,0,0)} doesn't allow |
18728 | modification of any pixels in the window. | |
18729 | ||
18730 | When the scissor test is disabled, it is as though the scissor box | |
18731 | includes the entire window. | |
18732 | ||
8925f36f AW |
18733 | @code{GL_INVALID_VALUE} is generated if either @var{width} or |
18734 | @var{height} is negative. | |
18735 | ||
18736 | @code{GL_INVALID_OPERATION} is generated if @code{glScissor} is executed | |
18737 | between the execution of @code{glBegin} and the corresponding execution | |
18738 | of @code{glEnd}. | |
18739 | ||
bb894c9d | 18740 | @end deftypefun |
8925f36f | 18741 | |
bb894c9d | 18742 | @deftypefun void glSecondaryColorPointer size type stride pointer |
3c9b6116 AW |
18743 | Define an array of secondary colors. |
18744 | ||
8925f36f AW |
18745 | @table @asis |
18746 | @item @var{size} | |
f37e7e3d | 18747 | Specifies the number of components per color. Must be 3. |
8925f36f AW |
18748 | |
18749 | @item @var{type} | |
f37e7e3d | 18750 | Specifies the data type of each color component in the array. Symbolic |
8925f36f AW |
18751 | constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, |
18752 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
f37e7e3d | 18753 | @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is |
8925f36f AW |
18754 | @code{GL_FLOAT}. |
18755 | ||
18756 | @item @var{stride} | |
f37e7e3d DH |
18757 | Specifies the byte offset between consecutive colors. If @var{stride} is |
18758 | 0, the colors are understood to be tightly packed in the array. The | |
8925f36f AW |
18759 | initial value is 0. |
18760 | ||
18761 | @item @var{pointer} | |
18762 | Specifies a pointer to the first component of the first color element in | |
f37e7e3d | 18763 | the array. The initial value is 0. |
8925f36f AW |
18764 | |
18765 | @end table | |
18766 | ||
8925f36f | 18767 | @code{glSecondaryColorPointer} specifies the location and data format of |
f37e7e3d DH |
18768 | an array of color components to use when rendering. @var{size} specifies |
18769 | the number of components per color, and must be 3. @var{type} specifies | |
18770 | the data type of each color component, and @var{stride} specifies the | |
18771 | byte stride from one color to the next, allowing vertices and attributes | |
18772 | to be packed into a single array or stored in separate arrays. | |
8925f36f AW |
18773 | |
18774 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
18775 | target (see @code{glBindBuffer}) while a secondary color array is | |
18776 | specified, @var{pointer} is treated as a byte offset into the buffer | |
f37e7e3d | 18777 | object's data store. Also, the buffer object binding |
8925f36f AW |
18778 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as secondary color vertex |
18779 | array client-side state | |
18780 | (@code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING}). | |
18781 | ||
18782 | When a secondary color array is specified, @var{size}, @var{type}, | |
18783 | @var{stride}, and @var{pointer} are saved as client-side state, in | |
18784 | addition to the current vertex array buffer object binding. | |
18785 | ||
18786 | To enable and disable the secondary color array, call | |
18787 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
f37e7e3d | 18788 | argument @code{GL_SECONDARY_COLOR_ARRAY}. If enabled, the secondary |
8925f36f AW |
18789 | color array is used when @code{glArrayElement}, @code{glDrawArrays}, |
18790 | @code{glMultiDrawArrays}, @code{glDrawElements}, | |
18791 | @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called. | |
18792 | ||
8925f36f AW |
18793 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 3. |
18794 | ||
18795 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
18796 | value. | |
18797 | ||
18798 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
18799 | ||
bb894c9d | 18800 | @end deftypefun |
8925f36f | 18801 | |
d172eed9 AW |
18802 | @deftypefun void glSecondaryColor3b red green blue |
18803 | @deftypefunx void glSecondaryColor3s red green blue | |
18804 | @deftypefunx void glSecondaryColor3i red green blue | |
ca09631c | 18805 | @deftypefunx void glSecondaryColor3f red green blue |
d172eed9 AW |
18806 | @deftypefunx void glSecondaryColor3d red green blue |
18807 | @deftypefunx void glSecondaryColor3ub red green blue | |
18808 | @deftypefunx void glSecondaryColor3us red green blue | |
bb894c9d | 18809 | @deftypefunx void glSecondaryColor3ui red green blue |
d172eed9 AW |
18810 | @deftypefunx void glSecondaryColor3bv v |
18811 | @deftypefunx void glSecondaryColor3sv v | |
18812 | @deftypefunx void glSecondaryColor3iv v | |
18813 | @deftypefunx void glSecondaryColor3fv v | |
18814 | @deftypefunx void glSecondaryColor3dv v | |
18815 | @deftypefunx void glSecondaryColor3ubv v | |
18816 | @deftypefunx void glSecondaryColor3usv v | |
18817 | @deftypefunx void glSecondaryColor3uiv v | |
3c9b6116 AW |
18818 | Set the current secondary color. |
18819 | ||
8925f36f AW |
18820 | @table @asis |
18821 | @item @var{red} | |
18822 | @itemx @var{green} | |
18823 | @itemx @var{blue} | |
18824 | Specify new red, green, and blue values for the current secondary color. | |
18825 | ||
18826 | @end table | |
18827 | ||
8925f36f AW |
18828 | The GL stores both a primary four-valued RGBA color and a secondary |
18829 | four-valued RGBA color (where alpha is always set to 0.0) that is | |
18830 | associated with every vertex. | |
18831 | ||
18832 | The secondary color is interpolated and applied to each fragment during | |
f37e7e3d | 18833 | rasterization when @code{GL_COLOR_SUM} is enabled. When lighting is |
8925f36f AW |
18834 | enabled, and @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value |
18835 | of the secondary color is assigned the value computed from the specular | |
f37e7e3d DH |
18836 | term of the lighting computation. Both the primary and secondary current |
18837 | colors are applied to each fragment, regardless of the state of | |
18838 | @code{GL_COLOR_SUM}, under such conditions. When | |
8925f36f AW |
18839 | @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value returned from |
18840 | querying the current secondary color is undefined. | |
18841 | ||
18842 | @code{glSecondaryColor3b}, @code{glSecondaryColor3s}, and | |
18843 | @code{glSecondaryColor3i} take three signed byte, short, or long | |
f37e7e3d | 18844 | integers as arguments. When @strong{v} is appended to the name, the |
8925f36f AW |
18845 | color commands can take a pointer to an array of such values. |
18846 | ||
18847 | Color values are stored in floating-point format, with unspecified | |
f37e7e3d | 18848 | mantissa and exponent sizes. Unsigned integer color components, when |
8925f36f AW |
18849 | specified, are linearly mapped to floating-point values such that the |
18850 | largest representable value maps to 1.0 (full intensity), and 0 maps to | |
f37e7e3d | 18851 | 0.0 (zero intensity). Signed integer color components, when specified, |
8925f36f AW |
18852 | are linearly mapped to floating-point values such that the most positive |
18853 | representable value maps to 1.0, and the most negative representable | |
f37e7e3d DH |
18854 | value maps to @r{-1.0}. (Note that this mapping does not convert 0 |
18855 | precisely to 0.0). Floating-point values are mapped directly. | |
8925f36f AW |
18856 | |
18857 | Neither floating-point nor signed integer values are clamped to the | |
f37e7e3d | 18858 | range @r{[0,1]} before the current color is updated. However, color |
8925f36f AW |
18859 | components are clamped to this range before they are interpolated or |
18860 | written into a color buffer. | |
18861 | ||
bb894c9d | 18862 | @end deftypefun |
8925f36f | 18863 | |
bb894c9d | 18864 | @deftypefun void glSelectBuffer size buffer |
3c9b6116 AW |
18865 | Establish a buffer for selection mode values. |
18866 | ||
8925f36f AW |
18867 | @table @asis |
18868 | @item @var{size} | |
18869 | Specifies the size of @var{buffer}. | |
18870 | ||
18871 | @item @var{buffer} | |
18872 | Returns the selection data. | |
18873 | ||
18874 | @end table | |
18875 | ||
8925f36f AW |
18876 | @code{glSelectBuffer} has two arguments: @var{buffer} is a pointer to an |
18877 | array of unsigned integers, and @var{size} indicates the size of the | |
f37e7e3d | 18878 | array. @var{buffer} returns values from the name stack (see |
8925f36f AW |
18879 | @code{glInitNames}, @code{glLoadName}, @code{glPushName}) when the |
18880 | rendering mode is @code{GL_SELECT} (see @code{glRenderMode}). | |
18881 | @code{glSelectBuffer} must be issued before selection mode is enabled, | |
18882 | and it must not be issued while the rendering mode is @code{GL_SELECT}. | |
18883 | ||
18884 | A programmer can use selection to determine which primitives are drawn | |
f37e7e3d | 18885 | into some region of a window. The region is defined by the current |
8925f36f AW |
18886 | modelview and perspective matrices. |
18887 | ||
18888 | In selection mode, no pixel fragments are produced from rasterization. | |
18889 | Instead, if a primitive or a raster position intersects the clipping | |
18890 | volume defined by the viewing frustum and the user-defined clipping | |
f37e7e3d | 18891 | planes, this primitive causes a selection hit. (With polygons, no hit |
8925f36f AW |
18892 | occurs if the polygon is culled.) When a change is made to the name |
18893 | stack, or when @code{glRenderMode} is called, a hit record is copied to | |
18894 | @var{buffer} if any hits have occurred since the last such event (name | |
f37e7e3d | 18895 | stack change or @code{glRenderMode} call). The hit record consists of |
8925f36f AW |
18896 | the number of names in the name stack at the time of the event, followed |
18897 | by the minimum and maximum depth values of all vertices that hit since | |
18898 | the previous event, followed by the name stack contents, bottom name | |
18899 | first. | |
18900 | ||
18901 | Depth values (which are in the range [0,1]) are multiplied by | |
3c9b6116 | 18902 | @r{2^32-1}, before being placed in the hit record. |
8925f36f AW |
18903 | |
18904 | An internal index into @var{buffer} is reset to 0 whenever selection | |
f37e7e3d DH |
18905 | mode is entered. Each time a hit record is copied into @var{buffer}, the |
18906 | index is incremented to point to the cell just past the end of the block | |
18907 | of names\(emthat is, to the next available cell If the hit record is | |
18908 | larger than the number of remaining locations in @var{buffer}, as much | |
18909 | data as can fit is copied, and the overflow flag is set. If the name | |
18910 | stack is empty when a hit record is copied, that record consists of 0 | |
18911 | followed by the minimum and maximum depth values. | |
8925f36f AW |
18912 | |
18913 | To exit selection mode, call @code{glRenderMode} with an argument other | |
f37e7e3d | 18914 | than @code{GL_SELECT}. Whenever @code{glRenderMode} is called while the |
8925f36f AW |
18915 | render mode is @code{GL_SELECT}, it returns the number of hit records |
18916 | copied to @var{buffer}, resets the overflow flag and the selection | |
f37e7e3d | 18917 | buffer pointer, and initializes the name stack to be empty. If the |
8925f36f AW |
18918 | overflow bit was set when @code{glRenderMode} was called, a negative hit |
18919 | record count is returned. | |
18920 | ||
8925f36f AW |
18921 | @code{GL_INVALID_VALUE} is generated if @var{size} is negative. |
18922 | ||
18923 | @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is | |
18924 | called while the render mode is @code{GL_SELECT}, or if | |
18925 | @code{glRenderMode} is called with argument @code{GL_SELECT} before | |
18926 | @code{glSelectBuffer} is called at least once. | |
18927 | ||
18928 | @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is | |
18929 | executed between the execution of @code{glBegin} and the corresponding | |
18930 | execution of @code{glEnd}. | |
18931 | ||
bb894c9d | 18932 | @end deftypefun |
8925f36f | 18933 | |
bb894c9d | 18934 | @deftypefun void glSeparableFilter2D target internalformat width height format type row column |
3c9b6116 AW |
18935 | Define a separable two-dimensional convolution filter. |
18936 | ||
8925f36f AW |
18937 | @table @asis |
18938 | @item @var{target} | |
18939 | Must be @code{GL_SEPARABLE_2D}. | |
18940 | ||
18941 | @item @var{internalformat} | |
f37e7e3d | 18942 | The internal format of the convolution filter kernel. The allowable |
8925f36f AW |
18943 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, |
18944 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
18945 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
18946 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
18947 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
18948 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
18949 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
18950 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
18951 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
18952 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
18953 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
18954 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
18955 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
18956 | ||
18957 | @item @var{width} | |
f37e7e3d | 18958 | The number of elements in the pixel array referenced by @var{row}. (This |
8925f36f AW |
18959 | is the width of the separable filter kernel.) |
18960 | ||
18961 | @item @var{height} | |
18962 | The number of elements in the pixel array referenced by @var{column}. | |
18963 | (This is the height of the separable filter kernel.) | |
18964 | ||
18965 | @item @var{format} | |
f37e7e3d | 18966 | The format of the pixel data in @var{row} and @var{column}. The |
8925f36f AW |
18967 | allowable values are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, |
18968 | @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, | |
18969 | @code{GL_BGRA}, @code{GL_INTENSITY}, @code{GL_LUMINANCE}, and | |
18970 | @code{GL_LUMINANCE_ALPHA}. | |
18971 | ||
18972 | @item @var{type} | |
f37e7e3d | 18973 | The type of the pixel data in @var{row} and @var{column}. Symbolic |
8925f36f AW |
18974 | constants @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
18975 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
18976 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
18977 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
18978 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
18979 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
18980 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
18981 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
18982 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
18983 | ||
18984 | @item @var{row} | |
18985 | Pointer to a one-dimensional array of pixel data that is processed to | |
18986 | build the row filter kernel. | |
18987 | ||
18988 | @item @var{column} | |
18989 | Pointer to a one-dimensional array of pixel data that is processed to | |
18990 | build the column filter kernel. | |
18991 | ||
18992 | @end table | |
18993 | ||
8925f36f AW |
18994 | @code{glSeparableFilter2D} builds a two-dimensional separable |
18995 | convolution filter kernel from two arrays of pixels. | |
18996 | ||
18997 | The pixel arrays specified by (@var{width}, @var{format}, @var{type}, | |
18998 | @var{row}) and (@var{height}, @var{format}, @var{type}, @var{column}) | |
18999 | are processed just as if they had been passed to @code{glDrawPixels}, | |
19000 | but processing stops after the final expansion to RGBA is completed. | |
19001 | ||
19002 | If a non-zero named buffer object is bound to the | |
19003 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
19004 | convolution filter is specified, @var{row} and @var{column} are treated | |
19005 | as byte offsets into the buffer object's data store. | |
19006 | ||
19007 | Next, the R, G, B, and A components of all pixels in both arrays are | |
19008 | scaled by the four separable 2D @code{GL_CONVOLUTION_FILTER_SCALE} | |
19009 | parameters and biased by the four separable 2D | |
f37e7e3d | 19010 | @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias |
8925f36f AW |
19011 | parameters are set by @code{glConvolutionParameter} using the |
19012 | @code{GL_SEPARABLE_2D} target and the names | |
19013 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
f37e7e3d DH |
19014 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors |
19015 | of four values that are applied to red, green, blue, and alpha, in that | |
19016 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
19017 | during this process. | |
8925f36f AW |
19018 | |
19019 | Each pixel is then converted to the internal format specified by | |
f37e7e3d | 19020 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 19021 | of the pixel (R, G, B, and A) to the values included in the internal |
f37e7e3d | 19022 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
19023 | is as follows: |
19024 | ||
19025 | @table @asis | |
19026 | @item @strong{Internal Format} | |
19027 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
19028 | @strong{Luminance}, @strong{Intensity} | |
19029 | ||
19030 | @item @code{GL_LUMINANCE} | |
19031 | , , , , R , | |
19032 | ||
19033 | @item @code{GL_LUMINANCE_ALPHA} | |
19034 | , , , A , R , | |
19035 | ||
19036 | @item @code{GL_INTENSITY} | |
19037 | , , , , , R | |
19038 | ||
19039 | @item @code{GL_RGB} | |
19040 | R , G , B , , , | |
19041 | ||
19042 | @item @code{GL_RGBA} | |
19043 | R , G , B , A , , | |
19044 | ||
19045 | @end table | |
19046 | ||
19047 | The red, green, blue, alpha, luminance, and/or intensity components of | |
19048 | the resulting pixels are stored in floating-point rather than integer | |
f37e7e3d | 19049 | format. They form two one-dimensional filter kernel images. The row |
8925f36f | 19050 | image is indexed by coordinate @var{i} starting at zero and increasing |
f37e7e3d DH |
19051 | from left to right. Each location in the row image is derived from |
19052 | element @var{i} of @var{row}. The column image is indexed by coordinate | |
19053 | @var{j} starting at zero and increasing from bottom to top. Each | |
8925f36f AW |
19054 | location in the column image is derived from element @var{j} of |
19055 | @var{column}. | |
19056 | ||
19057 | Note that after a convolution is performed, the resulting color | |
19058 | components are also scaled by their corresponding | |
19059 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
19060 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
19061 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
f37e7e3d | 19062 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. |
8925f36f | 19063 | |
8925f36f AW |
19064 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
19065 | @code{GL_SEPARABLE_2D}. | |
19066 | ||
19067 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
19068 | of the allowable values. | |
19069 | ||
19070 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
19071 | allowable values. | |
19072 | ||
19073 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
19074 | allowable values. | |
19075 | ||
19076 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
f37e7e3d DH |
19077 | greater than the maximum supported value. This value may be queried with |
19078 | @code{glGetConvolutionParameter} using target @code{GL_SEPARABLE_2D} and | |
19079 | name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
8925f36f AW |
19080 | |
19081 | @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero | |
f37e7e3d | 19082 | or greater than the maximum supported value. This value may be queried |
8925f36f AW |
19083 | with @code{glGetConvolutionParameter} using target |
19084 | @code{GL_SEPARABLE_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
19085 | ||
19086 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
19087 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
19088 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
19089 | and @var{format} is not @code{GL_RGB}. | |
19090 | ||
19091 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
19092 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
19093 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
19094 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
19095 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
19096 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
19097 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
19098 | ||
19099 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
19100 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
19101 | object's data store is currently mapped. | |
19102 | ||
19103 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
19104 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
19105 | would be unpacked from the buffer object such that the memory reads | |
19106 | required would exceed the data store size. | |
19107 | ||
19108 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
19109 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{row} | |
19110 | or @var{column} is not evenly divisible into the number of bytes needed | |
19111 | to store in memory a datum indicated by @var{type}. | |
19112 | ||
19113 | @code{GL_INVALID_OPERATION} is generated if @code{glSeparableFilter2D} | |
19114 | is executed between the execution of @code{glBegin} and the | |
19115 | corresponding execution of @code{glEnd}. | |
19116 | ||
bb894c9d | 19117 | @end deftypefun |
8925f36f | 19118 | |
bb894c9d | 19119 | @deftypefun void glShadeModel mode |
3c9b6116 AW |
19120 | Select flat or smooth shading. |
19121 | ||
8925f36f AW |
19122 | @table @asis |
19123 | @item @var{mode} | |
f37e7e3d DH |
19124 | Specifies a symbolic value representing a shading technique. Accepted |
19125 | values are @code{GL_FLAT} and @code{GL_SMOOTH}. The initial value is | |
8925f36f AW |
19126 | @code{GL_SMOOTH}. |
19127 | ||
19128 | @end table | |
19129 | ||
f37e7e3d | 19130 | GL primitives can have either flat or smooth shading. Smooth shading, |
8925f36f AW |
19131 | the default, causes the computed colors of vertices to be interpolated |
19132 | as the primitive is rasterized, typically assigning different colors to | |
f37e7e3d | 19133 | each resulting pixel fragment. Flat shading selects the computed color |
8925f36f | 19134 | of just one vertex and assigns it to all the pixel fragments generated |
f37e7e3d DH |
19135 | by rasterizing a single primitive. In either case, the computed color of |
19136 | a vertex is the result of lighting if lighting is enabled, or it is the | |
19137 | current color at the time the vertex was specified if lighting is | |
8925f36f AW |
19138 | disabled. |
19139 | ||
f37e7e3d | 19140 | Flat and smooth shading are indistinguishable for points. Starting when |
8925f36f | 19141 | @code{glBegin} is issued and counting vertices and primitives from 1, |
3c9b6116 | 19142 | the GL gives each flat-shaded line segment @r{@var{i}} the computed |
f37e7e3d | 19143 | color of vertex @r{@var{i}+1}, its second vertex. Counting similarly |
8925f36f | 19144 | from 1, the GL gives each flat-shaded polygon the computed color of the |
f37e7e3d DH |
19145 | vertex listed in the following table. This is the last vertex to specify |
19146 | the polygon in all cases except single polygons, where the first vertex | |
19147 | specifies the flat-shaded color. | |
8925f36f AW |
19148 | |
19149 | ||
19150 | ||
19151 | @table @asis | |
19152 | @item @strong{ | |
3c9b6116 | 19153 | Primitive Type of Polygon @r{@var{i}}} |
8925f36f AW |
19154 | @strong{Vertex} |
19155 | ||
19156 | @item | |
19157 | Single polygon | |
3c9b6116 | 19158 | (@r{@var{i}==1}) |
8925f36f AW |
19159 | 1 |
19160 | ||
19161 | @item | |
19162 | Triangle strip | |
3c9b6116 | 19163 | @r{@var{i}+2} |
8925f36f AW |
19164 | |
19165 | @item | |
19166 | Triangle fan | |
3c9b6116 | 19167 | @r{@var{i}+2} |
8925f36f AW |
19168 | |
19169 | @item | |
19170 | Independent triangle | |
3c9b6116 | 19171 | @r{3@var{i}} |
8925f36f AW |
19172 | |
19173 | @item | |
19174 | Quad strip | |
3c9b6116 | 19175 | @r{2@var{i}+2} |
8925f36f AW |
19176 | |
19177 | @item | |
19178 | Independent quad | |
3c9b6116 | 19179 | @r{4@var{i}} |
8925f36f AW |
19180 | |
19181 | @end table | |
19182 | ||
19183 | Flat and smooth shading are specified by @code{glShadeModel} with | |
19184 | @var{mode} set to @code{GL_FLAT} and @code{GL_SMOOTH}, respectively. | |
19185 | ||
8925f36f AW |
19186 | @code{GL_INVALID_ENUM} is generated if @var{mode} is any value other |
19187 | than @code{GL_FLAT} or @code{GL_SMOOTH}. | |
19188 | ||
19189 | @code{GL_INVALID_OPERATION} is generated if @code{glShadeModel} is | |
19190 | executed between the execution of @code{glBegin} and the corresponding | |
19191 | execution of @code{glEnd}. | |
19192 | ||
bb894c9d | 19193 | @end deftypefun |
8925f36f | 19194 | |
bb894c9d | 19195 | @deftypefun void glShaderSource shader count string length |
3c9b6116 AW |
19196 | Replaces the source code in a shader object. |
19197 | ||
8925f36f AW |
19198 | @table @asis |
19199 | @item @var{shader} | |
19200 | Specifies the handle of the shader object whose source code is to be | |
19201 | replaced. | |
19202 | ||
19203 | @item @var{count} | |
19204 | Specifies the number of elements in the @var{string} and @var{length} | |
19205 | arrays. | |
19206 | ||
19207 | @item @var{string} | |
19208 | Specifies an array of pointers to strings containing the source code to | |
19209 | be loaded into the shader. | |
19210 | ||
19211 | @item @var{length} | |
19212 | Specifies an array of string lengths. | |
19213 | ||
19214 | @end table | |
19215 | ||
8925f36f | 19216 | @code{glShaderSource} sets the source code in @var{shader} to the source |
f37e7e3d DH |
19217 | code in the array of strings specified by @var{string}. Any source code |
19218 | previously stored in the shader object is completely replaced. The | |
19219 | number of strings in the array is specified by @var{count}. If | |
8925f36f | 19220 | @var{length} is @code{NULL}, each string is assumed to be null |
f37e7e3d DH |
19221 | terminated. If @var{length} is a value other than @code{NULL}, it points |
19222 | to an array containing a string length for each of the corresponding | |
19223 | elements of @var{string}. Each element in the @var{length} array may | |
19224 | contain the length of the corresponding string (the null character is | |
19225 | not counted as part of the string length) or a value less than 0 to | |
19226 | indicate that the string is null terminated. The source code strings are | |
19227 | not scanned or parsed at this time; they are simply copied into the | |
19228 | specified shader object. | |
8925f36f | 19229 | |
8925f36f AW |
19230 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
19231 | generated by OpenGL. | |
19232 | ||
19233 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
19234 | object. | |
19235 | ||
19236 | @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0. | |
19237 | ||
19238 | @code{GL_INVALID_OPERATION} is generated if @code{glShaderSource} is | |
19239 | executed between the execution of @code{glBegin} and the corresponding | |
19240 | execution of @code{glEnd}. | |
19241 | ||
bb894c9d | 19242 | @end deftypefun |
8925f36f | 19243 | |
bb894c9d | 19244 | @deftypefun void glStencilFuncSeparate face func ref mask |
3c9b6116 AW |
19245 | Set front and/or back function and reference value for stencil testing. |
19246 | ||
8925f36f AW |
19247 | @table @asis |
19248 | @item @var{face} | |
f37e7e3d | 19249 | Specifies whether front and/or back stencil state is updated. Three |
8925f36f AW |
19250 | symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and |
19251 | @code{GL_FRONT_AND_BACK}. | |
19252 | ||
19253 | @item @var{func} | |
f37e7e3d | 19254 | Specifies the test function. Eight symbolic constants are valid: |
8925f36f AW |
19255 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER}, |
19256 | @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and | |
f37e7e3d | 19257 | @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}. |
8925f36f AW |
19258 | |
19259 | @item @var{ref} | |
f37e7e3d DH |
19260 | Specifies the reference value for the stencil test. @var{ref} is clamped |
19261 | to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of | |
19262 | bitplanes in the stencil buffer. The initial value is 0. | |
8925f36f AW |
19263 | |
19264 | @item @var{mask} | |
19265 | Specifies a mask that is ANDed with both the reference value and the | |
f37e7e3d | 19266 | stored stencil value when the test is done. The initial value is all |
8925f36f AW |
19267 | 1's. |
19268 | ||
19269 | @end table | |
19270 | ||
8925f36f | 19271 | Stenciling, like depth-buffering, enables and disables drawing on a |
f37e7e3d | 19272 | per-pixel basis. You draw into the stencil planes using GL drawing |
8925f36f | 19273 | primitives, then render geometry and images, using the stencil planes to |
f37e7e3d | 19274 | mask out portions of the screen. Stenciling is typically used in |
8925f36f AW |
19275 | multipass rendering algorithms to achieve special effects, such as |
19276 | decals, outlining, and constructive solid geometry rendering. | |
19277 | ||
19278 | The stencil test conditionally eliminates a pixel based on the outcome | |
19279 | of a comparison between the reference value and the value in the stencil | |
f37e7e3d DH |
19280 | buffer. To enable and disable the test, call @code{glEnable} and |
19281 | @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify | |
8925f36f AW |
19282 | actions based on the outcome of the stencil test, call |
19283 | @code{glStencilOp} or @code{glStencilOpSeparate}. | |
19284 | ||
19285 | There can be two separate sets of @var{func}, @var{ref}, and @var{mask} | |
19286 | parameters; one affects back-facing polygons, and the other affects | |
19287 | front-facing polygons as well as other non-polygon primitives. | |
19288 | @code{glStencilFunc} sets both front and back stencil state to the same | |
19289 | values, as if @code{glStencilFuncSeparate} were called with @var{face} | |
19290 | set to @code{GL_FRONT_AND_BACK}. | |
19291 | ||
19292 | @var{func} is a symbolic constant that determines the stencil comparison | |
f37e7e3d | 19293 | function. It accepts one of eight values, shown in the following list. |
8925f36f | 19294 | @var{ref} is an integer reference value that is used in the stencil |
f37e7e3d DH |
19295 | comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where |
19296 | @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask} | |
3c9b6116 AW |
19297 | is bitwise ANDed with both the reference value and the stored stencil |
19298 | value, with the ANDed values participating in the comparison. | |
8925f36f AW |
19299 | |
19300 | If @var{stencil} represents the value stored in the corresponding | |
19301 | stencil buffer location, the following list shows the effect of each | |
f37e7e3d | 19302 | comparison function that can be specified by @var{func}. Only if the |
8925f36f | 19303 | comparison succeeds is the pixel passed through to the next stage in the |
f37e7e3d | 19304 | rasterization process (see @code{glStencilOp}). All tests treat |
8925f36f | 19305 | @var{stencil} values as unsigned integers in the range |
3c9b6116 AW |
19306 | @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the |
19307 | stencil buffer. | |
8925f36f AW |
19308 | |
19309 | The following values are accepted by @var{func}: | |
19310 | ||
19311 | @table @asis | |
19312 | @item @code{GL_NEVER} | |
19313 | Always fails. | |
19314 | ||
19315 | @item @code{GL_LESS} | |
19316 | Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ). | |
19317 | ||
19318 | @item @code{GL_LEQUAL} | |
19319 | Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ). | |
19320 | ||
19321 | @item @code{GL_GREATER} | |
19322 | Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ). | |
19323 | ||
19324 | @item @code{GL_GEQUAL} | |
19325 | Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ). | |
19326 | ||
19327 | @item @code{GL_EQUAL} | |
19328 | Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ). | |
19329 | ||
19330 | @item @code{GL_NOTEQUAL} | |
19331 | Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ). | |
19332 | ||
19333 | @item @code{GL_ALWAYS} | |
19334 | Always passes. | |
19335 | ||
19336 | @end table | |
19337 | ||
8925f36f AW |
19338 | @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the |
19339 | eight accepted values. | |
19340 | ||
19341 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilFuncSeparate} | |
19342 | is executed between the execution of @code{glBegin} and the | |
19343 | corresponding execution of @code{glEnd}. | |
19344 | ||
bb894c9d | 19345 | @end deftypefun |
8925f36f | 19346 | |
bb894c9d | 19347 | @deftypefun void glStencilFunc func ref mask |
3c9b6116 AW |
19348 | Set front and back function and reference value for stencil testing. |
19349 | ||
8925f36f AW |
19350 | @table @asis |
19351 | @item @var{func} | |
f37e7e3d | 19352 | Specifies the test function. Eight symbolic constants are valid: |
8925f36f AW |
19353 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER}, |
19354 | @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and | |
f37e7e3d | 19355 | @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}. |
8925f36f AW |
19356 | |
19357 | @item @var{ref} | |
f37e7e3d DH |
19358 | Specifies the reference value for the stencil test. @var{ref} is clamped |
19359 | to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of | |
19360 | bitplanes in the stencil buffer. The initial value is 0. | |
8925f36f AW |
19361 | |
19362 | @item @var{mask} | |
19363 | Specifies a mask that is ANDed with both the reference value and the | |
f37e7e3d | 19364 | stored stencil value when the test is done. The initial value is all |
8925f36f AW |
19365 | 1's. |
19366 | ||
19367 | @end table | |
19368 | ||
8925f36f | 19369 | Stenciling, like depth-buffering, enables and disables drawing on a |
f37e7e3d | 19370 | per-pixel basis. Stencil planes are first drawn into using GL drawing |
8925f36f | 19371 | primitives, then geometry and images are rendered using the stencil |
f37e7e3d | 19372 | planes to mask out portions of the screen. Stenciling is typically used |
8925f36f AW |
19373 | in multipass rendering algorithms to achieve special effects, such as |
19374 | decals, outlining, and constructive solid geometry rendering. | |
19375 | ||
19376 | The stencil test conditionally eliminates a pixel based on the outcome | |
19377 | of a comparison between the reference value and the value in the stencil | |
f37e7e3d DH |
19378 | buffer. To enable and disable the test, call @code{glEnable} and |
19379 | @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify | |
8925f36f AW |
19380 | actions based on the outcome of the stencil test, call |
19381 | @code{glStencilOp} or @code{glStencilOpSeparate}. | |
19382 | ||
19383 | There can be two separate sets of @var{func}, @var{ref}, and @var{mask} | |
19384 | parameters; one affects back-facing polygons, and the other affects | |
19385 | front-facing polygons as well as other non-polygon primitives. | |
19386 | @code{glStencilFunc} sets both front and back stencil state to the same | |
f37e7e3d | 19387 | values. Use @code{glStencilFuncSeparate} to set front and back stencil |
8925f36f AW |
19388 | state to different values. |
19389 | ||
19390 | @var{func} is a symbolic constant that determines the stencil comparison | |
f37e7e3d | 19391 | function. It accepts one of eight values, shown in the following list. |
8925f36f | 19392 | @var{ref} is an integer reference value that is used in the stencil |
f37e7e3d DH |
19393 | comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where |
19394 | @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask} | |
3c9b6116 AW |
19395 | is bitwise ANDed with both the reference value and the stored stencil |
19396 | value, with the ANDed values participating in the comparison. | |
8925f36f AW |
19397 | |
19398 | If @var{stencil} represents the value stored in the corresponding | |
19399 | stencil buffer location, the following list shows the effect of each | |
f37e7e3d | 19400 | comparison function that can be specified by @var{func}. Only if the |
8925f36f | 19401 | comparison succeeds is the pixel passed through to the next stage in the |
f37e7e3d | 19402 | rasterization process (see @code{glStencilOp}). All tests treat |
8925f36f | 19403 | @var{stencil} values as unsigned integers in the range |
3c9b6116 AW |
19404 | @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the |
19405 | stencil buffer. | |
8925f36f AW |
19406 | |
19407 | The following values are accepted by @var{func}: | |
19408 | ||
19409 | @table @asis | |
19410 | @item @code{GL_NEVER} | |
19411 | Always fails. | |
19412 | ||
19413 | @item @code{GL_LESS} | |
19414 | Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ). | |
19415 | ||
19416 | @item @code{GL_LEQUAL} | |
19417 | Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ). | |
19418 | ||
19419 | @item @code{GL_GREATER} | |
19420 | Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ). | |
19421 | ||
19422 | @item @code{GL_GEQUAL} | |
19423 | Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ). | |
19424 | ||
19425 | @item @code{GL_EQUAL} | |
19426 | Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ). | |
19427 | ||
19428 | @item @code{GL_NOTEQUAL} | |
19429 | Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ). | |
19430 | ||
19431 | @item @code{GL_ALWAYS} | |
19432 | Always passes. | |
19433 | ||
19434 | @end table | |
19435 | ||
8925f36f AW |
19436 | @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the |
19437 | eight accepted values. | |
19438 | ||
19439 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilFunc} is | |
19440 | executed between the execution of @code{glBegin} and the corresponding | |
19441 | execution of @code{glEnd}. | |
19442 | ||
bb894c9d | 19443 | @end deftypefun |
8925f36f | 19444 | |
bb894c9d | 19445 | @deftypefun void glStencilMaskSeparate face mask |
3c9b6116 AW |
19446 | Control the front and/or back writing of individual bits in the stencil |
19447 | planes. | |
19448 | ||
8925f36f AW |
19449 | @table @asis |
19450 | @item @var{face} | |
19451 | Specifies whether the front and/or back stencil writemask is updated. | |
19452 | Three symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and | |
19453 | @code{GL_FRONT_AND_BACK}. | |
19454 | ||
19455 | @item @var{mask} | |
19456 | Specifies a bit mask to enable and disable writing of individual bits in | |
f37e7e3d | 19457 | the stencil planes. Initially, the mask is all 1's. |
8925f36f AW |
19458 | |
19459 | @end table | |
19460 | ||
8925f36f | 19461 | @code{glStencilMaskSeparate} controls the writing of individual bits in |
f37e7e3d | 19462 | the stencil planes. The least significant @r{@var{n}} bits of |
3c9b6116 | 19463 | @var{mask}, where @r{@var{n}} is the number of bits in the stencil |
f37e7e3d DH |
19464 | buffer, specify a mask. Where a 1 appears in the mask, it's possible to |
19465 | write to the corresponding bit in the stencil buffer. Where a 0 appears, | |
19466 | the corresponding bit is write-protected. Initially, all bits are | |
19467 | enabled for writing. | |
8925f36f AW |
19468 | |
19469 | There can be two separate @var{mask} writemasks; one affects back-facing | |
19470 | polygons, and the other affects front-facing polygons as well as other | |
f37e7e3d | 19471 | non-polygon primitives. @code{glStencilMask} sets both front and back |
8925f36f AW |
19472 | stencil writemasks to the same values, as if |
19473 | @code{glStencilMaskSeparate} were called with @var{face} set to | |
19474 | @code{GL_FRONT_AND_BACK}. | |
19475 | ||
8925f36f AW |
19476 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilMaskSeparate} |
19477 | is executed between the execution of @code{glBegin} and the | |
19478 | corresponding execution of @code{glEnd}. | |
19479 | ||
bb894c9d | 19480 | @end deftypefun |
8925f36f | 19481 | |
bb894c9d | 19482 | @deftypefun void glStencilMask mask |
3c9b6116 AW |
19483 | Control the front and back writing of individual bits in the stencil |
19484 | planes. | |
19485 | ||
8925f36f AW |
19486 | @table @asis |
19487 | @item @var{mask} | |
19488 | Specifies a bit mask to enable and disable writing of individual bits in | |
f37e7e3d | 19489 | the stencil planes. Initially, the mask is all 1's. |
8925f36f AW |
19490 | |
19491 | @end table | |
19492 | ||
8925f36f | 19493 | @code{glStencilMask} controls the writing of individual bits in the |
f37e7e3d | 19494 | stencil planes. The least significant @r{@var{n}} bits of @var{mask}, |
3c9b6116 | 19495 | where @r{@var{n}} is the number of bits in the stencil buffer, specify a |
f37e7e3d DH |
19496 | mask. Where a 1 appears in the mask, it's possible to write to the |
19497 | corresponding bit in the stencil buffer. Where a 0 appears, the | |
19498 | corresponding bit is write-protected. Initially, all bits are enabled | |
8925f36f AW |
19499 | for writing. |
19500 | ||
19501 | There can be two separate @var{mask} writemasks; one affects back-facing | |
19502 | polygons, and the other affects front-facing polygons as well as other | |
f37e7e3d DH |
19503 | non-polygon primitives. @code{glStencilMask} sets both front and back |
19504 | stencil writemasks to the same values. Use @code{glStencilMaskSeparate} | |
8925f36f AW |
19505 | to set front and back stencil writemasks to different values. |
19506 | ||
8925f36f AW |
19507 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilMask} is |
19508 | executed between the execution of @code{glBegin} and the corresponding | |
19509 | execution of @code{glEnd}. | |
19510 | ||
bb894c9d | 19511 | @end deftypefun |
8925f36f | 19512 | |
bb894c9d | 19513 | @deftypefun void glStencilOpSeparate face sfail dpfail dppass |
3c9b6116 AW |
19514 | Set front and/or back stencil test actions. |
19515 | ||
8925f36f AW |
19516 | @table @asis |
19517 | @item @var{face} | |
f37e7e3d | 19518 | Specifies whether front and/or back stencil state is updated. Three |
8925f36f AW |
19519 | symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and |
19520 | @code{GL_FRONT_AND_BACK}. | |
19521 | ||
19522 | @item @var{sfail} | |
f37e7e3d DH |
19523 | Specifies the action to take when the stencil test fails. Eight symbolic |
19524 | constants are accepted: @code{GL_KEEP}, @code{GL_ZERO}, | |
8925f36f | 19525 | @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR}, |
f37e7e3d | 19526 | @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is |
8925f36f AW |
19527 | @code{GL_KEEP}. |
19528 | ||
19529 | @item @var{dpfail} | |
19530 | Specifies the stencil action when the stencil test passes, but the depth | |
f37e7e3d DH |
19531 | test fails. @var{dpfail} accepts the same symbolic constants as |
19532 | @var{sfail}. The initial value is @code{GL_KEEP}. | |
8925f36f AW |
19533 | |
19534 | @item @var{dppass} | |
19535 | Specifies the stencil action when both the stencil test and the depth | |
19536 | test pass, or when the stencil test passes and either there is no depth | |
f37e7e3d DH |
19537 | buffer or depth testing is not enabled. @var{dppass} accepts the same |
19538 | symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}. | |
8925f36f AW |
19539 | |
19540 | @end table | |
19541 | ||
8925f36f | 19542 | Stenciling, like depth-buffering, enables and disables drawing on a |
f37e7e3d | 19543 | per-pixel basis. You draw into the stencil planes using GL drawing |
8925f36f | 19544 | primitives, then render geometry and images, using the stencil planes to |
f37e7e3d | 19545 | mask out portions of the screen. Stenciling is typically used in |
8925f36f AW |
19546 | multipass rendering algorithms to achieve special effects, such as |
19547 | decals, outlining, and constructive solid geometry rendering. | |
19548 | ||
19549 | The stencil test conditionally eliminates a pixel based on the outcome | |
19550 | of a comparison between the value in the stencil buffer and a reference | |
f37e7e3d | 19551 | value. To enable and disable the test, call @code{glEnable} and |
8925f36f AW |
19552 | @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it, |
19553 | call @code{glStencilFunc} or @code{glStencilFuncSeparate}. | |
19554 | ||
19555 | There can be two separate sets of @var{sfail}, @var{dpfail}, and | |
19556 | @var{dppass} parameters; one affects back-facing polygons, and the other | |
19557 | affects front-facing polygons as well as other non-polygon primitives. | |
19558 | @code{glStencilOp} sets both front and back stencil state to the same | |
19559 | values, as if @code{glStencilOpSeparate} were called with @var{face} set | |
19560 | to @code{GL_FRONT_AND_BACK}. | |
19561 | ||
19562 | @code{glStencilOpSeparate} takes three arguments that indicate what | |
f37e7e3d | 19563 | happens to the stored stencil value while stenciling is enabled. If the |
8925f36f AW |
19564 | stencil test fails, no change is made to the pixel's color or depth |
19565 | buffers, and @var{sfail} specifies what happens to the stencil buffer | |
f37e7e3d | 19566 | contents. The following eight actions are possible. |
8925f36f AW |
19567 | |
19568 | @table @asis | |
19569 | @item @code{GL_KEEP} | |
19570 | Keeps the current value. | |
19571 | ||
19572 | @item @code{GL_ZERO} | |
19573 | Sets the stencil buffer value to 0. | |
19574 | ||
19575 | @item @code{GL_REPLACE} | |
19576 | Sets the stencil buffer value to @var{ref}, as specified by | |
19577 | @code{glStencilFunc}. | |
19578 | ||
19579 | @item @code{GL_INCR} | |
f37e7e3d | 19580 | Increments the current stencil buffer value. Clamps to the maximum |
8925f36f AW |
19581 | representable unsigned value. |
19582 | ||
19583 | @item @code{GL_INCR_WRAP} | |
f37e7e3d | 19584 | Increments the current stencil buffer value. Wraps stencil buffer value |
8925f36f AW |
19585 | to zero when incrementing the maximum representable unsigned value. |
19586 | ||
19587 | @item @code{GL_DECR} | |
f37e7e3d | 19588 | Decrements the current stencil buffer value. Clamps to 0. |
8925f36f AW |
19589 | |
19590 | @item @code{GL_DECR_WRAP} | |
f37e7e3d | 19591 | Decrements the current stencil buffer value. Wraps stencil buffer value |
8925f36f AW |
19592 | to the maximum representable unsigned value when decrementing a stencil |
19593 | buffer value of zero. | |
19594 | ||
19595 | @item @code{GL_INVERT} | |
19596 | Bitwise inverts the current stencil buffer value. | |
19597 | ||
19598 | @end table | |
19599 | ||
f37e7e3d DH |
19600 | Stencil buffer values are treated as unsigned integers. When incremented |
19601 | and decremented, values are clamped to 0 and @r{2^@var{n}-1}, where | |
19602 | @r{@var{n}} is the value returned by querying @code{GL_STENCIL_BITS}. | |
8925f36f AW |
19603 | |
19604 | The other two arguments to @code{glStencilOpSeparate} specify stencil | |
19605 | buffer actions that depend on whether subsequent depth buffer tests | |
19606 | succeed (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}). | |
19607 | The actions are specified using the same eight symbolic constants as | |
f37e7e3d DH |
19608 | @var{sfail}. Note that @var{dpfail} is ignored when there is no depth |
19609 | buffer, or when the depth buffer is not enabled. In these cases, | |
8925f36f AW |
19610 | @var{sfail} and @var{dppass} specify stencil action when the stencil |
19611 | test fails and passes, respectively. | |
19612 | ||
8925f36f AW |
19613 | @code{GL_INVALID_ENUM} is generated if @var{face} is any value other |
19614 | than @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}. | |
19615 | ||
19616 | @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or | |
19617 | @var{dppass} is any value other than the eight defined constant values. | |
19618 | ||
19619 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilOpSeparate} | |
19620 | is executed between the execution of @code{glBegin} and the | |
19621 | corresponding execution of @code{glEnd}. | |
19622 | ||
bb894c9d | 19623 | @end deftypefun |
8925f36f | 19624 | |
bb894c9d | 19625 | @deftypefun void glStencilOp sfail dpfail dppass |
3c9b6116 AW |
19626 | Set front and back stencil test actions. |
19627 | ||
8925f36f AW |
19628 | @table @asis |
19629 | @item @var{sfail} | |
f37e7e3d DH |
19630 | Specifies the action to take when the stencil test fails. Eight symbolic |
19631 | constants are accepted: @code{GL_KEEP}, @code{GL_ZERO}, | |
8925f36f | 19632 | @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR}, |
f37e7e3d | 19633 | @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is |
8925f36f AW |
19634 | @code{GL_KEEP}. |
19635 | ||
19636 | @item @var{dpfail} | |
19637 | Specifies the stencil action when the stencil test passes, but the depth | |
f37e7e3d DH |
19638 | test fails. @var{dpfail} accepts the same symbolic constants as |
19639 | @var{sfail}. The initial value is @code{GL_KEEP}. | |
8925f36f AW |
19640 | |
19641 | @item @var{dppass} | |
19642 | Specifies the stencil action when both the stencil test and the depth | |
19643 | test pass, or when the stencil test passes and either there is no depth | |
f37e7e3d DH |
19644 | buffer or depth testing is not enabled. @var{dppass} accepts the same |
19645 | symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}. | |
8925f36f AW |
19646 | |
19647 | @end table | |
19648 | ||
8925f36f | 19649 | Stenciling, like depth-buffering, enables and disables drawing on a |
f37e7e3d | 19650 | per-pixel basis. You draw into the stencil planes using GL drawing |
8925f36f | 19651 | primitives, then render geometry and images, using the stencil planes to |
f37e7e3d | 19652 | mask out portions of the screen. Stenciling is typically used in |
8925f36f AW |
19653 | multipass rendering algorithms to achieve special effects, such as |
19654 | decals, outlining, and constructive solid geometry rendering. | |
19655 | ||
19656 | The stencil test conditionally eliminates a pixel based on the outcome | |
19657 | of a comparison between the value in the stencil buffer and a reference | |
f37e7e3d | 19658 | value. To enable and disable the test, call @code{glEnable} and |
8925f36f AW |
19659 | @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it, |
19660 | call @code{glStencilFunc} or @code{glStencilFuncSeparate}. | |
19661 | ||
19662 | There can be two separate sets of @var{sfail}, @var{dpfail}, and | |
19663 | @var{dppass} parameters; one affects back-facing polygons, and the other | |
19664 | affects front-facing polygons as well as other non-polygon primitives. | |
19665 | @code{glStencilOp} sets both front and back stencil state to the same | |
f37e7e3d | 19666 | values. Use @code{glStencilOpSeparate} to set front and back stencil |
8925f36f AW |
19667 | state to different values. |
19668 | ||
19669 | @code{glStencilOp} takes three arguments that indicate what happens to | |
f37e7e3d | 19670 | the stored stencil value while stenciling is enabled. If the stencil |
8925f36f | 19671 | test fails, no change is made to the pixel's color or depth buffers, and |
f37e7e3d | 19672 | @var{sfail} specifies what happens to the stencil buffer contents. The |
8925f36f AW |
19673 | following eight actions are possible. |
19674 | ||
19675 | @table @asis | |
19676 | @item @code{GL_KEEP} | |
19677 | Keeps the current value. | |
19678 | ||
19679 | @item @code{GL_ZERO} | |
19680 | Sets the stencil buffer value to 0. | |
19681 | ||
19682 | @item @code{GL_REPLACE} | |
19683 | Sets the stencil buffer value to @var{ref}, as specified by | |
19684 | @code{glStencilFunc}. | |
19685 | ||
19686 | @item @code{GL_INCR} | |
f37e7e3d | 19687 | Increments the current stencil buffer value. Clamps to the maximum |
8925f36f AW |
19688 | representable unsigned value. |
19689 | ||
19690 | @item @code{GL_INCR_WRAP} | |
f37e7e3d | 19691 | Increments the current stencil buffer value. Wraps stencil buffer value |
8925f36f AW |
19692 | to zero when incrementing the maximum representable unsigned value. |
19693 | ||
19694 | @item @code{GL_DECR} | |
f37e7e3d | 19695 | Decrements the current stencil buffer value. Clamps to 0. |
8925f36f AW |
19696 | |
19697 | @item @code{GL_DECR_WRAP} | |
f37e7e3d | 19698 | Decrements the current stencil buffer value. Wraps stencil buffer value |
8925f36f AW |
19699 | to the maximum representable unsigned value when decrementing a stencil |
19700 | buffer value of zero. | |
19701 | ||
19702 | @item @code{GL_INVERT} | |
19703 | Bitwise inverts the current stencil buffer value. | |
19704 | ||
19705 | @end table | |
19706 | ||
f37e7e3d DH |
19707 | Stencil buffer values are treated as unsigned integers. When incremented |
19708 | and decremented, values are clamped to 0 and @r{2^@var{n}-1}, where | |
19709 | @r{@var{n}} is the value returned by querying @code{GL_STENCIL_BITS}. | |
8925f36f AW |
19710 | |
19711 | The other two arguments to @code{glStencilOp} specify stencil buffer | |
19712 | actions that depend on whether subsequent depth buffer tests succeed | |
f37e7e3d | 19713 | (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}). The |
8925f36f | 19714 | actions are specified using the same eight symbolic constants as |
f37e7e3d DH |
19715 | @var{sfail}. Note that @var{dpfail} is ignored when there is no depth |
19716 | buffer, or when the depth buffer is not enabled. In these cases, | |
8925f36f AW |
19717 | @var{sfail} and @var{dppass} specify stencil action when the stencil |
19718 | test fails and passes, respectively. | |
19719 | ||
8925f36f AW |
19720 | @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or |
19721 | @var{dppass} is any value other than the eight defined constant values. | |
19722 | ||
19723 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilOp} is | |
19724 | executed between the execution of @code{glBegin} and the corresponding | |
19725 | execution of @code{glEnd}. | |
19726 | ||
bb894c9d | 19727 | @end deftypefun |
8925f36f | 19728 | |
bb894c9d | 19729 | @deftypefun void glTexCoordPointer size type stride pointer |
3c9b6116 AW |
19730 | Define an array of texture coordinates. |
19731 | ||
8925f36f AW |
19732 | @table @asis |
19733 | @item @var{size} | |
f37e7e3d DH |
19734 | Specifies the number of coordinates per array element. Must be 1, 2, 3, |
19735 | or 4. The initial value is 4. | |
8925f36f AW |
19736 | |
19737 | @item @var{type} | |
f37e7e3d | 19738 | Specifies the data type of each texture coordinate. Symbolic constants |
8925f36f | 19739 | @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or @code{GL_DOUBLE} are |
f37e7e3d | 19740 | accepted. The initial value is @code{GL_FLOAT}. |
8925f36f AW |
19741 | |
19742 | @item @var{stride} | |
19743 | Specifies the byte offset between consecutive texture coordinate sets. | |
19744 | If @var{stride} is 0, the array elements are understood to be tightly | |
f37e7e3d | 19745 | packed. The initial value is 0. |
8925f36f AW |
19746 | |
19747 | @item @var{pointer} | |
19748 | Specifies a pointer to the first coordinate of the first texture | |
f37e7e3d | 19749 | coordinate set in the array. The initial value is 0. |
8925f36f AW |
19750 | |
19751 | @end table | |
19752 | ||
8925f36f | 19753 | @code{glTexCoordPointer} specifies the location and data format of an |
f37e7e3d DH |
19754 | array of texture coordinates to use when rendering. @var{size} specifies |
19755 | the number of coordinates per texture coordinate set, and must be 1, 2, | |
19756 | 3, or 4. @var{type} specifies the data type of each texture coordinate, | |
19757 | and @var{stride} specifies the byte stride from one texture coordinate | |
19758 | set to the next, allowing vertices and attributes to be packed into a | |
19759 | single array or stored in separate arrays. (Single-array storage may be | |
19760 | more efficient on some implementations; see @code{glInterleavedArrays}.) | |
8925f36f AW |
19761 | |
19762 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
19763 | target (see @code{glBindBuffer}) while a texture coordinate array is | |
19764 | specified, @var{pointer} is treated as a byte offset into the buffer | |
f37e7e3d | 19765 | object's data store. Also, the buffer object binding |
8925f36f AW |
19766 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as texture coordinate vertex |
19767 | array client-side state (@code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING}). | |
19768 | ||
19769 | When a texture coordinate array is specified, @var{size}, @var{type}, | |
19770 | @var{stride}, and @var{pointer} are saved as client-side state, in | |
19771 | addition to the current vertex array buffer object binding. | |
19772 | ||
19773 | To enable and disable a texture coordinate array, call | |
19774 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
f37e7e3d | 19775 | argument @code{GL_TEXTURE_COORD_ARRAY}. If enabled, the texture |
8925f36f AW |
19776 | coordinate array is used when @code{glArrayElement}, |
19777 | @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements}, | |
19778 | @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called. | |
19779 | ||
8925f36f AW |
19780 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4. |
19781 | ||
19782 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
19783 | value. | |
19784 | ||
19785 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
19786 | ||
bb894c9d | 19787 | @end deftypefun |
8925f36f | 19788 | |
d172eed9 AW |
19789 | @deftypefun void glTexCoord1s s |
19790 | @deftypefunx void glTexCoord1i s | |
ca09631c | 19791 | @deftypefunx void glTexCoord1f s |
d172eed9 AW |
19792 | @deftypefunx void glTexCoord1d s |
19793 | @deftypefunx void glTexCoord2s s t | |
bb894c9d | 19794 | @deftypefunx void glTexCoord2i s t |
ca09631c | 19795 | @deftypefunx void glTexCoord2f s t |
d172eed9 AW |
19796 | @deftypefunx void glTexCoord2d s t |
19797 | @deftypefunx void glTexCoord3s s t r | |
bb894c9d | 19798 | @deftypefunx void glTexCoord3i s t r |
ca09631c | 19799 | @deftypefunx void glTexCoord3f s t r |
d172eed9 AW |
19800 | @deftypefunx void glTexCoord3d s t r |
19801 | @deftypefunx void glTexCoord4s s t r q | |
bb894c9d | 19802 | @deftypefunx void glTexCoord4i s t r q |
ca09631c | 19803 | @deftypefunx void glTexCoord4f s t r q |
d172eed9 AW |
19804 | @deftypefunx void glTexCoord4d s t r q |
19805 | @deftypefunx void glTexCoord1sv v | |
19806 | @deftypefunx void glTexCoord1iv v | |
19807 | @deftypefunx void glTexCoord1fv v | |
19808 | @deftypefunx void glTexCoord1dv v | |
19809 | @deftypefunx void glTexCoord2sv v | |
19810 | @deftypefunx void glTexCoord2iv v | |
19811 | @deftypefunx void glTexCoord2fv v | |
19812 | @deftypefunx void glTexCoord2dv v | |
19813 | @deftypefunx void glTexCoord3sv v | |
19814 | @deftypefunx void glTexCoord3iv v | |
19815 | @deftypefunx void glTexCoord3fv v | |
19816 | @deftypefunx void glTexCoord3dv v | |
19817 | @deftypefunx void glTexCoord4sv v | |
19818 | @deftypefunx void glTexCoord4iv v | |
19819 | @deftypefunx void glTexCoord4fv v | |
19820 | @deftypefunx void glTexCoord4dv v | |
3c9b6116 AW |
19821 | Set the current texture coordinates. |
19822 | ||
8925f36f AW |
19823 | @table @asis |
19824 | @item @var{s} | |
19825 | @itemx @var{t} | |
19826 | @itemx @var{r} | |
19827 | @itemx @var{q} | |
f37e7e3d | 19828 | Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates. Not |
8925f36f AW |
19829 | all parameters are present in all forms of the command. |
19830 | ||
19831 | @end table | |
19832 | ||
8925f36f | 19833 | @code{glTexCoord} specifies texture coordinates in one, two, three, or |
f37e7e3d DH |
19834 | four dimensions. @code{glTexCoord1} sets the current texture coordinates |
19835 | to @r{(@var{s},001)}; a call to @code{glTexCoord2} sets them to | |
19836 | @r{(@var{s},@var{t}01)}. Similarly, @code{glTexCoord3} specifies the | |
3c9b6116 | 19837 | texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and |
8925f36f | 19838 | @code{glTexCoord4} defines all four components explicitly as |
3c9b6116 | 19839 | @r{(@var{s},@var{t}@var{r}@var{q})}. |
8925f36f AW |
19840 | |
19841 | The current texture coordinates are part of the data that is associated | |
f37e7e3d | 19842 | with each vertex and with the current raster position. Initially, the |
8925f36f AW |
19843 | values for @var{s}, @var{t}, @var{r}, and @var{q} are (0, 0, 0, 1). |
19844 | ||
19845 | ||
19846 | ||
bb894c9d | 19847 | @end deftypefun |
8925f36f | 19848 | |
bb894c9d AW |
19849 | @deftypefun void glTexEnvf target pname param |
19850 | @deftypefunx void glTexEnvi target pname param | |
d172eed9 AW |
19851 | @deftypefunx void glTexEnvfv target pname params |
19852 | @deftypefunx void glTexEnviv target pname params | |
3c9b6116 AW |
19853 | Set texture environment parameters. |
19854 | ||
8925f36f AW |
19855 | @table @asis |
19856 | @item @var{target} | |
f37e7e3d | 19857 | Specifies a texture environment. May be @code{GL_TEXTURE_ENV}, |
8925f36f AW |
19858 | @code{GL_TEXTURE_FILTER_CONTROL} or @code{GL_POINT_SPRITE}. |
19859 | ||
19860 | @item @var{pname} | |
19861 | Specifies the symbolic name of a single-valued texture environment | |
f37e7e3d | 19862 | parameter. May be either @code{GL_TEXTURE_ENV_MODE}, |
8925f36f AW |
19863 | @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB}, |
19864 | @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, | |
19865 | @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, | |
19866 | @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB}, | |
19867 | @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA}, | |
19868 | @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE}, | |
19869 | @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}. | |
19870 | ||
19871 | @item @var{param} | |
19872 | Specifies a single symbolic constant, one of @code{GL_ADD}, | |
19873 | @code{GL_ADD_SIGNED}, @code{GL_INTERPOLATE}, @code{GL_MODULATE}, | |
19874 | @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, @code{GL_SUBTRACT}, | |
19875 | @code{GL_COMBINE}, @code{GL_TEXTURE}, @code{GL_CONSTANT}, | |
19876 | @code{GL_PRIMARY_COLOR}, @code{GL_PREVIOUS}, @code{GL_SRC_COLOR}, | |
19877 | @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_SRC_ALPHA}, | |
19878 | @code{GL_ONE_MINUS_SRC_ALPHA}, a single boolean value for the point | |
19879 | sprite texture coordinate replacement, a single floating-point value for | |
19880 | the texture level-of-detail bias, or 1.0, 2.0, or 4.0 when specifying | |
19881 | the @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE}. | |
19882 | ||
19883 | @end table | |
19884 | ||
8925f36f | 19885 | A texture environment specifies how texture values are interpreted when |
f37e7e3d | 19886 | a fragment is textured. When @var{target} is |
8925f36f | 19887 | @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must be |
f37e7e3d | 19888 | @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is @code{GL_TEXTURE_ENV}, |
8925f36f AW |
19889 | @var{pname} can be @code{GL_TEXTURE_ENV_MODE}, |
19890 | @code{GL_TEXTURE_ENV_COLOR}, @code{GL_COMBINE_RGB}, | |
19891 | @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE}, @code{GL_ALPHA_SCALE}, | |
19892 | @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB}, | |
19893 | @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or @code{GL_SRC2_ALPHA}. | |
19894 | ||
19895 | If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, then @var{params} is (or | |
f37e7e3d | 19896 | points to) the symbolic name of a texture function. Six texture |
8925f36f AW |
19897 | functions may be specified: @code{GL_ADD}, @code{GL_MODULATE}, |
19898 | @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, or | |
19899 | @code{GL_COMBINE}. | |
19900 | ||
19901 | The following table shows the correspondence of filtered texture values | |
3c9b6116 AW |
19902 | @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}}, |
19903 | @r{@var{A}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{I}_@var{t}} to texture | |
f37e7e3d | 19904 | source components. @r{@var{C}_@var{s}} and @r{@var{A}_@var{s}} are used |
3c9b6116 | 19905 | by the texture functions described below. |
8925f36f AW |
19906 | |
19907 | ||
19908 | ||
19909 | @table @asis | |
19910 | @item | |
19911 | Texture Base Internal Format | |
3c9b6116 | 19912 | @r{@code{C}_@var{s}}, @r{@code{A}_@var{s}} |
8925f36f AW |
19913 | |
19914 | @item @code{GL_ALPHA} | |
3c9b6116 | 19915 | (0, 0, 0) , @r{@var{A}_@var{t}} |
8925f36f AW |
19916 | |
19917 | @item @code{GL_LUMINANCE} | |
3c9b6116 | 19918 | ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) , 1 |
8925f36f AW |
19919 | |
19920 | @item @code{GL_LUMINANCE_ALPHA} | |
3c9b6116 AW |
19921 | ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) , |
19922 | @r{@var{A}_@var{t}} | |
8925f36f AW |
19923 | |
19924 | @item @code{GL_INTENSITY} | |
3c9b6116 AW |
19925 | ( @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}} ) , |
19926 | @r{@var{I}_@var{t}} | |
8925f36f AW |
19927 | |
19928 | @item @code{GL_RGB} | |
3c9b6116 | 19929 | ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) , 1 |
8925f36f AW |
19930 | |
19931 | @item @code{GL_RGBA} | |
3c9b6116 AW |
19932 | ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) , |
19933 | @r{@var{A}_@var{t}} | |
8925f36f AW |
19934 | |
19935 | @end table | |
19936 | ||
19937 | A texture function acts on the fragment to be textured using the texture | |
19938 | image value that applies to the fragment (see @code{glTexParameter}) and | |
f37e7e3d | 19939 | produces an RGBA color for that fragment. The following table shows how |
8925f36f | 19940 | the RGBA color is produced for each of the first five texture functions |
f37e7e3d DH |
19941 | that can be chosen. @r{@var{C}} is a triple of color values (RGB) and |
19942 | @r{@var{A}} is the associated alpha value. RGBA values extracted from a | |
19943 | texture image are in the range [0,1]. The subscript @r{@var{p}} refers | |
3c9b6116 AW |
19944 | to the color computed from the previous texture stage (or the incoming |
19945 | fragment if processing texture stage 0), the subscript @r{@var{s}} to | |
19946 | the texture source color, the subscript @r{@var{c}} to the texture | |
19947 | environment color, and the subscript @r{@var{v}} indicates a value | |
19948 | produced by the texture function. | |
8925f36f AW |
19949 | |
19950 | ||
19951 | ||
19952 | @table @asis | |
19953 | @item | |
19954 | Texture Base Internal Format | |
19955 | @code{Value}, @code{GL_REPLACE} Function , @code{GL_MODULATE} Function , | |
19956 | @code{GL_DECAL} Function , @code{GL_BLEND} Function , @code{GL_ADD} | |
19957 | Function | |
19958 | ||
19959 | @item @code{GL_ALPHA} | |
3c9b6116 AW |
19960 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}}, |
19961 | undefined , @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}} | |
8925f36f AW |
19962 | |
19963 | @item | |
3c9b6116 AW |
19964 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
19965 | @r{@var{A}_@var{p}@var{A}_@var{s}}, , | |
19966 | @r{@var{A}_@var{v}=@var{A}_@var{p}@var{A}_@var{s}}, | |
19967 | @r{@var{A}_@var{p}@var{A}_@var{s}} | |
8925f36f AW |
19968 | |
19969 | @item @code{GL_LUMINANCE} | |
3c9b6116 AW |
19970 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
19971 | @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined , | |
19972 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
19973 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
19974 | |
19975 | @item | |
19976 | (or 1) | |
3c9b6116 AW |
19977 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, , |
19978 | @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}} | |
8925f36f AW |
19979 | |
19980 | @item @code{GL_LUMINANCE_ALPHA} | |
3c9b6116 AW |
19981 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
19982 | @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined , | |
19983 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
19984 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
19985 | |
19986 | @item | |
19987 | (or 2) | |
3c9b6116 AW |
19988 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
19989 | @r{@var{A}_@var{p}@var{A}_@var{s}}, , | |
19990 | @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}} | |
8925f36f AW |
19991 | |
19992 | @item @code{GL_INTENSITY} | |
3c9b6116 AW |
19993 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
19994 | @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined , | |
19995 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
19996 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
19997 | |
19998 | @item | |
3c9b6116 AW |
19999 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
20000 | @r{@var{A}_@var{p}@var{A}_@var{s}}, , | |
20001 | @r{@var{A}_@var{p}(1-@var{A}_@var{s},)+@var{A}_@var{c}@var{A}_@var{s}}, | |
20002 | @r{@var{A}_@var{p}+@var{A}_@var{s}} | |
8925f36f AW |
20003 | |
20004 | @item @code{GL_RGB} | |
3c9b6116 AW |
20005 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
20006 | @r{@var{C}_@var{p}@var{C}_@var{s}}, @r{@var{C}_@var{s}}, | |
20007 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
20008 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
20009 | |
20010 | @item | |
20011 | (or 3) | |
3c9b6116 AW |
20012 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, |
20013 | @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}} | |
8925f36f AW |
20014 | |
20015 | @item @code{GL_RGBA} | |
3c9b6116 AW |
20016 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
20017 | @r{@var{C}_@var{p}@var{C}_@var{s}}, | |
20018 | @r{@var{C}_@var{p}(1-@var{A}_@var{s},)+@var{C}_@var{s}@var{A}_@var{s}}, | |
20019 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
20020 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
20021 | |
20022 | @item | |
20023 | (or 4) | |
3c9b6116 AW |
20024 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
20025 | @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}}, | |
20026 | @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}} | |
8925f36f AW |
20027 | |
20028 | @end table | |
20029 | ||
20030 | If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, and @var{params} is | |
20031 | @code{GL_COMBINE}, the form of the texture function depends on the | |
20032 | values of @code{GL_COMBINE_RGB} and @code{GL_COMBINE_ALPHA}. | |
20033 | ||
20034 | The following describes how the texture sources, as specified by | |
20035 | @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB}, | |
20036 | @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, and @code{GL_SRC2_ALPHA}, | |
f37e7e3d | 20037 | are combined to produce a final texture color. In the following tables, |
3c9b6116 AW |
20038 | @code{GL_SRC0_c} is represented by @r{@var{Arg0}}, @code{GL_SRC1_c} is |
20039 | represented by @r{@var{Arg1}}, and @code{GL_SRC2_c} is represented by | |
20040 | @r{@var{Arg2}}. | |
8925f36f AW |
20041 | |
20042 | @code{GL_COMBINE_RGB} accepts any of @code{GL_REPLACE}, | |
20043 | @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED}, | |
20044 | @code{GL_INTERPOLATE}, @code{GL_SUBTRACT}, @code{GL_DOT3_RGB}, or | |
20045 | @code{GL_DOT3_RGBA}. | |
20046 | ||
20047 | ||
20048 | ||
20049 | @table @asis | |
20050 | @item @strong{@code{GL_COMBINE_RGB}} | |
20051 | @strong{Texture Function} | |
20052 | ||
20053 | @item @code{GL_REPLACE} | |
3c9b6116 | 20054 | @r{@var{Arg0}} |
8925f36f AW |
20055 | |
20056 | @item @code{GL_MODULATE} | |
3c9b6116 | 20057 | @r{@var{Arg0}×@var{Arg1}} |
8925f36f AW |
20058 | |
20059 | @item @code{GL_ADD} | |
3c9b6116 | 20060 | @r{@var{Arg0}+@var{Arg1}} |
8925f36f AW |
20061 | |
20062 | @item @code{GL_ADD_SIGNED} | |
3c9b6116 | 20063 | @r{@var{Arg0}+@var{Arg1}-0.5} |
8925f36f AW |
20064 | |
20065 | @item @code{GL_INTERPOLATE} | |
3c9b6116 | 20066 | @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)} |
8925f36f AW |
20067 | |
20068 | @item @code{GL_SUBTRACT} | |
3c9b6116 | 20069 | @r{@var{Arg0}-@var{Arg1}} |
8925f36f AW |
20070 | |
20071 | @item @code{GL_DOT3_RGB} | |
20072 | or @code{GL_DOT3_RGBA} | |
3c9b6116 | 20073 | @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 |
20074 | |
20075 | @end table | |
20076 | ||
20077 | The scalar results for @code{GL_DOT3_RGB} and @code{GL_DOT3_RGBA} are | |
20078 | placed into each of the 3 (RGB) or 4 (RGBA) components on output. | |
20079 | ||
20080 | Likewise, @code{GL_COMBINE_ALPHA} accepts any of @code{GL_REPLACE}, | |
20081 | @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED}, | |
f37e7e3d | 20082 | @code{GL_INTERPOLATE}, or @code{GL_SUBTRACT}. The following table |
8925f36f AW |
20083 | describes how alpha values are combined: |
20084 | ||
20085 | ||
20086 | ||
20087 | @table @asis | |
20088 | @item @strong{@code{GL_COMBINE_ALPHA}} | |
20089 | @strong{Texture Function} | |
20090 | ||
20091 | @item @code{GL_REPLACE} | |
3c9b6116 | 20092 | @r{@var{Arg0}} |
8925f36f AW |
20093 | |
20094 | @item @code{GL_MODULATE} | |
3c9b6116 | 20095 | @r{@var{Arg0}×@var{Arg1}} |
8925f36f AW |
20096 | |
20097 | @item @code{GL_ADD} | |
3c9b6116 | 20098 | @r{@var{Arg0}+@var{Arg1}} |
8925f36f AW |
20099 | |
20100 | @item @code{GL_ADD_SIGNED} | |
3c9b6116 | 20101 | @r{@var{Arg0}+@var{Arg1}-0.5} |
8925f36f AW |
20102 | |
20103 | @item @code{GL_INTERPOLATE} | |
3c9b6116 | 20104 | @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)} |
8925f36f AW |
20105 | |
20106 | @item @code{GL_SUBTRACT} | |
3c9b6116 | 20107 | @r{@var{Arg0}-@var{Arg1}} |
8925f36f AW |
20108 | |
20109 | @end table | |
20110 | ||
3c9b6116 AW |
20111 | In the following tables, the value @r{@var{C}_@var{s}} represents the |
20112 | color sampled from the currently bound texture, @r{@var{C}_@var{c}} | |
20113 | represents the constant texture-environment color, @r{@var{C}_@var{f}} | |
20114 | represents the primary color of the incoming fragment, and | |
20115 | @r{@var{C}_@var{p}} represents the color computed from the previous | |
20116 | texture stage or @r{@var{C}_@var{f}} if processing texture stage 0. | |
20117 | Likewise, @r{@var{A}_@var{s}}, @r{@var{A}_@var{c}}, @r{@var{A}_@var{f}}, | |
20118 | and @r{@var{A}_@var{p}} represent the respective alpha values. | |
8925f36f | 20119 | |
3c9b6116 AW |
20120 | The following table describes the values assigned to @r{@var{Arg0}}, |
20121 | @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the RGB sources and | |
8925f36f AW |
20122 | operands: |
20123 | ||
20124 | ||
20125 | ||
20126 | @table @asis | |
20127 | @item @strong{@code{GL_SRCn_RGB}} | |
20128 | @strong{@code{GL_OPERANDn_RGB}}, @strong{Argument Value} | |
20129 | ||
20130 | @item @code{GL_TEXTURE} | |
3c9b6116 | 20131 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},} |
8925f36f AW |
20132 | |
20133 | @item | |
3c9b6116 | 20134 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},} |
8925f36f AW |
20135 | |
20136 | @item | |
3c9b6116 | 20137 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
20138 | |
20139 | @item | |
3c9b6116 | 20140 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
20141 | |
20142 | @item @code{GL_TEXTUREn} | |
3c9b6116 | 20143 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},} |
8925f36f AW |
20144 | |
20145 | @item | |
3c9b6116 | 20146 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},} |
8925f36f AW |
20147 | |
20148 | @item | |
3c9b6116 | 20149 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
20150 | |
20151 | @item | |
3c9b6116 | 20152 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
20153 | |
20154 | @item @code{GL_CONSTANT} | |
3c9b6116 | 20155 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{c},} |
8925f36f AW |
20156 | |
20157 | @item | |
3c9b6116 | 20158 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{c},} |
8925f36f AW |
20159 | |
20160 | @item | |
3c9b6116 | 20161 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},} |
8925f36f AW |
20162 | |
20163 | @item | |
3c9b6116 | 20164 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},} |
8925f36f AW |
20165 | |
20166 | @item @code{GL_PRIMARY_COLOR} | |
3c9b6116 | 20167 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{f},} |
8925f36f AW |
20168 | |
20169 | @item | |
3c9b6116 | 20170 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{f},} |
8925f36f AW |
20171 | |
20172 | @item | |
3c9b6116 | 20173 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},} |
8925f36f AW |
20174 | |
20175 | @item | |
3c9b6116 | 20176 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},} |
8925f36f AW |
20177 | |
20178 | @item @code{GL_PREVIOUS} | |
3c9b6116 | 20179 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{p},} |
8925f36f AW |
20180 | |
20181 | @item | |
3c9b6116 | 20182 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{p},} |
8925f36f AW |
20183 | |
20184 | @item | |
3c9b6116 | 20185 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},} |
8925f36f AW |
20186 | |
20187 | @item | |
3c9b6116 | 20188 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},} |
8925f36f AW |
20189 | |
20190 | @end table | |
20191 | ||
3c9b6116 AW |
20192 | For @code{GL_TEXTUREn} sources, @r{@var{C}_@var{s}} and |
20193 | @r{@var{A}_@var{s}} represent the color and alpha, respectively, | |
20194 | produced from texture stage @r{@var{n}}. | |
8925f36f | 20195 | |
3c9b6116 AW |
20196 | The follow table describes the values assigned to @r{@var{Arg0}}, |
20197 | @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the alpha sources and | |
20198 | operands: | |
8925f36f AW |
20199 | |
20200 | ||
20201 | ||
20202 | @table @asis | |
20203 | @item @strong{@code{GL_SRCn_ALPHA}} | |
20204 | @strong{@code{GL_OPERANDn_ALPHA}}, @strong{Argument Value} | |
20205 | ||
20206 | @item @code{GL_TEXTURE} | |
3c9b6116 | 20207 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
20208 | |
20209 | @item | |
3c9b6116 | 20210 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
20211 | |
20212 | @item @code{GL_TEXTUREn} | |
3c9b6116 | 20213 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
20214 | |
20215 | @item | |
3c9b6116 | 20216 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
20217 | |
20218 | @item @code{GL_CONSTANT} | |
3c9b6116 | 20219 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},} |
8925f36f AW |
20220 | |
20221 | @item | |
3c9b6116 | 20222 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},} |
8925f36f AW |
20223 | |
20224 | @item @code{GL_PRIMARY_COLOR} | |
3c9b6116 | 20225 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},} |
8925f36f AW |
20226 | |
20227 | @item | |
3c9b6116 | 20228 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},} |
8925f36f AW |
20229 | |
20230 | @item @code{GL_PREVIOUS} | |
3c9b6116 | 20231 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},} |
8925f36f AW |
20232 | |
20233 | @item | |
3c9b6116 | 20234 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},} |
8925f36f AW |
20235 | |
20236 | @end table | |
20237 | ||
20238 | The RGB and alpha results of the texture function are multipled by the | |
20239 | values of @code{GL_RGB_SCALE} and @code{GL_ALPHA_SCALE}, respectively, | |
3c9b6116 | 20240 | and clamped to the range @r{[0,1]}. |
8925f36f AW |
20241 | |
20242 | If @var{pname} is @code{GL_TEXTURE_ENV_COLOR}, @var{params} is a pointer | |
f37e7e3d | 20243 | to an array that holds an RGBA color consisting of four values. Integer |
8925f36f | 20244 | color components are interpreted linearly such that the most positive |
f37e7e3d | 20245 | integer maps to 1.0, and the most negative integer maps to -1.0. The |
8925f36f | 20246 | values are clamped to the range [0,1] when they are specified. |
3c9b6116 | 20247 | @r{@var{C}_@var{c}} takes these four values. |
8925f36f AW |
20248 | |
20249 | If @var{pname} is @code{GL_TEXTURE_LOD_BIAS}, the value specified is | |
20250 | added to the texture level-of-detail parameter, that selects which | |
20251 | mipmap, or mipmaps depending upon the selected | |
20252 | @code{GL_TEXTURE_MIN_FILTER}, will be sampled. | |
20253 | ||
20254 | @code{GL_TEXTURE_ENV_MODE} defaults to @code{GL_MODULATE} and | |
20255 | @code{GL_TEXTURE_ENV_COLOR} defaults to (0, 0, 0, 0). | |
20256 | ||
20257 | If @var{target} is @code{GL_POINT_SPRITE} and @var{pname} is | |
20258 | @code{GL_COORD_REPLACE}, the boolean value specified is used to either | |
f37e7e3d | 20259 | enable or disable point sprite texture coordinate replacement. The |
8925f36f AW |
20260 | default value is @code{GL_FALSE}. |
20261 | ||
8925f36f AW |
20262 | @code{GL_INVALID_ENUM} is generated when @var{target} or @var{pname} is |
20263 | not one of the accepted defined values, or when @var{params} should have | |
20264 | a defined constant value (based on the value of @var{pname}) and does | |
20265 | not. | |
20266 | ||
20267 | @code{GL_INVALID_VALUE} is generated if the @var{params} value for | |
20268 | @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE} are not one of 1.0, 2.0, or | |
20269 | 4.0. | |
20270 | ||
20271 | @code{GL_INVALID_OPERATION} is generated if @code{glTexEnv} is executed | |
20272 | between the execution of @code{glBegin} and the corresponding execution | |
20273 | of @code{glEnd}. | |
20274 | ||
bb894c9d | 20275 | @end deftypefun |
8925f36f | 20276 | |
bb894c9d | 20277 | @deftypefun void glTexGeni coord pname param |
ca09631c | 20278 | @deftypefunx void glTexGenf coord pname param |
d172eed9 AW |
20279 | @deftypefunx void glTexGend coord pname param |
20280 | @deftypefunx void glTexGeniv coord pname params | |
20281 | @deftypefunx void glTexGenfv coord pname params | |
20282 | @deftypefunx void glTexGendv coord pname params | |
3c9b6116 AW |
20283 | Control the generation of texture coordinates. |
20284 | ||
8925f36f AW |
20285 | @table @asis |
20286 | @item @var{coord} | |
f37e7e3d DH |
20287 | Specifies a texture coordinate. Must be one of @code{GL_S}, @code{GL_T}, |
20288 | @code{GL_R}, or @code{GL_Q}. | |
8925f36f AW |
20289 | |
20290 | @item @var{pname} | |
20291 | Specifies the symbolic name of the texture-coordinate generation | |
f37e7e3d | 20292 | function. Must be @code{GL_TEXTURE_GEN_MODE}. |
8925f36f AW |
20293 | |
20294 | @item @var{param} | |
20295 | Specifies a single-valued texture generation parameter, one of | |
20296 | @code{GL_OBJECT_LINEAR}, @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP}, | |
20297 | @code{GL_NORMAL_MAP}, or @code{GL_REFLECTION_MAP}. | |
20298 | ||
20299 | @end table | |
20300 | ||
8925f36f | 20301 | @code{glTexGen} selects a texture-coordinate generation function or |
f37e7e3d DH |
20302 | supplies coefficients for one of the functions. @var{coord} names one of |
20303 | the (@var{s}, @var{t}, @var{r}, @var{q}) texture coordinates; it must be | |
20304 | one of the symbols @code{GL_S}, @code{GL_T}, @code{GL_R}, or | |
20305 | @code{GL_Q}. @var{pname} must be one of three symbolic constants: | |
8925f36f | 20306 | @code{GL_TEXTURE_GEN_MODE}, @code{GL_OBJECT_PLANE}, or |
f37e7e3d | 20307 | @code{GL_EYE_PLANE}. If @var{pname} is @code{GL_TEXTURE_GEN_MODE}, then |
8925f36f AW |
20308 | @var{params} chooses a mode, one of @code{GL_OBJECT_LINEAR}, |
20309 | @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP}, @code{GL_NORMAL_MAP}, or | |
f37e7e3d | 20310 | @code{GL_REFLECTION_MAP}. If @var{pname} is either |
8925f36f AW |
20311 | @code{GL_OBJECT_PLANE} or @code{GL_EYE_PLANE}, @var{params} contains |
20312 | coefficients for the corresponding texture generation function. | |
20313 | ||
20314 | If the texture generation function is @code{GL_OBJECT_LINEAR}, the | |
20315 | function | |
20316 | ||
3c9b6116 AW |
20317 | @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}} |
20318 | ||
20319 | is used, where @r{@var{g}} is the value computed for the coordinate | |
20320 | named in @var{coord}, @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and | |
20321 | @r{@var{p}_4} are the four values supplied in @var{params}, and | |
20322 | @r{@var{x}_@var{o}}, @r{@var{y}_@var{o}}, @r{@var{z}_@var{o}}, and | |
f37e7e3d | 20323 | @r{@var{w}_@var{o}} are the object coordinates of the vertex. This |
3c9b6116 AW |
20324 | function can be used, for example, to texture-map terrain using sea |
20325 | level as a reference plane (defined by @r{@var{p}_1}, @r{@var{p}_2}, | |
f37e7e3d | 20326 | @r{@var{p}_3}, and @r{@var{p}_4}). The altitude of a terrain vertex is |
3c9b6116 AW |
20327 | computed by the @code{GL_OBJECT_LINEAR} coordinate generation function |
20328 | as its distance from sea level; that altitude can then be used to index | |
20329 | the texture image to map white snow onto peaks and green grass onto | |
20330 | foothills. | |
8925f36f AW |
20331 | |
20332 | If the texture generation function is @code{GL_EYE_LINEAR}, the function | |
20333 | ||
3c9b6116 | 20334 | @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 |
20335 | |
20336 | is used, where | |
20337 | ||
3c9b6116 | 20338 | @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 | 20339 | |
3c9b6116 AW |
20340 | and @r{@var{x}_@var{e}}, @r{@var{y}_@var{e}}, @r{@var{z}_@var{e}}, and |
20341 | @r{@var{w}_@var{e}} are the eye coordinates of the vertex, | |
20342 | @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and @r{@var{p}_4} are the | |
20343 | values supplied in @var{params}, and @r{@var{M}} is the modelview matrix | |
f37e7e3d DH |
20344 | when @code{glTexGen} is invoked. If @r{@var{M}} is poorly conditioned or |
20345 | singular, texture coordinates generated by the resulting function may be | |
20346 | inaccurate or undefined. | |
8925f36f AW |
20347 | |
20348 | Note that the values in @var{params} define a reference plane in eye | |
f37e7e3d DH |
20349 | coordinates. The modelview matrix that is applied to them may not be the |
20350 | same one in effect when the polygon vertices are transformed. This | |
8925f36f AW |
20351 | function establishes a field of texture coordinates that can produce |
20352 | dynamic contour lines on moving objects. | |
20353 | ||
20354 | If the texture generation function is @code{GL_SPHERE_MAP} and | |
3c9b6116 | 20355 | @var{coord} is either @code{GL_S} or @code{GL_T}, @r{@var{s}} and |
f37e7e3d DH |
20356 | @r{@var{t}} texture coordinates are generated as follows. Let @var{u} be |
20357 | the unit vector pointing from the origin to the polygon vertex (in eye | |
20358 | coordinates). Let @var{n} sup prime be the current normal, after | |
20359 | transformation to eye coordinates. Let | |
8925f36f | 20360 | |
3c9b6116 | 20361 | @r{@var{f}=(@var{f}_@var{x}@var{f}_@var{y}@var{f}_@var{z},)^@var{T}} |
8925f36f AW |
20362 | be the reflection vector such that |
20363 | ||
3c9b6116 | 20364 | @r{@var{f}=@var{u}-2@var{n}^″@var{n}^″,^@var{T}@var{u}} |
8925f36f AW |
20365 | |
20366 | Finally, let | |
3c9b6116 AW |
20367 | @r{@var{m}=2√(@var{f}_@var{x},^2+@var{f}_@var{y},^2+(@var{f}_@var{z}+1,)^2,)}. |
20368 | Then the values assigned to the @r{@var{s}} and @r{@var{t}} texture | |
20369 | coordinates are | |
8925f36f | 20370 | |
3c9b6116 | 20371 | @r{@var{s}=@var{f}_@var{x}/@var{m}+1/2} |
8925f36f | 20372 | |
3c9b6116 | 20373 | @r{@var{t}=@var{f}_@var{y}/@var{m}+1/2} |
8925f36f AW |
20374 | |
20375 | To enable or disable a texture-coordinate generation function, call | |
20376 | @code{glEnable} or @code{glDisable} with one of the symbolic | |
20377 | texture-coordinate names (@code{GL_TEXTURE_GEN_S}, | |
20378 | @code{GL_TEXTURE_GEN_T}, @code{GL_TEXTURE_GEN_R}, or | |
f37e7e3d | 20379 | @code{GL_TEXTURE_GEN_Q}) as the argument. When enabled, the specified |
8925f36f | 20380 | texture coordinate is computed according to the generating function |
f37e7e3d DH |
20381 | associated with that coordinate. When disabled, subsequent vertices take |
20382 | the specified texture coordinate from the current set of texture | |
20383 | coordinates. Initially, all texture generation functions are set to | |
20384 | @code{GL_EYE_LINEAR} and are disabled. Both @r{@var{s}} plane equations | |
3c9b6116 AW |
20385 | are (1, 0, 0, 0), both @r{@var{t}} plane equations are (0, 1, 0, 0), and |
20386 | all @r{@var{r}} and @r{@var{q}} plane equations are (0, 0, 0, 0). | |
8925f36f AW |
20387 | |
20388 | When the @code{ARB_multitexture} extension is supported, @code{glTexGen} | |
20389 | sets the texture generation parameters for the currently active texture | |
20390 | unit, selected with @code{glActiveTexture}. | |
20391 | ||
8925f36f AW |
20392 | @code{GL_INVALID_ENUM} is generated when @var{coord} or @var{pname} is |
20393 | not an accepted defined value, or when @var{pname} is | |
20394 | @code{GL_TEXTURE_GEN_MODE} and @var{params} is not an accepted defined | |
20395 | value. | |
20396 | ||
20397 | @code{GL_INVALID_ENUM} is generated when @var{pname} is | |
20398 | @code{GL_TEXTURE_GEN_MODE}, @var{params} is @code{GL_SPHERE_MAP}, and | |
20399 | @var{coord} is either @code{GL_R} or @code{GL_Q}. | |
20400 | ||
20401 | @code{GL_INVALID_OPERATION} is generated if @code{glTexGen} is executed | |
20402 | between the execution of @code{glBegin} and the corresponding execution | |
20403 | of @code{glEnd}. | |
20404 | ||
bb894c9d | 20405 | @end deftypefun |
8925f36f | 20406 | |
bb894c9d | 20407 | @deftypefun void glTexImage1D target level internalFormat width border format type data |
3c9b6116 AW |
20408 | Specify a one-dimensional texture image. |
20409 | ||
8925f36f AW |
20410 | @table @asis |
20411 | @item @var{target} | |
f37e7e3d | 20412 | Specifies the target texture. Must be @code{GL_TEXTURE_1D} or |
8925f36f AW |
20413 | @code{GL_PROXY_TEXTURE_1D}. |
20414 | ||
20415 | @item @var{level} | |
f37e7e3d | 20416 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
20417 | Level @var{n} is the @var{n}th mipmap reduction image. |
20418 | ||
20419 | @item @var{internalFormat} | |
f37e7e3d | 20420 | Specifies the number of color components in the texture. Must be 1, 2, |
8925f36f AW |
20421 | 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA}, |
20422 | @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
20423 | @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA}, | |
20424 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
20425 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
20426 | @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT}, | |
20427 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, | |
20428 | @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
20429 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
20430 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
20431 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
20432 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
20433 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
20434 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
20435 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
20436 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
20437 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
20438 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
20439 | @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE}, | |
20440 | @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
20441 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
20442 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
20443 | ||
20444 | @item @var{width} | |
f37e7e3d | 20445 | Specifies the width of the texture image including the border if any. If |
8925f36f | 20446 | the GL version does not support non-power-of-two sizes, this value must |
f37e7e3d | 20447 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 AW |
20448 | implementations support texture images that are at least 64 texels wide. |
20449 | The height of the 1D texture image is 1. | |
8925f36f AW |
20450 | |
20451 | @item @var{border} | |
f37e7e3d | 20452 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
20453 | |
20454 | @item @var{format} | |
f37e7e3d | 20455 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
20456 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, |
20457 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
20458 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
20459 | @code{GL_LUMINANCE_ALPHA}. | |
20460 | ||
20461 | @item @var{type} | |
f37e7e3d DH |
20462 | Specifies the data type of the pixel data. The following symbolic values |
20463 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
20464 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
20465 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
20466 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
20467 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
20468 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
20469 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
20470 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
20471 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f AW |
20472 | |
20473 | @item @var{data} | |
20474 | Specifies a pointer to the image data in memory. | |
20475 | ||
20476 | @end table | |
20477 | ||
8925f36f | 20478 | Texturing maps a portion of a specified texture image onto each |
f37e7e3d | 20479 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
20480 | disable one-dimensional texturing, call @code{glEnable} and |
20481 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
20482 | ||
f37e7e3d | 20483 | Texture images are defined with @code{glTexImage1D}. The arguments |
8925f36f AW |
20484 | describe the parameters of the texture image, such as width, width of |
20485 | the border, level-of-detail number (see @code{glTexParameter}), and the | |
f37e7e3d | 20486 | internal resolution and format used to store the image. The last three |
8925f36f AW |
20487 | arguments describe how the image is represented in memory; they are |
20488 | identical to the pixel formats used for @code{glDrawPixels}. | |
20489 | ||
20490 | If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from | |
20491 | @var{data}, but all of the texture image state is recalculated, checked | |
20492 | for consistency, and checked against the implementation's capabilities. | |
20493 | If the implementation cannot handle a texture of the requested texture | |
20494 | size, it sets all of the image state to 0, but does not generate an | |
f37e7e3d | 20495 | error (see @code{glGetError}). To query for an entire mipmap array, use |
8925f36f AW |
20496 | an image array level greater than or equal to 1. |
20497 | ||
20498 | If @var{target} is @code{GL_TEXTURE_1D}, data is read from @var{data} as | |
20499 | a sequence of signed or unsigned bytes, shorts, or longs, or | |
f37e7e3d | 20500 | single-precision floating-point values, depending on @var{type}. These |
8925f36f | 20501 | values are grouped into sets of one, two, three, or four values, |
f37e7e3d | 20502 | depending on @var{format}, to form elements. If @var{type} is |
8925f36f | 20503 | @code{GL_BITMAP}, the data is considered as a string of unsigned bytes |
f37e7e3d | 20504 | (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is |
8925f36f AW |
20505 | treated as eight 1-bit elements, with bit ordering determined by |
20506 | @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}). | |
20507 | ||
20508 | If a non-zero named buffer object is bound to the | |
20509 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
20510 | texture image is specified, @var{data} is treated as a byte offset into | |
20511 | the buffer object's data store. | |
20512 | ||
20513 | The first element corresponds to the left end of the texture array. | |
20514 | Subsequent elements progress left-to-right through the remaining texels | |
f37e7e3d | 20515 | in the texture array. The final element corresponds to the right end of |
8925f36f AW |
20516 | the texture array. |
20517 | ||
20518 | @var{format} determines the composition of each element in @var{data}. | |
20519 | It can assume one of these symbolic values: | |
20520 | ||
20521 | @table @asis | |
20522 | @item @code{GL_COLOR_INDEX} | |
f37e7e3d | 20523 | Each element is a single value, a color index. The GL converts it to |
8925f36f AW |
20524 | fixed point (with an unspecified number of zero bits to the right of the |
20525 | binary point), shifted left or right depending on the value and sign of | |
20526 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see | |
f37e7e3d | 20527 | @code{glPixelTransfer}). The resulting index is converted to a set of |
8925f36f AW |
20528 | color components using the @code{GL_PIXEL_MAP_I_TO_R}, |
20529 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
20530 | @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1]. | |
20531 | ||
20532 | @item @code{GL_RED} | |
f37e7e3d | 20533 | Each element is a single red component. The GL converts it to floating |
8925f36f | 20534 | point and assembles it into an RGBA element by attaching 0 for green and |
f37e7e3d | 20535 | blue, and 1 for alpha. Each component is then multiplied by the signed |
8925f36f AW |
20536 | scale factor @code{GL_c_SCALE}, added to the signed bias |
20537 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20538 | @code{glPixelTransfer}). | |
20539 | ||
20540 | @item @code{GL_GREEN} | |
f37e7e3d DH |
20541 | Each element is a single green component. The GL converts it to floating |
20542 | point and assembles it into an RGBA element by attaching 0 for red and | |
20543 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
20544 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
8925f36f AW |
20545 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see |
20546 | @code{glPixelTransfer}). | |
20547 | ||
20548 | @item @code{GL_BLUE} | |
f37e7e3d | 20549 | Each element is a single blue component. The GL converts it to floating |
8925f36f | 20550 | point and assembles it into an RGBA element by attaching 0 for red and |
f37e7e3d | 20551 | green, and 1 for alpha. Each component is then multiplied by the signed |
8925f36f AW |
20552 | scale factor @code{GL_c_SCALE}, added to the signed bias |
20553 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20554 | @code{glPixelTransfer}). | |
20555 | ||
20556 | @item @code{GL_ALPHA} | |
f37e7e3d DH |
20557 | Each element is a single alpha component. The GL converts it to floating |
20558 | point and assembles it into an RGBA element by attaching 0 for red, | |
20559 | green, and blue. Each component is then multiplied by the signed scale | |
20560 | factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20561 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
8925f36f AW |
20562 | |
20563 | @item @code{GL_INTENSITY} | |
f37e7e3d DH |
20564 | Each element is a single intensity value. The GL converts it to floating |
20565 | point, then assembles it into an RGBA element by replicating the | |
20566 | intensity value three times for red, green, blue, and alpha. Each | |
8925f36f AW |
20567 | component is then multiplied by the signed scale factor |
20568 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20569 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20570 | ||
20571 | @item @code{GL_RGB} | |
20572 | @item @code{GL_BGR} | |
f37e7e3d DH |
20573 | Each element is an RGB triple. The GL converts it to floating point and |
20574 | assembles it into an RGBA element by attaching 1 for alpha. Each | |
8925f36f AW |
20575 | component is then multiplied by the signed scale factor |
20576 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20577 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20578 | ||
20579 | @item @code{GL_RGBA} | |
20580 | @item @code{GL_BGRA} | |
f37e7e3d | 20581 | Each element contains all four components. Each component is multiplied |
8925f36f AW |
20582 | by the signed scale factor @code{GL_c_SCALE}, added to the signed bias |
20583 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20584 | @code{glPixelTransfer}). | |
20585 | ||
20586 | @item @code{GL_LUMINANCE} | |
f37e7e3d DH |
20587 | Each element is a single luminance value. The GL converts it to floating |
20588 | point, then assembles it into an RGBA element by replicating the | |
20589 | luminance value three times for red, green, and blue and attaching 1 for | |
20590 | alpha. Each component is then multiplied by the signed scale factor | |
8925f36f AW |
20591 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and |
20592 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20593 | ||
20594 | @item @code{GL_LUMINANCE_ALPHA} | |
f37e7e3d | 20595 | Each element is a luminance/alpha pair. The GL converts it to floating |
8925f36f | 20596 | point, then assembles it into an RGBA element by replicating the |
f37e7e3d | 20597 | luminance value three times for red, green, and blue. Each component is |
8925f36f AW |
20598 | then multiplied by the signed scale factor @code{GL_c_SCALE}, added to |
20599 | the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20600 | @code{glPixelTransfer}). | |
20601 | ||
20602 | @item @code{GL_DEPTH_COMPONENT} | |
f37e7e3d | 20603 | Each element is a single depth value. The GL converts it to floating |
8925f36f AW |
20604 | point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds |
20605 | the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see | |
20606 | @code{glPixelTransfer}). | |
20607 | ||
20608 | @end table | |
20609 | ||
20610 | Refer to the @code{glDrawPixels} reference page for a description of the | |
20611 | acceptable values for the @var{type} parameter. | |
20612 | ||
20613 | If an application wants to store the texture at a certain resolution or | |
20614 | in a certain format, it can request the resolution and format with | |
f37e7e3d DH |
20615 | @var{internalFormat}. The GL will choose an internal representation that |
20616 | closely approximates that requested by @var{internalFormat}, but it may | |
20617 | not match exactly. (The representations specified by | |
8925f36f | 20618 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and |
f37e7e3d DH |
20619 | @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may |
20620 | also be used to specify the above representations.) | |
8925f36f AW |
20621 | |
20622 | If the @var{internalFormat} parameter is one of the generic compressed | |
20623 | formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
20624 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
20625 | @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will | |
20626 | replace the internal format with the symbolic constant for a specific | |
f37e7e3d | 20627 | internal format and compress the texture before storage. If no |
8925f36f AW |
20628 | corresponding internal format is available, or the GL can not compress |
20629 | that image for any reason, the internal format is instead replaced with | |
20630 | a corresponding base internal format. | |
20631 | ||
20632 | If the @var{internalFormat} parameter is @code{GL_SRGB}, | |
20633 | @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8}, | |
20634 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
20635 | or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red, | |
20636 | green, blue, or luminance components are encoded in the sRGB color | |
f37e7e3d | 20637 | space. Any alpha component is left unchanged. The conversion from the |
3c9b6116 AW |
20638 | sRGB encoded component @r{@var{c}_@var{s}} to a linear component |
20639 | @r{@var{c}_@var{l}} is: | |
8925f36f | 20640 | |
3c9b6116 AW |
20641 | @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045), |
20642 | ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)} | |
8925f36f | 20643 | |
3c9b6116 | 20644 | Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1]. |
8925f36f AW |
20645 | |
20646 | Use the @code{GL_PROXY_TEXTURE_1D} target to try out a resolution and | |
f37e7e3d DH |
20647 | format. The implementation will update and recompute its best match for |
20648 | the requested storage resolution and format. To then query this state, | |
20649 | call @code{glGetTexLevelParameter}. If the texture cannot be | |
8925f36f AW |
20650 | accommodated, texture state is set to 0. |
20651 | ||
20652 | A one-component texture image uses only the red component of the RGBA | |
f37e7e3d DH |
20653 | color from @var{data}. A two-component image uses the R and A values. A |
20654 | three-component image uses the R, G, and B values. A four-component | |
8925f36f AW |
20655 | image uses all of the RGBA components. |
20656 | ||
20657 | Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures | |
f37e7e3d | 20658 | during texture filtering and application. Image-based shadowing can be |
8925f36f | 20659 | enabled by comparing texture r coordinates to depth texture values to |
f37e7e3d | 20660 | generate a boolean result. See @code{glTexParameter} for details on |
8925f36f AW |
20661 | texture comparison. |
20662 | ||
8925f36f AW |
20663 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
20664 | @code{GL_TEXTURE_1D} or @code{GL_PROXY_TEXTURE_1D}. | |
20665 | ||
20666 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
f37e7e3d DH |
20667 | format constant. Format constants other than @code{GL_STENCIL_INDEX} are |
20668 | accepted. | |
8925f36f AW |
20669 | |
20670 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
20671 | constant. | |
20672 | ||
20673 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
20674 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
20675 | ||
20676 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
20677 | ||
20678 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
20679 | @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of |
20680 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
20681 | |
20682 | @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1, | |
20683 | 2, 3, 4, or one of the accepted resolution and format symbolic | |
20684 | constants. | |
20685 | ||
20686 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or | |
20687 | greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
20688 | ||
20689 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
20690 | not supported and the @var{width} cannot be represented as | |
3c9b6116 | 20691 | @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}. |
8925f36f AW |
20692 | |
20693 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
20694 | ||
20695 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
20696 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
20697 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
20698 | and @var{format} is not @code{GL_RGB}. | |
20699 | ||
20700 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
20701 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
20702 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
20703 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
20704 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
20705 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
20706 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
20707 | ||
20708 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
20709 | @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not | |
20710 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
20711 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}. | |
20712 | ||
20713 | @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is | |
20714 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
20715 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and | |
20716 | @var{format} is not @code{GL_DEPTH_COMPONENT}. | |
20717 | ||
20718 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
20719 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
20720 | object's data store is currently mapped. | |
20721 | ||
20722 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
20723 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
20724 | would be unpacked from the buffer object such that the memory reads | |
20725 | required would exceed the data store size. | |
20726 | ||
20727 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
20728 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
20729 | is not evenly divisible into the number of bytes needed to store in | |
20730 | memory a datum indicated by @var{type}. | |
20731 | ||
20732 | @code{GL_INVALID_OPERATION} is generated if @code{glTexImage1D} is | |
20733 | executed between the execution of @code{glBegin} and the corresponding | |
20734 | execution of @code{glEnd}. | |
20735 | ||
bb894c9d | 20736 | @end deftypefun |
8925f36f | 20737 | |
bb894c9d | 20738 | @deftypefun void glTexImage2D target level internalFormat width height border format type data |
3c9b6116 AW |
20739 | Specify a two-dimensional texture image. |
20740 | ||
8925f36f AW |
20741 | @table @asis |
20742 | @item @var{target} | |
f37e7e3d | 20743 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, |
8925f36f AW |
20744 | @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, |
20745 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
20746 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
20747 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
20748 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
20749 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
20750 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
20751 | ||
20752 | @item @var{level} | |
f37e7e3d | 20753 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
20754 | Level @var{n} is the @var{n}th mipmap reduction image. |
20755 | ||
20756 | @item @var{internalFormat} | |
f37e7e3d | 20757 | Specifies the number of color components in the texture. Must be 1, 2, |
8925f36f AW |
20758 | 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA}, |
20759 | @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
20760 | @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA}, | |
20761 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
20762 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
20763 | @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT}, | |
20764 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, | |
20765 | @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
20766 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
20767 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
20768 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
20769 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
20770 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
20771 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
20772 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
20773 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
20774 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
20775 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
20776 | @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE}, | |
20777 | @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
20778 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
20779 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
20780 | ||
20781 | @item @var{width} | |
f37e7e3d | 20782 | Specifies the width of the texture image including the border if any. If |
8925f36f | 20783 | the GL version does not support non-power-of-two sizes, this value must |
f37e7e3d | 20784 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 | 20785 | implementations support texture images that are at least 64 texels wide. |
8925f36f AW |
20786 | |
20787 | @item @var{height} | |
20788 | Specifies the height of the texture image including the border if any. | |
20789 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
20790 | must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}. |
20791 | All implementations support texture images that are at least 64 texels | |
20792 | high. | |
8925f36f AW |
20793 | |
20794 | @item @var{border} | |
f37e7e3d | 20795 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
20796 | |
20797 | @item @var{format} | |
f37e7e3d | 20798 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
20799 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, |
20800 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
20801 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
20802 | @code{GL_LUMINANCE_ALPHA}. | |
20803 | ||
20804 | @item @var{type} | |
f37e7e3d DH |
20805 | Specifies the data type of the pixel data. The following symbolic values |
20806 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
20807 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
20808 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
20809 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
20810 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
20811 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
20812 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
20813 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
20814 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f AW |
20815 | |
20816 | @item @var{data} | |
20817 | Specifies a pointer to the image data in memory. | |
20818 | ||
20819 | @end table | |
20820 | ||
8925f36f | 20821 | Texturing maps a portion of a specified texture image onto each |
f37e7e3d | 20822 | graphical primitive for which texturing is enabled. To enable and |
8925f36f | 20823 | disable two-dimensional texturing, call @code{glEnable} and |
f37e7e3d | 20824 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and |
8925f36f AW |
20825 | disable texturing using cube-mapped texture, call @code{glEnable} and |
20826 | @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}. | |
20827 | ||
f37e7e3d | 20828 | To define texture images, call @code{glTexImage2D}. The arguments |
8925f36f AW |
20829 | describe the parameters of the texture image, such as height, width, |
20830 | width of the border, level-of-detail number (see @code{glTexParameter}), | |
f37e7e3d | 20831 | and number of color components provided. The last three arguments |
8925f36f AW |
20832 | describe how the image is represented in memory; they are identical to |
20833 | the pixel formats used for @code{glDrawPixels}. | |
20834 | ||
20835 | If @var{target} is @code{GL_PROXY_TEXTURE_2D} or | |
20836 | @code{GL_PROXY_TEXTURE_CUBE_MAP}, no data is read from @var{data}, but | |
20837 | all of the texture image state is recalculated, checked for consistency, | |
f37e7e3d | 20838 | and checked against the implementation's capabilities. If the |
8925f36f AW |
20839 | implementation cannot handle a texture of the requested texture size, it |
20840 | sets all of the image state to 0, but does not generate an error (see | |
f37e7e3d | 20841 | @code{glGetError}). To query for an entire mipmap array, use an image |
8925f36f AW |
20842 | array level greater than or equal to 1. |
20843 | ||
20844 | If @var{target} is @code{GL_TEXTURE_2D}, or one of the | |
20845 | @code{GL_TEXTURE_CUBE_MAP} targets, data is read from @var{data} as a | |
20846 | sequence of signed or unsigned bytes, shorts, or longs, or | |
f37e7e3d | 20847 | single-precision floating-point values, depending on @var{type}. These |
8925f36f | 20848 | values are grouped into sets of one, two, three, or four values, |
f37e7e3d | 20849 | depending on @var{format}, to form elements. If @var{type} is |
8925f36f | 20850 | @code{GL_BITMAP}, the data is considered as a string of unsigned bytes |
f37e7e3d | 20851 | (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is |
8925f36f AW |
20852 | treated as eight 1-bit elements, with bit ordering determined by |
20853 | @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}). | |
20854 | ||
20855 | If a non-zero named buffer object is bound to the | |
20856 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
20857 | texture image is specified, @var{data} is treated as a byte offset into | |
20858 | the buffer object's data store. | |
20859 | ||
20860 | The first element corresponds to the lower left corner of the texture | |
f37e7e3d | 20861 | image. Subsequent elements progress left-to-right through the remaining |
8925f36f | 20862 | texels in the lowest row of the texture image, and then in successively |
f37e7e3d | 20863 | higher rows of the texture image. The final element corresponds to the |
8925f36f AW |
20864 | upper right corner of the texture image. |
20865 | ||
20866 | @var{format} determines the composition of each element in @var{data}. | |
20867 | It can assume one of these symbolic values: | |
20868 | ||
20869 | @table @asis | |
20870 | @item @code{GL_COLOR_INDEX} | |
f37e7e3d | 20871 | Each element is a single value, a color index. The GL converts it to |
8925f36f AW |
20872 | fixed point (with an unspecified number of zero bits to the right of the |
20873 | binary point), shifted left or right depending on the value and sign of | |
20874 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see | |
f37e7e3d | 20875 | @code{glPixelTransfer}). The resulting index is converted to a set of |
8925f36f AW |
20876 | color components using the @code{GL_PIXEL_MAP_I_TO_R}, |
20877 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
20878 | @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1]. | |
20879 | ||
20880 | @item @code{GL_RED} | |
f37e7e3d | 20881 | Each element is a single red component. The GL converts it to floating |
8925f36f | 20882 | point and assembles it into an RGBA element by attaching 0 for green and |
f37e7e3d | 20883 | blue, and 1 for alpha. Each component is then multiplied by the signed |
8925f36f AW |
20884 | scale factor @code{GL_c_SCALE}, added to the signed bias |
20885 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20886 | @code{glPixelTransfer}). | |
20887 | ||
20888 | @item @code{GL_GREEN} | |
f37e7e3d DH |
20889 | Each element is a single green component. The GL converts it to floating |
20890 | point and assembles it into an RGBA element by attaching 0 for red and | |
20891 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
20892 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
8925f36f AW |
20893 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see |
20894 | @code{glPixelTransfer}). | |
20895 | ||
20896 | @item @code{GL_BLUE} | |
f37e7e3d | 20897 | Each element is a single blue component. The GL converts it to floating |
8925f36f | 20898 | point and assembles it into an RGBA element by attaching 0 for red and |
f37e7e3d | 20899 | green, and 1 for alpha. Each component is then multiplied by the signed |
8925f36f AW |
20900 | scale factor @code{GL_c_SCALE}, added to the signed bias |
20901 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20902 | @code{glPixelTransfer}). | |
20903 | ||
20904 | @item @code{GL_ALPHA} | |
f37e7e3d DH |
20905 | Each element is a single alpha component. The GL converts it to floating |
20906 | point and assembles it into an RGBA element by attaching 0 for red, | |
20907 | green, and blue. Each component is then multiplied by the signed scale | |
20908 | factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20909 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
8925f36f AW |
20910 | |
20911 | @item @code{GL_INTENSITY} | |
f37e7e3d DH |
20912 | Each element is a single intensity value. The GL converts it to floating |
20913 | point, then assembles it into an RGBA element by replicating the | |
20914 | intensity value three times for red, green, blue, and alpha. Each | |
8925f36f AW |
20915 | component is then multiplied by the signed scale factor |
20916 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20917 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20918 | ||
20919 | @item @code{GL_RGB} | |
20920 | @item @code{GL_BGR} | |
f37e7e3d DH |
20921 | Each element is an RGB triple. The GL converts it to floating point and |
20922 | assembles it into an RGBA element by attaching 1 for alpha. Each | |
8925f36f AW |
20923 | component is then multiplied by the signed scale factor |
20924 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20925 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20926 | ||
20927 | @item @code{GL_RGBA} | |
20928 | @item @code{GL_BGRA} | |
f37e7e3d | 20929 | Each element contains all four components. Each component is multiplied |
8925f36f AW |
20930 | by the signed scale factor @code{GL_c_SCALE}, added to the signed bias |
20931 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20932 | @code{glPixelTransfer}). | |
20933 | ||
20934 | @item @code{GL_LUMINANCE} | |
f37e7e3d DH |
20935 | Each element is a single luminance value. The GL converts it to floating |
20936 | point, then assembles it into an RGBA element by replicating the | |
20937 | luminance value three times for red, green, and blue and attaching 1 for | |
20938 | alpha. Each component is then multiplied by the signed scale factor | |
8925f36f AW |
20939 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and |
20940 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20941 | ||
20942 | @item @code{GL_LUMINANCE_ALPHA} | |
f37e7e3d | 20943 | Each element is a luminance/alpha pair. The GL converts it to floating |
8925f36f | 20944 | point, then assembles it into an RGBA element by replicating the |
f37e7e3d | 20945 | luminance value three times for red, green, and blue. Each component is |
8925f36f AW |
20946 | then multiplied by the signed scale factor @code{GL_c_SCALE}, added to |
20947 | the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20948 | @code{glPixelTransfer}). | |
20949 | ||
20950 | @item @code{GL_DEPTH_COMPONENT} | |
f37e7e3d | 20951 | Each element is a single depth value. The GL converts it to floating |
8925f36f AW |
20952 | point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds |
20953 | the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see | |
20954 | @code{glPixelTransfer}). | |
20955 | ||
20956 | @end table | |
20957 | ||
20958 | Refer to the @code{glDrawPixels} reference page for a description of the | |
20959 | acceptable values for the @var{type} parameter. | |
20960 | ||
20961 | If an application wants to store the texture at a certain resolution or | |
20962 | in a certain format, it can request the resolution and format with | |
f37e7e3d DH |
20963 | @var{internalFormat}. The GL will choose an internal representation that |
20964 | closely approximates that requested by @var{internalFormat}, but it may | |
20965 | not match exactly. (The representations specified by | |
8925f36f | 20966 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and |
f37e7e3d DH |
20967 | @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may |
20968 | also be used to specify the above representations.) | |
8925f36f AW |
20969 | |
20970 | If the @var{internalFormat} parameter is one of the generic compressed | |
20971 | formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
20972 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
20973 | @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will | |
20974 | replace the internal format with the symbolic constant for a specific | |
f37e7e3d | 20975 | internal format and compress the texture before storage. If no |
8925f36f AW |
20976 | corresponding internal format is available, or the GL can not compress |
20977 | that image for any reason, the internal format is instead replaced with | |
20978 | a corresponding base internal format. | |
20979 | ||
20980 | If the @var{internalFormat} parameter is @code{GL_SRGB}, | |
20981 | @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8}, | |
20982 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
20983 | or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red, | |
20984 | green, blue, or luminance components are encoded in the sRGB color | |
f37e7e3d | 20985 | space. Any alpha component is left unchanged. The conversion from the |
3c9b6116 AW |
20986 | sRGB encoded component @r{@var{c}_@var{s}} to a linear component |
20987 | @r{@var{c}_@var{l}} is: | |
8925f36f | 20988 | |
3c9b6116 AW |
20989 | @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045), |
20990 | ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)} | |
8925f36f | 20991 | |
3c9b6116 | 20992 | Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1]. |
8925f36f AW |
20993 | |
20994 | Use the @code{GL_PROXY_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_CUBE_MAP} | |
f37e7e3d | 20995 | target to try out a resolution and format. The implementation will |
8925f36f | 20996 | update and recompute its best match for the requested storage resolution |
f37e7e3d DH |
20997 | and format. To then query this state, call |
20998 | @code{glGetTexLevelParameter}. If the texture cannot be accommodated, | |
8925f36f AW |
20999 | texture state is set to 0. |
21000 | ||
21001 | A one-component texture image uses only the red component of the RGBA | |
f37e7e3d DH |
21002 | color extracted from @var{data}. A two-component image uses the R and A |
21003 | values. A three-component image uses the R, G, and B values. A | |
8925f36f AW |
21004 | four-component image uses all of the RGBA components. |
21005 | ||
21006 | Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures | |
f37e7e3d | 21007 | during texture filtering and application. Image-based shadowing can be |
8925f36f | 21008 | enabled by comparing texture r coordinates to depth texture values to |
f37e7e3d | 21009 | generate a boolean result. See @code{glTexParameter} for details on |
8925f36f AW |
21010 | texture comparison. |
21011 | ||
8925f36f AW |
21012 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
21013 | @code{GL_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_2D}, | |
21014 | @code{GL_PROXY_TEXTURE_CUBE_MAP}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
21015 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
21016 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
21017 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
21018 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
21019 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
21020 | ||
21021 | @code{GL_INVALID_ENUM} is generated if @var{target} is one of the six | |
21022 | cube map 2D image targets and the width and height parameters are not | |
21023 | equal. | |
21024 | ||
21025 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
21026 | constant. | |
21027 | ||
21028 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
21029 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
21030 | ||
21031 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is | |
21032 | less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
21033 | ||
21034 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
21035 | ||
21036 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
21037 | @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of |
21038 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
21039 | |
21040 | @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1, | |
21041 | 2, 3, 4, or one of the accepted resolution and format symbolic | |
21042 | constants. | |
21043 | ||
21044 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is | |
21045 | less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
21046 | ||
21047 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
21048 | not supported and the @var{width} or @var{height} cannot be represented | |
3c9b6116 | 21049 | as @r{2^@var{k}+2(@var{border},)} for some integer value of @var{k}. |
8925f36f AW |
21050 | |
21051 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
21052 | ||
21053 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21054 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21055 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
21056 | and @var{format} is not @code{GL_RGB}. | |
21057 | ||
21058 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21059 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21060 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21061 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21062 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
21063 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
21064 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
21065 | ||
21066 | @code{GL_INVALID_OPERATION} is generated if @var{target} is not | |
21067 | @code{GL_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_2D} and | |
21068 | @var{internalFormat} is @code{GL_DEPTH_COMPONENT}, | |
21069 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or | |
21070 | @code{GL_DEPTH_COMPONENT32}. | |
21071 | ||
21072 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
21073 | @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not | |
21074 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
21075 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}. | |
21076 | ||
21077 | @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is | |
21078 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
21079 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and | |
21080 | @var{format} is not @code{GL_DEPTH_COMPONENT}. | |
21081 | ||
21082 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21083 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
21084 | object's data store is currently mapped. | |
21085 | ||
21086 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21087 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
21088 | would be unpacked from the buffer object such that the memory reads | |
21089 | required would exceed the data store size. | |
21090 | ||
21091 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21092 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
21093 | is not evenly divisible into the number of bytes needed to store in | |
21094 | memory a datum indicated by @var{type}. | |
21095 | ||
21096 | @code{GL_INVALID_OPERATION} is generated if @code{glTexImage2D} is | |
21097 | executed between the execution of @code{glBegin} and the corresponding | |
21098 | execution of @code{glEnd}. | |
21099 | ||
bb894c9d | 21100 | @end deftypefun |
8925f36f | 21101 | |
bb894c9d | 21102 | @deftypefun void glTexImage3D target level internalFormat width height depth border format type data |
3c9b6116 AW |
21103 | Specify a three-dimensional texture image. |
21104 | ||
8925f36f AW |
21105 | @table @asis |
21106 | @item @var{target} | |
f37e7e3d | 21107 | Specifies the target texture. Must be @code{GL_TEXTURE_3D} or |
8925f36f AW |
21108 | @code{GL_PROXY_TEXTURE_3D}. |
21109 | ||
21110 | @item @var{level} | |
f37e7e3d | 21111 | Specifies the level-of-detail number. Level 0 is the base image level. |
3c9b6116 | 21112 | Level @r{@var{n}} is the @r{@var{n}^@var{th}} mipmap reduction image. |
8925f36f AW |
21113 | |
21114 | @item @var{internalFormat} | |
f37e7e3d | 21115 | Specifies the number of color components in the texture. Must be 1, 2, |
8925f36f AW |
21116 | 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA}, |
21117 | @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
21118 | @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA}, | |
21119 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
21120 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
21121 | @code{GL_COMPRESSED_RGBA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
21122 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
21123 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
21124 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
21125 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
21126 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
21127 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
21128 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
21129 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
21130 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
21131 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
21132 | @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE}, | |
21133 | @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
21134 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
21135 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
21136 | ||
21137 | @item @var{width} | |
f37e7e3d | 21138 | Specifies the width of the texture image including the border if any. If |
8925f36f | 21139 | the GL version does not support non-power-of-two sizes, this value must |
f37e7e3d | 21140 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 AW |
21141 | implementations support 3D texture images that are at least 16 texels |
21142 | wide. | |
8925f36f AW |
21143 | |
21144 | @item @var{height} | |
21145 | Specifies the height of the texture image including the border if any. | |
21146 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
21147 | must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}. |
21148 | All implementations support 3D texture images that are at least 16 | |
21149 | texels high. | |
8925f36f AW |
21150 | |
21151 | @item @var{depth} | |
f37e7e3d | 21152 | Specifies the depth of the texture image including the border if any. If |
8925f36f | 21153 | the GL version does not support non-power-of-two sizes, this value must |
f37e7e3d | 21154 | be @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}. All |
3c9b6116 AW |
21155 | implementations support 3D texture images that are at least 16 texels |
21156 | deep. | |
8925f36f AW |
21157 | |
21158 | @item @var{border} | |
f37e7e3d | 21159 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
21160 | |
21161 | @item @var{format} | |
f37e7e3d | 21162 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
21163 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, |
21164 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
21165 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
21166 | @code{GL_LUMINANCE_ALPHA}. | |
21167 | ||
21168 | @item @var{type} | |
f37e7e3d DH |
21169 | Specifies the data type of the pixel data. The following symbolic values |
21170 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
21171 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
21172 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
21173 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
21174 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
21175 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
21176 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
21177 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
21178 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f AW |
21179 | |
21180 | @item @var{data} | |
21181 | Specifies a pointer to the image data in memory. | |
21182 | ||
21183 | @end table | |
21184 | ||
8925f36f | 21185 | Texturing maps a portion of a specified texture image onto each |
f37e7e3d | 21186 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
21187 | disable three-dimensional texturing, call @code{glEnable} and |
21188 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
21189 | ||
f37e7e3d | 21190 | To define texture images, call @code{glTexImage3D}. The arguments |
8925f36f AW |
21191 | describe the parameters of the texture image, such as height, width, |
21192 | depth, width of the border, level-of-detail number (see | |
f37e7e3d | 21193 | @code{glTexParameter}), and number of color components provided. The |
8925f36f AW |
21194 | last three arguments describe how the image is represented in memory; |
21195 | they are identical to the pixel formats used for @code{glDrawPixels}. | |
21196 | ||
21197 | If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from | |
21198 | @var{data}, but all of the texture image state is recalculated, checked | |
21199 | for consistency, and checked against the implementation's capabilities. | |
21200 | If the implementation cannot handle a texture of the requested texture | |
21201 | size, it sets all of the image state to 0, but does not generate an | |
f37e7e3d | 21202 | error (see @code{glGetError}). To query for an entire mipmap array, use |
8925f36f AW |
21203 | an image array level greater than or equal to 1. |
21204 | ||
21205 | If @var{target} is @code{GL_TEXTURE_3D}, data is read from @var{data} as | |
21206 | a sequence of signed or unsigned bytes, shorts, or longs, or | |
f37e7e3d | 21207 | single-precision floating-point values, depending on @var{type}. These |
8925f36f | 21208 | values are grouped into sets of one, two, three, or four values, |
f37e7e3d | 21209 | depending on @var{format}, to form elements. If @var{type} is |
8925f36f | 21210 | @code{GL_BITMAP}, the data is considered as a string of unsigned bytes |
f37e7e3d | 21211 | (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is |
8925f36f AW |
21212 | treated as eight 1-bit elements, with bit ordering determined by |
21213 | @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}). | |
21214 | ||
21215 | If a non-zero named buffer object is bound to the | |
21216 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
21217 | texture image is specified, @var{data} is treated as a byte offset into | |
21218 | the buffer object's data store. | |
21219 | ||
21220 | The first element corresponds to the lower left corner of the texture | |
f37e7e3d | 21221 | image. Subsequent elements progress left-to-right through the remaining |
8925f36f | 21222 | texels in the lowest row of the texture image, and then in successively |
f37e7e3d | 21223 | higher rows of the texture image. The final element corresponds to the |
8925f36f AW |
21224 | upper right corner of the texture image. |
21225 | ||
21226 | @var{format} determines the composition of each element in @var{data}. | |
21227 | It can assume one of these symbolic values: | |
21228 | ||
21229 | @table @asis | |
21230 | @item @code{GL_COLOR_INDEX} | |
f37e7e3d | 21231 | Each element is a single value, a color index. The GL converts it to |
8925f36f AW |
21232 | fixed point (with an unspecified number of zero bits to the right of the |
21233 | binary point), shifted left or right depending on the value and sign of | |
21234 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see | |
f37e7e3d | 21235 | @code{glPixelTransfer}). The resulting index is converted to a set of |
8925f36f AW |
21236 | color components using the @code{GL_PIXEL_MAP_I_TO_R}, |
21237 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
21238 | @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1]. | |
21239 | ||
21240 | @item @code{GL_RED} | |
f37e7e3d | 21241 | Each element is a single red component. The GL converts it to floating |
8925f36f | 21242 | point and assembles it into an RGBA element by attaching 0 for green and |
f37e7e3d | 21243 | blue, and 1 for alpha. Each component is then multiplied by the signed |
8925f36f AW |
21244 | scale factor @code{GL_c_SCALE}, added to the signed bias |
21245 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21246 | @code{glPixelTransfer}). | |
21247 | ||
21248 | @item @code{GL_GREEN} | |
f37e7e3d DH |
21249 | Each element is a single green component. The GL converts it to floating |
21250 | point and assembles it into an RGBA element by attaching 0 for red and | |
21251 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
21252 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
8925f36f AW |
21253 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see |
21254 | @code{glPixelTransfer}). | |
21255 | ||
21256 | @item @code{GL_BLUE} | |
f37e7e3d | 21257 | Each element is a single blue component. The GL converts it to floating |
8925f36f | 21258 | point and assembles it into an RGBA element by attaching 0 for red and |
f37e7e3d | 21259 | green, and 1 for alpha. Each component is then multiplied by the signed |
8925f36f AW |
21260 | scale factor @code{GL_c_SCALE}, added to the signed bias |
21261 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21262 | @code{glPixelTransfer}). | |
21263 | ||
21264 | @item @code{GL_ALPHA} | |
f37e7e3d DH |
21265 | Each element is a single alpha component. The GL converts it to floating |
21266 | point and assembles it into an RGBA element by attaching 0 for red, | |
21267 | green, and blue. Each component is then multiplied by the signed scale | |
21268 | factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
21269 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
8925f36f AW |
21270 | |
21271 | @item @code{GL_INTENSITY} | |
f37e7e3d DH |
21272 | Each element is a single intensity value. The GL converts it to floating |
21273 | point, then assembles it into an RGBA element by replicating the | |
21274 | intensity value three times for red, green, blue, and alpha. Each | |
8925f36f AW |
21275 | component is then multiplied by the signed scale factor |
21276 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
21277 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
21278 | ||
21279 | @item @code{GL_RGB} | |
21280 | @item @code{GL_BGR} | |
f37e7e3d DH |
21281 | Each element is an RGB triple. The GL converts it to floating point and |
21282 | assembles it into an RGBA element by attaching 1 for alpha. Each | |
8925f36f AW |
21283 | component is then multiplied by the signed scale factor |
21284 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
21285 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
21286 | ||
21287 | @item @code{GL_RGBA} | |
21288 | @item @code{GL_BGRA} | |
f37e7e3d | 21289 | Each element contains all four components. Each component is multiplied |
8925f36f AW |
21290 | by the signed scale factor @code{GL_c_SCALE}, added to the signed bias |
21291 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21292 | @code{glPixelTransfer}). | |
21293 | ||
21294 | @item @code{GL_LUMINANCE} | |
f37e7e3d DH |
21295 | Each element is a single luminance value. The GL converts it to floating |
21296 | point, then assembles it into an RGBA element by replicating the | |
21297 | luminance value three times for red, green, and blue and attaching 1 for | |
21298 | alpha. Each component is then multiplied by the signed scale factor | |
8925f36f AW |
21299 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and |
21300 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
21301 | ||
21302 | @item @code{GL_LUMINANCE_ALPHA} | |
f37e7e3d | 21303 | Each element is a luminance/alpha pair. The GL converts it to floating |
8925f36f | 21304 | point, then assembles it into an RGBA element by replicating the |
f37e7e3d | 21305 | luminance value three times for red, green, and blue. Each component is |
8925f36f AW |
21306 | then multiplied by the signed scale factor @code{GL_c_SCALE}, added to |
21307 | the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21308 | @code{glPixelTransfer}). | |
21309 | ||
21310 | @end table | |
21311 | ||
21312 | Refer to the @code{glDrawPixels} reference page for a description of the | |
21313 | acceptable values for the @var{type} parameter. | |
21314 | ||
21315 | If an application wants to store the texture at a certain resolution or | |
21316 | in a certain format, it can request the resolution and format with | |
f37e7e3d DH |
21317 | @var{internalFormat}. The GL will choose an internal representation that |
21318 | closely approximates that requested by @var{internalFormat}, but it may | |
21319 | not match exactly. (The representations specified by | |
8925f36f | 21320 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and |
f37e7e3d DH |
21321 | @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may |
21322 | also be used to specify the above representations.) | |
8925f36f AW |
21323 | |
21324 | If the @var{internalFormat} parameter is one of the generic compressed | |
21325 | formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
21326 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
21327 | @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will | |
21328 | replace the internal format with the symbolic constant for a specific | |
f37e7e3d | 21329 | internal format and compress the texture before storage. If no |
8925f36f AW |
21330 | corresponding internal format is available, or the GL can not compress |
21331 | that image for any reason, the internal format is instead replaced with | |
21332 | a corresponding base internal format. | |
21333 | ||
21334 | If the @var{internalFormat} parameter is @code{GL_SRGB}, | |
21335 | @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8}, | |
21336 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
21337 | or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red, | |
21338 | green, blue, or luminance components are encoded in the sRGB color | |
f37e7e3d | 21339 | space. Any alpha component is left unchanged. The conversion from the |
3c9b6116 AW |
21340 | sRGB encoded component @r{@var{c}_@var{s}} to a linear component |
21341 | @r{@var{c}_@var{l}} is: | |
8925f36f | 21342 | |
3c9b6116 AW |
21343 | @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045), |
21344 | ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)} | |
8925f36f | 21345 | |
3c9b6116 | 21346 | Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1]. |
8925f36f AW |
21347 | |
21348 | Use the @code{GL_PROXY_TEXTURE_3D} target to try out a resolution and | |
f37e7e3d DH |
21349 | format. The implementation will update and recompute its best match for |
21350 | the requested storage resolution and format. To then query this state, | |
21351 | call @code{glGetTexLevelParameter}. If the texture cannot be | |
8925f36f AW |
21352 | accommodated, texture state is set to 0. |
21353 | ||
21354 | A one-component texture image uses only the red component of the RGBA | |
f37e7e3d DH |
21355 | color extracted from @var{data}. A two-component image uses the R and A |
21356 | values. A three-component image uses the R, G, and B values. A | |
8925f36f AW |
21357 | four-component image uses all of the RGBA components. |
21358 | ||
8925f36f AW |
21359 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
21360 | @code{GL_TEXTURE_3D} or @code{GL_PROXY_TEXTURE_3D}. | |
21361 | ||
21362 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
f37e7e3d DH |
21363 | format constant. Format constants other than @code{GL_STENCIL_INDEX} and |
21364 | @code{GL_DEPTH_COMPONENT} are accepted. | |
8925f36f AW |
21365 | |
21366 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
21367 | constant. | |
21368 | ||
21369 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
21370 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
21371 | ||
21372 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
21373 | ||
21374 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
21375 | @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of |
21376 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
21377 | |
21378 | @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1, | |
21379 | 2, 3, 4, or one of the accepted resolution and format symbolic | |
21380 | constants. | |
21381 | ||
21382 | @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or | |
21383 | @var{depth} is less than 0 or greater than 2 + | |
21384 | @code{GL_MAX_TEXTURE_SIZE}. | |
21385 | ||
21386 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
21387 | not supported and the @var{width}, @var{height}, or @var{depth} cannot | |
3c9b6116 AW |
21388 | be represented as @r{2^@var{k}+2(@var{border},)} for some integer value |
21389 | of @var{k}. | |
8925f36f AW |
21390 | |
21391 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
21392 | ||
21393 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21394 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21395 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
21396 | and @var{format} is not @code{GL_RGB}. | |
21397 | ||
21398 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21399 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21400 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21401 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21402 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
21403 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
21404 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
21405 | ||
21406 | @code{GL_INVALID_OPERATION} is generated if @var{format} or | |
21407 | @var{internalFormat} is @code{GL_DEPTH_COMPONENT}, | |
21408 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or | |
21409 | @code{GL_DEPTH_COMPONENT32}. | |
21410 | ||
21411 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21412 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
21413 | object's data store is currently mapped. | |
21414 | ||
21415 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21416 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
21417 | would be unpacked from the buffer object such that the memory reads | |
21418 | required would exceed the data store size. | |
21419 | ||
21420 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21421 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
21422 | is not evenly divisible into the number of bytes needed to store in | |
21423 | memory a datum indicated by @var{type}. | |
21424 | ||
21425 | @code{GL_INVALID_OPERATION} is generated if @code{glTexImage3D} is | |
21426 | executed between the execution of @code{glBegin} and the corresponding | |
21427 | execution of @code{glEnd}. | |
21428 | ||
bb894c9d | 21429 | @end deftypefun |
8925f36f | 21430 | |
bb894c9d AW |
21431 | @deftypefun void glTexParameterf target pname param |
21432 | @deftypefunx void glTexParameteri target pname param | |
d172eed9 AW |
21433 | @deftypefunx void glTexParameterfv target pname params |
21434 | @deftypefunx void glTexParameteriv target pname params | |
3c9b6116 AW |
21435 | Set texture parameters. |
21436 | ||
8925f36f AW |
21437 | @table @asis |
21438 | @item @var{target} | |
21439 | Specifies the target texture, which must be either @code{GL_TEXTURE_1D}, | |
21440 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or | |
21441 | @code{GL_TEXTURE_CUBE_MAP}. | |
21442 | ||
21443 | @item @var{pname} | |
21444 | Specifies the symbolic name of a single-valued texture parameter. | |
21445 | @var{pname} can be one of the following: @code{GL_TEXTURE_MIN_FILTER}, | |
21446 | @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_LOD}, | |
21447 | @code{GL_TEXTURE_MAX_LOD}, @code{GL_TEXTURE_BASE_LEVEL}, | |
21448 | @code{GL_TEXTURE_MAX_LEVEL}, @code{GL_TEXTURE_WRAP_S}, | |
21449 | @code{GL_TEXTURE_WRAP_T}, @code{GL_TEXTURE_WRAP_R}, | |
21450 | @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_COMPARE_MODE}, | |
21451 | @code{GL_TEXTURE_COMPARE_FUNC}, @code{GL_DEPTH_TEXTURE_MODE}, or | |
21452 | @code{GL_GENERATE_MIPMAP}. | |
21453 | ||
21454 | @item @var{param} | |
21455 | Specifies the value of @var{pname}. | |
21456 | ||
21457 | @end table | |
21458 | ||
8925f36f | 21459 | Texture mapping is a technique that applies an image onto an object's |
f37e7e3d | 21460 | surface as if the image were a decal or cellophane shrink-wrap. The |
3c9b6116 | 21461 | image is created in texture space, with an (@r{@var{s}}, @r{@var{t}}) |
f37e7e3d | 21462 | coordinate system. A texture is a one- or two-dimensional image and a |
3c9b6116 | 21463 | set of parameters that determine how samples are derived from the image. |
8925f36f AW |
21464 | |
21465 | @code{glTexParameter} assigns the value or values in @var{params} to the | |
f37e7e3d | 21466 | texture parameter specified as @var{pname}. @var{target} defines the |
8925f36f | 21467 | target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, or |
f37e7e3d | 21468 | @code{GL_TEXTURE_3D}. The following symbols are accepted in @var{pname}: |
8925f36f AW |
21469 | |
21470 | @table @asis | |
21471 | @item @code{GL_TEXTURE_MIN_FILTER} | |
21472 | The texture minifying function is used whenever the pixel being textured | |
f37e7e3d DH |
21473 | maps to an area greater than one texture element. There are six defined |
21474 | minifying functions. Two of them use the nearest one or nearest four | |
21475 | texture elements to compute the texture value. The other four use | |
8925f36f AW |
21476 | mipmaps. |
21477 | ||
21478 | A mipmap is an ordered set of arrays representing the same image at | |
f37e7e3d | 21479 | progressively lower resolutions. If the texture has dimensions |
3c9b6116 | 21480 | @r{2^@var{n}×2^@var{m}}, there are @r{@var{max}(@var{n},@var{m})+1} |
f37e7e3d DH |
21481 | mipmaps. The first mipmap is the original texture, with dimensions |
21482 | @r{2^@var{n}×2^@var{m}}. Each subsequent mipmap has dimensions | |
3c9b6116 AW |
21483 | @r{2^@var{k}-1,×2^@var{l}-1,}, where @r{2^@var{k}×2^@var{l}} are the |
21484 | dimensions of the previous mipmap, until either @r{@var{k}=0} or | |
f37e7e3d | 21485 | @r{@var{l}=0}. At that point, subsequent mipmaps have dimension |
3c9b6116 | 21486 | @r{1×2^@var{l}-1,} or @r{2^@var{k}-1,×1} until the final mipmap, which |
f37e7e3d | 21487 | has dimension @r{1×1}. To define the mipmaps, call @code{glTexImage1D}, |
8925f36f AW |
21488 | @code{glTexImage2D}, @code{glTexImage3D}, @code{glCopyTexImage1D}, or |
21489 | @code{glCopyTexImage2D} with the @var{level} argument indicating the | |
f37e7e3d | 21490 | order of the mipmaps. Level 0 is the original texture; level |
3c9b6116 | 21491 | @r{@var{max}(@var{n},@var{m})} is the final @r{1×1} mipmap. |
8925f36f AW |
21492 | |
21493 | @var{params} supplies a function for minifying the texture as one of the | |
21494 | following: | |
21495 | ||
21496 | As more texture elements are sampled in the minification process, fewer | |
f37e7e3d | 21497 | aliasing artifacts will be apparent. While the @code{GL_NEAREST} and |
8925f36f AW |
21498 | @code{GL_LINEAR} minification functions can be faster than the other |
21499 | four, they sample only one or four texture elements to determine the | |
21500 | texture value of the pixel being rendered and can produce moire patterns | |
f37e7e3d DH |
21501 | or ragged transitions. The initial value of @code{GL_TEXTURE_MIN_FILTER} |
21502 | is @code{GL_NEAREST_MIPMAP_LINEAR}. | |
8925f36f AW |
21503 | |
21504 | @item @code{GL_TEXTURE_MAG_FILTER} | |
21505 | The texture magnification function is used when the pixel being textured | |
f37e7e3d | 21506 | maps to an area less than or equal to one texture element. It sets the |
8925f36f | 21507 | texture magnification function to either @code{GL_NEAREST} or |
f37e7e3d DH |
21508 | @code{GL_LINEAR} (see below). @code{GL_NEAREST} is generally faster than |
21509 | @code{GL_LINEAR}, but it can produce textured images with sharper edges | |
21510 | because the transition between texture elements is not as smooth. The | |
21511 | initial value of @code{GL_TEXTURE_MAG_FILTER} is @code{GL_LINEAR}. | |
8925f36f AW |
21512 | |
21513 | @end table | |
21514 | ||
21515 | @table @asis | |
21516 | @item @code{GL_NEAREST} | |
21517 | Returns the value of the texture element that is nearest (in Manhattan | |
21518 | distance) to the center of the pixel being textured. | |
21519 | ||
21520 | @item @code{GL_LINEAR} | |
21521 | Returns the weighted average of the four texture elements that are | |
f37e7e3d | 21522 | closest to the center of the pixel being textured. These can include |
8925f36f AW |
21523 | border texture elements, depending on the values of |
21524 | @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact | |
21525 | mapping. | |
21526 | ||
21527 | @item @code{GL_NEAREST_MIPMAP_NEAREST} | |
21528 | Chooses the mipmap that most closely matches the size of the pixel being | |
21529 | textured and uses the @code{GL_NEAREST} criterion (the texture element | |
21530 | nearest to the center of the pixel) to produce a texture value. | |
21531 | ||
21532 | @item @code{GL_LINEAR_MIPMAP_NEAREST} | |
21533 | Chooses the mipmap that most closely matches the size of the pixel being | |
21534 | textured and uses the @code{GL_LINEAR} criterion (a weighted average of | |
21535 | the four texture elements that are closest to the center of the pixel) | |
21536 | to produce a texture value. | |
21537 | ||
21538 | @item @code{GL_NEAREST_MIPMAP_LINEAR} | |
21539 | Chooses the two mipmaps that most closely match the size of the pixel | |
21540 | being textured and uses the @code{GL_NEAREST} criterion (the texture | |
21541 | element nearest to the center of the pixel) to produce a texture value | |
f37e7e3d DH |
21542 | from each mipmap. The final texture value is a weighted average of those |
21543 | two values. | |
8925f36f AW |
21544 | |
21545 | @item @code{GL_LINEAR_MIPMAP_LINEAR} | |
21546 | Chooses the two mipmaps that most closely match the size of the pixel | |
21547 | being textured and uses the @code{GL_LINEAR} criterion (a weighted | |
21548 | average of the four texture elements that are closest to the center of | |
f37e7e3d | 21549 | the pixel) to produce a texture value from each mipmap. The final |
8925f36f AW |
21550 | texture value is a weighted average of those two values. |
21551 | ||
21552 | @end table | |
21553 | ||
21554 | @table @asis | |
21555 | @item @code{GL_NEAREST} | |
21556 | Returns the value of the texture element that is nearest (in Manhattan | |
21557 | distance) to the center of the pixel being textured. | |
21558 | ||
21559 | @item @code{GL_LINEAR} | |
21560 | Returns the weighted average of the four texture elements that are | |
f37e7e3d | 21561 | closest to the center of the pixel being textured. These can include |
8925f36f AW |
21562 | border texture elements, depending on the values of |
21563 | @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact | |
21564 | mapping. | |
21565 | ||
21566 | @end table | |
21567 | ||
21568 | ||
21569 | ||
21570 | @table @asis | |
21571 | @item @code{GL_TEXTURE_MIN_LOD} | |
f37e7e3d | 21572 | Sets the minimum level-of-detail parameter. This floating-point value |
8925f36f AW |
21573 | limits the selection of highest resolution mipmap (lowest mipmap level). |
21574 | The initial value is -1000. | |
21575 | ||
21576 | @end table | |
21577 | ||
21578 | ||
21579 | ||
21580 | @table @asis | |
21581 | @item @code{GL_TEXTURE_MAX_LOD} | |
f37e7e3d | 21582 | Sets the maximum level-of-detail parameter. This floating-point value |
8925f36f | 21583 | limits the selection of the lowest resolution mipmap (highest mipmap |
f37e7e3d | 21584 | level). The initial value is 1000. |
8925f36f AW |
21585 | |
21586 | @end table | |
21587 | ||
21588 | ||
21589 | ||
21590 | @table @asis | |
21591 | @item @code{GL_TEXTURE_BASE_LEVEL} | |
f37e7e3d DH |
21592 | Specifies the index of the lowest defined mipmap level. This is an |
21593 | integer value. The initial value is 0. | |
8925f36f AW |
21594 | |
21595 | @end table | |
21596 | ||
21597 | ||
21598 | ||
21599 | @table @asis | |
21600 | @item @code{GL_TEXTURE_MAX_LEVEL} | |
f37e7e3d DH |
21601 | Sets the index of the highest defined mipmap level. This is an integer |
21602 | value. The initial value is 1000. | |
8925f36f AW |
21603 | |
21604 | @end table | |
21605 | ||
21606 | ||
21607 | ||
21608 | @table @asis | |
21609 | @item @code{GL_TEXTURE_WRAP_S} | |
3c9b6116 | 21610 | Sets the wrap parameter for texture coordinate @r{@var{s}} to either |
8925f36f | 21611 | @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE}, |
f37e7e3d | 21612 | @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. @code{GL_CLAMP} causes |
3c9b6116 AW |
21613 | @r{@var{s}} coordinates to be clamped to the range [0,1] and is useful |
21614 | for preventing wrapping artifacts when mapping a single image onto an | |
f37e7e3d | 21615 | object. @code{GL_CLAMP_TO_BORDER} causes the @r{@var{s}} coordinate to |
3c9b6116 AW |
21616 | be clamped to the range @r{[-1/2@var{N},,1+1/2@var{N},]}, where |
21617 | @r{@var{N}} is the size of the texture in the direction of | |
21618 | clamping.@code{GL_CLAMP_TO_EDGE} causes @r{@var{s}} coordinates to be | |
21619 | clamped to the range @r{[1/2@var{N},,1-1/2@var{N},]}, where @r{@var{N}} | |
21620 | is the size of the texture in the direction of clamping. | |
21621 | @code{GL_REPEAT} causes the integer part of the @r{@var{s}} coordinate | |
21622 | to be ignored; the GL uses only the fractional part, thereby creating a | |
f37e7e3d | 21623 | repeating pattern. @code{GL_MIRRORED_REPEAT} causes the @r{@var{s}} |
3c9b6116 AW |
21624 | coordinate to be set to the fractional part of the texture coordinate if |
21625 | the integer part of @r{@var{s}} is even; if the integer part of | |
21626 | @r{@var{s}} is odd, then the @r{@var{s}} texture coordinate is set to | |
21627 | @r{1-@var{frac}(@var{s},)}, where @r{@var{frac}(@var{s},)} represents | |
f37e7e3d DH |
21628 | the fractional part of @r{@var{s}}. Border texture elements are accessed |
21629 | only if wrapping is set to @code{GL_CLAMP} or @code{GL_CLAMP_TO_BORDER}. | |
21630 | Initially, @code{GL_TEXTURE_WRAP_S} is set to @code{GL_REPEAT}. | |
8925f36f AW |
21631 | |
21632 | @end table | |
21633 | ||
21634 | ||
21635 | ||
21636 | @table @asis | |
21637 | @item @code{GL_TEXTURE_WRAP_T} | |
3c9b6116 | 21638 | Sets the wrap parameter for texture coordinate @r{@var{t}} to either |
8925f36f | 21639 | @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE}, |
f37e7e3d DH |
21640 | @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion under |
21641 | @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_T} is set to | |
21642 | @code{GL_REPEAT}. | |
8925f36f AW |
21643 | |
21644 | @item @code{GL_TEXTURE_WRAP_R} | |
3c9b6116 | 21645 | Sets the wrap parameter for texture coordinate @r{@var{r}} to either |
8925f36f | 21646 | @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE}, |
f37e7e3d DH |
21647 | @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion under |
21648 | @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_R} is set to | |
21649 | @code{GL_REPEAT}. | |
8925f36f AW |
21650 | |
21651 | @item @code{GL_TEXTURE_BORDER_COLOR} | |
f37e7e3d DH |
21652 | Sets a border color. @var{params} contains four values that comprise the |
21653 | RGBA color of the texture border. Integer color components are | |
8925f36f | 21654 | interpreted linearly such that the most positive integer maps to 1.0, |
f37e7e3d DH |
21655 | and the most negative integer maps to -1.0. The values are clamped to |
21656 | the range [0,1] when they are specified. Initially, the border color is | |
8925f36f AW |
21657 | (0, 0, 0, 0). |
21658 | ||
21659 | @item @code{GL_TEXTURE_PRIORITY} | |
21660 | Specifies the texture residence priority of the currently bound texture. | |
f37e7e3d | 21661 | Permissible values are in the range @r{[0,1]}. See |
8925f36f AW |
21662 | @code{glPrioritizeTextures} and @code{glBindTexture} for more |
21663 | information. | |
21664 | ||
21665 | @item @code{GL_TEXTURE_COMPARE_MODE} | |
21666 | Specifies the texture comparison mode for currently bound depth | |
f37e7e3d | 21667 | textures. That is, a texture whose internal format is |
8925f36f AW |
21668 | @code{GL_DEPTH_COMPONENT_*}; see @code{glTexImage2D}) Permissible values |
21669 | are: | |
21670 | ||
21671 | @item @code{GL_TEXTURE_COMPARE_FUNC} | |
21672 | Specifies the comparison operator used when | |
21673 | @code{GL_TEXTURE_COMPARE_MODE} is set to @code{GL_COMPARE_R_TO_TEXTURE}. | |
3c9b6116 AW |
21674 | Permissible values are: where @r{@var{r}} is the current interpolated |
21675 | texture coordinate, and @r{@var{D}_@var{t}} is the depth texture value | |
f37e7e3d | 21676 | sampled from the currently bound depth texture. @r{@var{result}} is |
3c9b6116 AW |
21677 | assigned to the either the luminance, intensity, or alpha (as specified |
21678 | by @code{GL_DEPTH_TEXTURE_MODE}.) | |
8925f36f AW |
21679 | |
21680 | @item @code{GL_DEPTH_TEXTURE_MODE} | |
21681 | Specifies a single symbolic constant indicating how depth values should | |
f37e7e3d DH |
21682 | be treated during filtering and texture application. Accepted values are |
21683 | @code{GL_LUMINANCE}, @code{GL_INTENSITY}, and @code{GL_ALPHA}. The | |
8925f36f AW |
21684 | initial value is @code{GL_LUMINANCE}. |
21685 | ||
21686 | @item @code{GL_GENERATE_MIPMAP} | |
21687 | Specifies a boolean value that indicates if all levels of a mipmap array | |
21688 | should be automatically updated when any modification to the base level | |
f37e7e3d | 21689 | mipmap is done. The initial value is @code{GL_FALSE}. |
8925f36f AW |
21690 | |
21691 | @end table | |
21692 | ||
21693 | @table @asis | |
21694 | @item @code{GL_COMPARE_R_TO_TEXTURE} | |
3c9b6116 | 21695 | Specifies that the interpolated and clamped @r{@var{r}} texture |
8925f36f | 21696 | coordinate should be compared to the value in the currently bound depth |
f37e7e3d DH |
21697 | texture. See the discussion of @code{GL_TEXTURE_COMPARE_FUNC} for |
21698 | details of how the comparison is evaluated. The result of the comparison | |
21699 | is assigned to luminance, intensity, or alpha (as specified by | |
21700 | @code{GL_DEPTH_TEXTURE_MODE}). | |
8925f36f AW |
21701 | |
21702 | @item @code{GL_NONE} | |
21703 | Specifies that the luminance, intensity, or alpha (as specified by | |
21704 | @code{GL_DEPTH_TEXTURE_MODE}) should be assigned the appropriate value | |
21705 | from the currently bound depth texture. | |
21706 | ||
21707 | @end table | |
21708 | ||
21709 | @table @asis | |
21710 | @item @strong{Texture Comparison Function} | |
21711 | @strong{Computed result} | |
21712 | ||
21713 | @item @code{GL_LEQUAL} | |
3c9b6116 | 21714 | @r{@var{result}=@{(1.0), (0.0) (@var{r}<=@var{D}_@var{t},), |
8925f36f AW |
21715 | (@var{r}>@var{D}_@var{t},),} |
21716 | ||
21717 | @item @code{GL_GEQUAL} | |
3c9b6116 | 21718 | @r{@var{result}=@{(1.0), (0.0) (@var{r}>=@var{D}_@var{t},), |
8925f36f AW |
21719 | (@var{r}<@var{D}_@var{t},),} |
21720 | ||
21721 | @item @code{GL_LESS} | |
3c9b6116 | 21722 | @r{@var{result}=@{(1.0), (0.0) (@var{r}<@var{D}_@var{t},), |
8925f36f AW |
21723 | (@var{r}>=@var{D}_@var{t},),} |
21724 | ||
21725 | @item @code{GL_GREATER} | |
3c9b6116 | 21726 | @r{@var{result}=@{(1.0), (0.0) (@var{r}>@var{D}_@var{t},), |
8925f36f AW |
21727 | (@var{r}<=@var{D}_@var{t},),} |
21728 | ||
21729 | @item @code{GL_EQUAL} | |
3c9b6116 | 21730 | @r{@var{result}=@{(1.0), (0.0) (@var{r}=@var{D}_@var{t},), |
8925f36f AW |
21731 | (@var{r}≠@var{D}_@var{t},),} |
21732 | ||
21733 | @item @code{GL_NOTEQUAL} | |
3c9b6116 | 21734 | @r{@var{result}=@{(1.0), (0.0) (@var{r}≠@var{D}_@var{t},), |
8925f36f AW |
21735 | (@var{r}=@var{D}_@var{t},),} |
21736 | ||
21737 | @item @code{GL_ALWAYS} | |
3c9b6116 | 21738 | @r{@var{result}=@code{1.0}} |
8925f36f AW |
21739 | |
21740 | @item @code{GL_NEVER} | |
3c9b6116 | 21741 | @r{@var{result}=@code{0.0}} |
8925f36f AW |
21742 | |
21743 | @end table | |
21744 | ||
8925f36f AW |
21745 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is |
21746 | not one of the accepted defined values. | |
21747 | ||
21748 | @code{GL_INVALID_ENUM} is generated if @var{params} should have a | |
21749 | defined constant value (based on the value of @var{pname}) and does not. | |
21750 | ||
21751 | @code{GL_INVALID_OPERATION} is generated if @code{glTexParameter} is | |
21752 | executed between the execution of @code{glBegin} and the corresponding | |
21753 | execution of @code{glEnd}. | |
21754 | ||
bb894c9d | 21755 | @end deftypefun |
8925f36f | 21756 | |
bb894c9d | 21757 | @deftypefun void glTexSubImage1D target level xoffset width format type data |
3c9b6116 AW |
21758 | Specify a one-dimensional texture subimage. |
21759 | ||
8925f36f AW |
21760 | @table @asis |
21761 | @item @var{target} | |
f37e7e3d | 21762 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. |
8925f36f AW |
21763 | |
21764 | @item @var{level} | |
f37e7e3d | 21765 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
21766 | Level @var{n} is the @var{n}th mipmap reduction image. |
21767 | ||
21768 | @item @var{xoffset} | |
21769 | Specifies a texel offset in the x direction within the texture array. | |
21770 | ||
21771 | @item @var{width} | |
21772 | Specifies the width of the texture subimage. | |
21773 | ||
21774 | @item @var{format} | |
f37e7e3d | 21775 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
21776 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, |
21777 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
21778 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
21779 | @code{GL_LUMINANCE_ALPHA}. | |
21780 | ||
21781 | @item @var{type} | |
f37e7e3d DH |
21782 | Specifies the data type of the pixel data. The following symbolic values |
21783 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
21784 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
21785 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
21786 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
21787 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
21788 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
21789 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
21790 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
21791 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f AW |
21792 | |
21793 | @item @var{data} | |
21794 | Specifies a pointer to the image data in memory. | |
21795 | ||
21796 | @end table | |
21797 | ||
8925f36f | 21798 | Texturing maps a portion of a specified texture image onto each |
f37e7e3d DH |
21799 | graphical primitive for which texturing is enabled. To enable or disable |
21800 | one-dimensional texturing, call @code{glEnable} and @code{glDisable} | |
21801 | with argument @code{GL_TEXTURE_1D}. | |
8925f36f AW |
21802 | |
21803 | @code{glTexSubImage1D} redefines a contiguous subregion of an existing | |
f37e7e3d | 21804 | one-dimensional texture image. The texels referenced by @var{data} |
8925f36f | 21805 | replace the portion of the existing texture array with x indices |
f37e7e3d | 21806 | @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive. This |
8925f36f | 21807 | region may not include any texels outside the range of the texture array |
f37e7e3d | 21808 | as it was originally specified. It is not an error to specify a |
8925f36f AW |
21809 | subtexture with width of 0, but such a specification has no effect. |
21810 | ||
21811 | If a non-zero named buffer object is bound to the | |
21812 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
21813 | texture image is specified, @var{data} is treated as a byte offset into | |
21814 | the buffer object's data store. | |
21815 | ||
8925f36f AW |
21816 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
21817 | allowable values. | |
21818 | ||
21819 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
21820 | format constant. | |
21821 | ||
21822 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
21823 | constant. | |
21824 | ||
21825 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
21826 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
21827 | ||
21828 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
21829 | ||
21830 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 | 21831 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of |
8925f36f AW |
21832 | @code{GL_MAX_TEXTURE_SIZE}. |
21833 | ||
3c9b6116 AW |
21834 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or |
21835 | if @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where | |
21836 | @r{@var{w}} is the @code{GL_TEXTURE_WIDTH}, and @r{@var{b}} is the width | |
21837 | of the @code{GL_TEXTURE_BORDER} of the texture image being modified. | |
21838 | Note that @r{@var{w}} includes twice the border width. | |
8925f36f AW |
21839 | |
21840 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0. | |
21841 | ||
21842 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
21843 | been defined by a previous @code{glTexImage1D} operation. | |
21844 | ||
21845 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21846 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21847 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
21848 | and @var{format} is not @code{GL_RGB}. | |
21849 | ||
21850 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21851 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21852 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21853 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21854 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
21855 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
21856 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
21857 | ||
21858 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21859 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
21860 | object's data store is currently mapped. | |
21861 | ||
21862 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21863 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
21864 | would be unpacked from the buffer object such that the memory reads | |
21865 | required would exceed the data store size. | |
21866 | ||
21867 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21868 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
21869 | is not evenly divisible into the number of bytes needed to store in | |
21870 | memory a datum indicated by @var{type}. | |
21871 | ||
21872 | @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage1D} is | |
21873 | executed between the execution of @code{glBegin} and the corresponding | |
21874 | execution of @code{glEnd}. | |
21875 | ||
bb894c9d | 21876 | @end deftypefun |
8925f36f | 21877 | |
bb894c9d | 21878 | @deftypefun void glTexSubImage2D target level xoffset yoffset width height format type data |
3c9b6116 AW |
21879 | Specify a two-dimensional texture subimage. |
21880 | ||
8925f36f AW |
21881 | @table @asis |
21882 | @item @var{target} | |
f37e7e3d | 21883 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, |
8925f36f AW |
21884 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, |
21885 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
21886 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
21887 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
21888 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
21889 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
21890 | ||
21891 | @item @var{level} | |
f37e7e3d | 21892 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
21893 | Level @var{n} is the @var{n}th mipmap reduction image. |
21894 | ||
21895 | @item @var{xoffset} | |
21896 | Specifies a texel offset in the x direction within the texture array. | |
21897 | ||
21898 | @item @var{yoffset} | |
21899 | Specifies a texel offset in the y direction within the texture array. | |
21900 | ||
21901 | @item @var{width} | |
21902 | Specifies the width of the texture subimage. | |
21903 | ||
21904 | @item @var{height} | |
21905 | Specifies the height of the texture subimage. | |
21906 | ||
21907 | @item @var{format} | |
f37e7e3d | 21908 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
21909 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, |
21910 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
21911 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
21912 | @code{GL_LUMINANCE_ALPHA}. | |
21913 | ||
21914 | @item @var{type} | |
f37e7e3d DH |
21915 | Specifies the data type of the pixel data. The following symbolic values |
21916 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
21917 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
21918 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
21919 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
21920 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
21921 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
21922 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
21923 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
21924 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f AW |
21925 | |
21926 | @item @var{data} | |
21927 | Specifies a pointer to the image data in memory. | |
21928 | ||
21929 | @end table | |
21930 | ||
8925f36f | 21931 | Texturing maps a portion of a specified texture image onto each |
f37e7e3d | 21932 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
21933 | disable two-dimensional texturing, call @code{glEnable} and |
21934 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. | |
21935 | ||
21936 | @code{glTexSubImage2D} redefines a contiguous subregion of an existing | |
f37e7e3d | 21937 | two-dimensional texture image. The texels referenced by @var{data} |
8925f36f | 21938 | replace the portion of the existing texture array with x indices |
3c9b6116 AW |
21939 | @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, and y |
21940 | indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive. | |
21941 | This region may not include any texels outside the range of the texture | |
f37e7e3d | 21942 | array as it was originally specified. It is not an error to specify a |
3c9b6116 AW |
21943 | subtexture with zero width or height, but such a specification has no |
21944 | effect. | |
8925f36f AW |
21945 | |
21946 | If a non-zero named buffer object is bound to the | |
21947 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
21948 | texture image is specified, @var{data} is treated as a byte offset into | |
21949 | the buffer object's data store. | |
21950 | ||
8925f36f AW |
21951 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
21952 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
21953 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
21954 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
21955 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
21956 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
21957 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
21958 | ||
21959 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
21960 | format constant. | |
21961 | ||
21962 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
21963 | constant. | |
21964 | ||
21965 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
21966 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
21967 | ||
21968 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
21969 | ||
21970 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 | 21971 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of |
8925f36f AW |
21972 | @code{GL_MAX_TEXTURE_SIZE}. |
21973 | ||
3c9b6116 AW |
21974 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, |
21975 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
21976 | @r{@var{yoffset}<-@var{b}}, or | |
21977 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}} | |
21978 | is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the | |
21979 | @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the border width of the | |
f37e7e3d | 21980 | texture image being modified. Note that @r{@var{w}} and @r{@var{h}} |
3c9b6116 | 21981 | include twice the border width. |
8925f36f AW |
21982 | |
21983 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is | |
21984 | less than 0. | |
21985 | ||
21986 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
21987 | been defined by a previous @code{glTexImage2D} operation. | |
21988 | ||
21989 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21990 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21991 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
21992 | and @var{format} is not @code{GL_RGB}. | |
21993 | ||
21994 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21995 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21996 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21997 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21998 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
21999 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
22000 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
22001 | ||
22002 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
22003 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
22004 | object's data store is currently mapped. | |
22005 | ||
22006 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
22007 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
22008 | would be unpacked from the buffer object such that the memory reads | |
22009 | required would exceed the data store size. | |
22010 | ||
22011 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
22012 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
22013 | is not evenly divisible into the number of bytes needed to store in | |
22014 | memory a datum indicated by @var{type}. | |
22015 | ||
22016 | @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage2D} is | |
22017 | executed between the execution of @code{glBegin} and the corresponding | |
22018 | execution of @code{glEnd}. | |
22019 | ||
bb894c9d | 22020 | @end deftypefun |
8925f36f | 22021 | |
bb894c9d | 22022 | @deftypefun void glTexSubImage3D target level xoffset yoffset zoffset width height depth format type data |
3c9b6116 AW |
22023 | Specify a three-dimensional texture subimage. |
22024 | ||
8925f36f AW |
22025 | @table @asis |
22026 | @item @var{target} | |
f37e7e3d | 22027 | Specifies the target texture. Must be @code{GL_TEXTURE_3D}. |
8925f36f AW |
22028 | |
22029 | @item @var{level} | |
f37e7e3d | 22030 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
22031 | Level @var{n} is the @var{n}th mipmap reduction image. |
22032 | ||
22033 | @item @var{xoffset} | |
22034 | Specifies a texel offset in the x direction within the texture array. | |
22035 | ||
22036 | @item @var{yoffset} | |
22037 | Specifies a texel offset in the y direction within the texture array. | |
22038 | ||
22039 | @item @var{zoffset} | |
22040 | Specifies a texel offset in the z direction within the texture array. | |
22041 | ||
22042 | @item @var{width} | |
22043 | Specifies the width of the texture subimage. | |
22044 | ||
22045 | @item @var{height} | |
22046 | Specifies the height of the texture subimage. | |
22047 | ||
22048 | @item @var{depth} | |
22049 | Specifies the depth of the texture subimage. | |
22050 | ||
22051 | @item @var{format} | |
f37e7e3d | 22052 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
22053 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, |
22054 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
22055 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
22056 | @code{GL_LUMINANCE_ALPHA}. | |
22057 | ||
22058 | @item @var{type} | |
f37e7e3d DH |
22059 | Specifies the data type of the pixel data. The following symbolic values |
22060 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
22061 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
22062 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
22063 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
22064 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
22065 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
22066 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
22067 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
22068 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f AW |
22069 | |
22070 | @item @var{data} | |
22071 | Specifies a pointer to the image data in memory. | |
22072 | ||
22073 | @end table | |
22074 | ||
8925f36f | 22075 | Texturing maps a portion of a specified texture image onto each |
f37e7e3d | 22076 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
22077 | disable three-dimensional texturing, call @code{glEnable} and |
22078 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
22079 | ||
22080 | @code{glTexSubImage3D} redefines a contiguous subregion of an existing | |
f37e7e3d | 22081 | three-dimensional texture image. The texels referenced by @var{data} |
8925f36f | 22082 | replace the portion of the existing texture array with x indices |
3c9b6116 AW |
22083 | @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, y indices |
22084 | @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive, and z | |
22085 | indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive. | |
22086 | This region may not include any texels outside the range of the texture | |
f37e7e3d | 22087 | array as it was originally specified. It is not an error to specify a |
3c9b6116 AW |
22088 | subtexture with zero width, height, or depth but such a specification |
22089 | has no effect. | |
8925f36f AW |
22090 | |
22091 | If a non-zero named buffer object is bound to the | |
22092 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
22093 | texture image is specified, @var{data} is treated as a byte offset into | |
22094 | the buffer object's data store. | |
22095 | ||
8925f36f AW |
22096 | @code{GL_INVALID_ENUM} is generated if /@var{target} is not |
22097 | @code{GL_TEXTURE_3D}. | |
22098 | ||
22099 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
22100 | format constant. | |
22101 | ||
22102 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
22103 | constant. | |
22104 | ||
22105 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
22106 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
22107 | ||
22108 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
22109 | ||
22110 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 | 22111 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of |
8925f36f AW |
22112 | @code{GL_MAX_TEXTURE_SIZE}. |
22113 | ||
3c9b6116 AW |
22114 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, |
22115 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
22116 | @r{@var{yoffset}<-@var{b}}, or | |
22117 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, or | |
22118 | @r{@var{zoffset}<-@var{b}}, or | |
22119 | @r{(@var{zoffset}+@var{depth},)>(@var{d}-@var{b},)}, where @r{@var{w}} | |
22120 | is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the | |
22121 | @code{GL_TEXTURE_HEIGHT}, @r{@var{d}} is the @code{GL_TEXTURE_DEPTH} and | |
22122 | @r{@var{b}} is the border width of the texture image being modified. | |
22123 | Note that @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the | |
22124 | border width. | |
8925f36f AW |
22125 | |
22126 | @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or | |
22127 | @var{depth} is less than 0. | |
22128 | ||
22129 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
22130 | been defined by a previous @code{glTexImage3D} operation. | |
22131 | ||
22132 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
22133 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
22134 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
22135 | and @var{format} is not @code{GL_RGB}. | |
22136 | ||
22137 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
22138 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
22139 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
22140 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
22141 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
22142 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
22143 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
22144 | ||
22145 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
22146 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
22147 | object's data store is currently mapped. | |
22148 | ||
22149 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
22150 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
22151 | would be unpacked from the buffer object such that the memory reads | |
22152 | required would exceed the data store size. | |
22153 | ||
22154 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
22155 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
22156 | is not evenly divisible into the number of bytes needed to store in | |
22157 | memory a datum indicated by @var{type}. | |
22158 | ||
22159 | @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage3D} is | |
22160 | executed between the execution of @code{glBegin} and the corresponding | |
22161 | execution of @code{glEnd}. | |
22162 | ||
bb894c9d | 22163 | @end deftypefun |
8925f36f | 22164 | |
d172eed9 AW |
22165 | @deftypefun void glTranslated x y z |
22166 | @deftypefunx void glTranslatef x y z | |
3c9b6116 AW |
22167 | Multiply the current matrix by a translation matrix. |
22168 | ||
8925f36f AW |
22169 | @table @asis |
22170 | @item @var{x} | |
22171 | @itemx @var{y} | |
22172 | @itemx @var{z} | |
22173 | Specify the @var{x}, @var{y}, and @var{z} coordinates of a translation | |
22174 | vector. | |
22175 | ||
22176 | @end table | |
22177 | ||
8925f36f | 22178 | @code{glTranslate} produces a translation by |
f37e7e3d | 22179 | @r{(@var{x},@var{y}@var{z})}. The current matrix (see |
8925f36f AW |
22180 | @code{glMatrixMode}) is multiplied by this translation matrix, with the |
22181 | product replacing the current matrix, as if @code{glMultMatrix} were | |
22182 | called with the following matrix for its argument: | |
22183 | ||
3c9b6116 | 22184 | @r{((1 0 0 @var{x}), (0 1 0 @var{y}), (0 0 1 @var{z}), (0 0 0 1),)} |
8925f36f AW |
22185 | |
22186 | ||
22187 | ||
22188 | If the matrix mode is either @code{GL_MODELVIEW} or | |
22189 | @code{GL_PROJECTION}, all objects drawn after a call to | |
22190 | @code{glTranslate} are translated. | |
22191 | ||
22192 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
22193 | untranslated coordinate system. | |
22194 | ||
8925f36f AW |
22195 | @code{GL_INVALID_OPERATION} is generated if @code{glTranslate} is |
22196 | executed between the execution of @code{glBegin} and the corresponding | |
22197 | execution of @code{glEnd}. | |
22198 | ||
bb894c9d | 22199 | @end deftypefun |
8925f36f | 22200 | |
bb894c9d AW |
22201 | @deftypefun void glUniform1f location v0 |
22202 | @deftypefunx void glUniform2f location v0 v1 | |
22203 | @deftypefunx void glUniform3f location v0 v1 v2 | |
22204 | @deftypefunx void glUniform4f location v0 v1 v2 v3 | |
22205 | @deftypefunx void glUniform1i location v0 | |
22206 | @deftypefunx void glUniform2i location v0 v1 | |
22207 | @deftypefunx void glUniform3i location v0 v1 v2 | |
22208 | @deftypefunx void glUniform4i location v0 v1 v2 v3 | |
d172eed9 AW |
22209 | @deftypefunx void glUniform1fv location count value |
22210 | @deftypefunx void glUniform2fv location count value | |
22211 | @deftypefunx void glUniform3fv location count value | |
22212 | @deftypefunx void glUniform4fv location count value | |
22213 | @deftypefunx void glUniform1iv location count value | |
22214 | @deftypefunx void glUniform2iv location count value | |
22215 | @deftypefunx void glUniform3iv location count value | |
22216 | @deftypefunx void glUniform4iv location count value | |
b002944d AW |
22217 | @deftypefunx void glUniformMatrix2fv location count transpose value |
22218 | @deftypefunx void glUniformMatrix3fv location count transpose value | |
22219 | @deftypefunx void glUniformMatrix4fv location count transpose value | |
22220 | @deftypefunx void glUniformMatrix2x3fv location count transpose value | |
22221 | @deftypefunx void glUniformMatrix3x2fv location count transpose value | |
22222 | @deftypefunx void glUniformMatrix2x4fv location count transpose value | |
22223 | @deftypefunx void glUniformMatrix4x2fv location count transpose value | |
22224 | @deftypefunx void glUniformMatrix3x4fv location count transpose value | |
22225 | @deftypefunx void glUniformMatrix4x3fv location count transpose value | |
3c9b6116 AW |
22226 | Specify the value of a uniform variable for the current program object. |
22227 | ||
8925f36f AW |
22228 | @table @asis |
22229 | @item @var{location} | |
22230 | Specifies the location of the uniform variable to be modified. | |
22231 | ||
22232 | @item @var{v0}, @var{v1}, @var{v2}, @var{v3} | |
22233 | Specifies the new values to be used for the specified uniform variable. | |
22234 | ||
22235 | @end table | |
22236 | ||
8925f36f | 22237 | @code{glUniform} modifies the value of a uniform variable or a uniform |
f37e7e3d | 22238 | variable array. The location of the uniform variable to be modified is |
8925f36f | 22239 | specified by @var{location}, which should be a value returned by |
f37e7e3d | 22240 | @code{glGetUniformLocation}. @code{glUniform} operates on the program |
8925f36f AW |
22241 | object that was made part of current state by calling |
22242 | @code{glUseProgram}. | |
22243 | ||
22244 | The commands @code{glUniform@{1|2|3|4@}@{f|i@}} are used to change the | |
22245 | value of the uniform variable specified by @var{location} using the | |
f37e7e3d | 22246 | values passed as arguments. The number specified in the command should |
8925f36f AW |
22247 | match the number of components in the data type of the specified uniform |
22248 | variable (e.g., @code{1} for float, int, bool; @code{2} for vec2, ivec2, | |
f37e7e3d | 22249 | bvec2, etc.). The suffix @code{f} indicates that floating-point values |
8925f36f AW |
22250 | are being passed; the suffix @code{i} indicates that integer values are |
22251 | being passed, and this type should also match the data type of the | |
f37e7e3d | 22252 | specified uniform variable. The @code{i} variants of this function |
8925f36f | 22253 | should be used to provide values for uniform variables defined as int, |
f37e7e3d DH |
22254 | ivec2, ivec3, ivec4, or arrays of these. The @code{f} variants should be |
22255 | used to provide values for uniform variables of type float, vec2, vec3, | |
22256 | vec4, or arrays of these. Either the @code{i} or the @code{f} variants | |
22257 | may be used to provide values for uniform variables of type bool, bvec2, | |
22258 | bvec3, bvec4, or arrays of these. The uniform variable will be set to | |
22259 | false if the input value is 0 or 0.0f, and it will be set to true | |
22260 | otherwise. | |
8925f36f AW |
22261 | |
22262 | All active uniform variables defined in a program object are initialized | |
f37e7e3d | 22263 | to 0 when the program object is linked successfully. They retain the |
8925f36f AW |
22264 | values assigned to them by a call to @code{glUniform } until the next |
22265 | successful link operation occurs on the program object, when they are | |
22266 | once again initialized to 0. | |
22267 | ||
22268 | The commands @code{glUniform@{1|2|3|4@}@{f|i@}v} can be used to modify a | |
f37e7e3d DH |
22269 | single uniform variable or a uniform variable array. These commands pass |
22270 | a count and a pointer to the values to be loaded into a uniform variable | |
22271 | or a uniform variable array. A count of 1 should be used if modifying | |
22272 | the value of a single uniform variable, and a count of 1 or greater can | |
22273 | be used to modify an entire array or part of an array. When loading | |
22274 | @var{n} elements starting at an arbitrary position @var{m} in a uniform | |
22275 | variable array, elements @var{m} + @var{n} - 1 in the array will be | |
22276 | replaced with the new values. If @var{m} + @var{n} - 1 is larger than | |
22277 | the size of the uniform variable array, values for all array elements | |
22278 | beyond the end of the array will be ignored. The number specified in the | |
22279 | name of the command indicates the number of components for each element | |
22280 | in @var{value}, and it should match the number of components in the data | |
22281 | type of the specified uniform variable (e.g., @code{1} for float, int, | |
22282 | bool; @code{2} for vec2, ivec2, bvec2, etc.). The data type specified in | |
22283 | the name of the command must match the data type for the specified | |
22284 | uniform variable as described previously for | |
8925f36f AW |
22285 | @code{glUniform@{1|2|3|4@}@{f|i@}}. |
22286 | ||
22287 | For uniform variable arrays, each element of the array is considered to | |
22288 | be of the type indicated in the name of the command (e.g., | |
22289 | @code{glUniform3f} or @code{glUniform3fv} can be used to load a uniform | |
f37e7e3d | 22290 | variable array of type vec3). The number of elements of the uniform |
8925f36f AW |
22291 | variable array to be modified is specified by @var{count} |
22292 | ||
22293 | The commands @code{glUniformMatrix@{2|3|4|2x3|3x2|2x4|4x2|3x4|4x3@}fv} | |
f37e7e3d DH |
22294 | are used to modify a matrix or an array of matrices. The numbers in the |
22295 | command name are interpreted as the dimensionality of the matrix. The | |
8925f36f AW |
22296 | number @code{2} indicates a 2 × 2 matrix (i.e., 4 values), the number |
22297 | @code{3} indicates a 3 × 3 matrix (i.e., 9 values), and the number | |
f37e7e3d | 22298 | @code{4} indicates a 4 × 4 matrix (i.e., 16 values). Non-square matrix |
8925f36f AW |
22299 | dimensionality is explicit, with the first number representing the |
22300 | number of columns and the second number representing the number of rows. | |
22301 | For example, @code{2x4} indicates a 2 × 4 matrix with 2 columns and 4 | |
f37e7e3d DH |
22302 | rows (i.e., 8 values). If @var{transpose} is @code{GL_FALSE}, each |
22303 | matrix is assumed to be supplied in column major order. If | |
8925f36f | 22304 | @var{transpose} is @code{GL_TRUE}, each matrix is assumed to be supplied |
f37e7e3d DH |
22305 | in row major order. The @var{count} argument indicates the number of |
22306 | matrices to be passed. A count of 1 should be used if modifying the | |
8925f36f AW |
22307 | value of a single matrix, and a count greater than 1 can be used to |
22308 | modify an array of matrices. | |
22309 | ||
8925f36f AW |
22310 | @code{GL_INVALID_OPERATION} is generated if there is no current program |
22311 | object. | |
22312 | ||
22313 | @code{GL_INVALID_OPERATION} is generated if the size of the uniform | |
22314 | variable declared in the shader does not match the size indicated by the | |
22315 | @code{glUniform} command. | |
22316 | ||
22317 | @code{GL_INVALID_OPERATION} is generated if one of the integer variants | |
22318 | of this function is used to load a uniform variable of type float, vec2, | |
22319 | vec3, vec4, or an array of these, or if one of the floating-point | |
22320 | variants of this function is used to load a uniform variable of type | |
22321 | int, ivec2, ivec3, or ivec4, or an array of these. | |
22322 | ||
22323 | @code{GL_INVALID_OPERATION} is generated if @var{location} is an invalid | |
22324 | uniform location for the current program object and @var{location} is | |
22325 | not equal to -1. | |
22326 | ||
22327 | @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0. | |
22328 | ||
22329 | @code{GL_INVALID_OPERATION} is generated if @var{count} is greater than | |
22330 | 1 and the indicated uniform variable is not an array variable. | |
22331 | ||
22332 | @code{GL_INVALID_OPERATION} is generated if a sampler is loaded using a | |
22333 | command other than @code{glUniform1i} and @code{glUniform1iv}. | |
22334 | ||
22335 | @code{GL_INVALID_OPERATION} is generated if @code{glUniform} is executed | |
22336 | between the execution of @code{glBegin} and the corresponding execution | |
22337 | of @code{glEnd}. | |
22338 | ||
bb894c9d | 22339 | @end deftypefun |
8925f36f | 22340 | |
bb894c9d | 22341 | @deftypefun void glUseProgram program |
3c9b6116 AW |
22342 | Installs a program object as part of current rendering state. |
22343 | ||
8925f36f AW |
22344 | @table @asis |
22345 | @item @var{program} | |
22346 | Specifies the handle of the program object whose executables are to be | |
22347 | used as part of current rendering state. | |
22348 | ||
22349 | @end table | |
22350 | ||
8925f36f | 22351 | @code{glUseProgram} installs the program object specified by |
f37e7e3d | 22352 | @var{program} as part of current rendering state. One or more |
8925f36f AW |
22353 | executables are created in a program object by successfully attaching |
22354 | shader objects to it with @code{glAttachShader}, successfully compiling | |
22355 | the shader objects with @code{glCompileShader}, and successfully linking | |
22356 | the program object with @code{glLinkProgram}. | |
22357 | ||
22358 | A program object will contain an executable that will run on the vertex | |
22359 | processor if it contains one or more shader objects of type | |
22360 | @code{GL_VERTEX_SHADER} that have been successfully compiled and linked. | |
22361 | Similarly, a program object will contain an executable that will run on | |
22362 | the fragment processor if it contains one or more shader objects of type | |
22363 | @code{GL_FRAGMENT_SHADER} that have been successfully compiled and | |
22364 | linked. | |
22365 | ||
22366 | Successfully installing an executable on a programmable processor will | |
22367 | cause the corresponding fixed functionality of OpenGL to be disabled. | |
22368 | Specifically, if an executable is installed on the vertex processor, the | |
22369 | OpenGL fixed functionality will be disabled as follows. | |
22370 | ||
22371 | @itemize | |
22372 | @item | |
22373 | The modelview matrix is not applied to vertex coordinates. | |
22374 | ||
22375 | @item | |
22376 | The projection matrix is not applied to vertex coordinates. | |
22377 | ||
22378 | @item | |
22379 | The texture matrices are not applied to texture coordinates. | |
22380 | ||
22381 | @item | |
22382 | Normals are not transformed to eye coordinates. | |
22383 | ||
22384 | @item | |
22385 | Normals are not rescaled or normalized. | |
22386 | ||
22387 | @item | |
22388 | Normalization of @code{GL_AUTO_NORMAL} evaluated normals is not | |
22389 | performed. | |
22390 | ||
22391 | @item | |
22392 | Texture coordinates are not generated automatically. | |
22393 | ||
22394 | @item | |
22395 | Per-vertex lighting is not performed. | |
22396 | ||
22397 | @item | |
22398 | Color material computations are not performed. | |
22399 | ||
22400 | @item | |
22401 | Color index lighting is not performed. | |
22402 | ||
22403 | @item | |
22404 | This list also applies when setting the current raster position. | |
22405 | ||
22406 | @end itemize | |
22407 | ||
22408 | The executable that is installed on the vertex processor is expected to | |
22409 | implement any or all of the desired functionality from the preceding | |
f37e7e3d | 22410 | list. Similarly, if an executable is installed on the fragment |
8925f36f AW |
22411 | processor, the OpenGL fixed functionality will be disabled as follows. |
22412 | ||
22413 | @itemize | |
22414 | @item | |
22415 | Texture environment and texture functions are not applied. | |
22416 | ||
22417 | @item | |
22418 | Texture application is not applied. | |
22419 | ||
22420 | @item | |
22421 | Color sum is not applied. | |
22422 | ||
22423 | @item | |
22424 | Fog is not applied. | |
22425 | ||
22426 | @end itemize | |
22427 | ||
22428 | Again, the fragment shader that is installed is expected to implement | |
22429 | any or all of the desired functionality from the preceding list. | |
22430 | ||
22431 | While a program object is in use, applications are free to modify | |
22432 | attached shader objects, compile attached shader objects, attach | |
f37e7e3d | 22433 | additional shader objects, and detach or delete shader objects. None of |
8925f36f | 22434 | these operations will affect the executables that are part of the |
f37e7e3d | 22435 | current state. However, relinking the program object that is currently |
8925f36f AW |
22436 | in use will install the program object as part of the current rendering |
22437 | state if the link operation was successful (see @code{glLinkProgram} ). | |
22438 | If the program object currently in use is relinked unsuccessfully, its | |
22439 | link status will be set to @code{GL_FALSE}, but the executables and | |
22440 | associated state will remain part of the current state until a | |
f37e7e3d | 22441 | subsequent call to @code{glUseProgram} removes it from use. After it is |
8925f36f AW |
22442 | removed from use, it cannot be made part of current state until it has |
22443 | been successfully relinked. | |
22444 | ||
22445 | If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER} | |
22446 | but it does not contain shader objects of type | |
22447 | @code{GL_FRAGMENT_SHADER}, an executable will be installed on the vertex | |
22448 | processor, but fixed functionality will be used for fragment processing. | |
22449 | Similarly, if @var{program} contains shader objects of type | |
22450 | @code{GL_FRAGMENT_SHADER} but it does not contain shader objects of type | |
22451 | @code{GL_VERTEX_SHADER}, an executable will be installed on the fragment | |
22452 | processor, but fixed functionality will be used for vertex processing. | |
22453 | If @var{program} is 0, the programmable processors will be disabled, and | |
22454 | fixed functionality will be used for both vertex and fragment | |
22455 | processing. | |
22456 | ||
8925f36f AW |
22457 | @code{GL_INVALID_VALUE} is generated if @var{program} is neither 0 nor a |
22458 | value generated by OpenGL. | |
22459 | ||
22460 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
22461 | program object. | |
22462 | ||
22463 | @code{GL_INVALID_OPERATION} is generated if @var{program} could not be | |
22464 | made part of current state. | |
22465 | ||
22466 | @code{GL_INVALID_OPERATION} is generated if @code{glUseProgram} is | |
22467 | executed between the execution of @code{glBegin} and the corresponding | |
22468 | execution of @code{glEnd}. | |
22469 | ||
bb894c9d | 22470 | @end deftypefun |
8925f36f | 22471 | |
bb894c9d | 22472 | @deftypefun void glValidateProgram program |
3c9b6116 AW |
22473 | Validates a program object. |
22474 | ||
8925f36f AW |
22475 | @table @asis |
22476 | @item @var{program} | |
22477 | Specifies the handle of the program object to be validated. | |
22478 | ||
22479 | @end table | |
22480 | ||
8925f36f | 22481 | @code{glValidateProgram} checks to see whether the executables contained |
f37e7e3d | 22482 | in @var{program} can execute given the current OpenGL state. The |
8925f36f | 22483 | information generated by the validation process will be stored in |
f37e7e3d | 22484 | @var{program}'s information log. The validation information may consist |
8925f36f AW |
22485 | of an empty string, or it may be a string containing information about |
22486 | how the current program object interacts with the rest of current OpenGL | |
f37e7e3d | 22487 | state. This provides a way for OpenGL implementers to convey more |
8925f36f AW |
22488 | information about why the current program is inefficient, suboptimal, |
22489 | failing to execute, and so on. | |
22490 | ||
22491 | The status of the validation operation will be stored as part of the | |
f37e7e3d DH |
22492 | program object's state. This value will be set to @code{GL_TRUE} if the |
22493 | validation succeeded, and @code{GL_FALSE} otherwise. It can be queried | |
8925f36f | 22494 | by calling @code{glGetProgram} with arguments @var{program} and |
f37e7e3d DH |
22495 | @code{GL_VALIDATE_STATUS}. If validation is successful, @var{program} is |
22496 | guaranteed to execute given the current state. Otherwise, @var{program} | |
22497 | is guaranteed to not execute. | |
8925f36f AW |
22498 | |
22499 | This function is typically useful only during application development. | |
22500 | The informational string stored in the information log is completely | |
22501 | implementation dependent; therefore, an application should not expect | |
22502 | different OpenGL implementations to produce identical information | |
22503 | strings. | |
22504 | ||
8925f36f AW |
22505 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
22506 | generated by OpenGL. | |
22507 | ||
22508 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
22509 | program object. | |
22510 | ||
22511 | @code{GL_INVALID_OPERATION} is generated if @code{glValidateProgram} is | |
22512 | executed between the execution of @code{glBegin} and the corresponding | |
22513 | execution of @code{glEnd}. | |
22514 | ||
bb894c9d | 22515 | @end deftypefun |
8925f36f | 22516 | |
bb894c9d | 22517 | @deftypefun void glVertexAttribPointer index size type normalized stride pointer |
3c9b6116 AW |
22518 | Define an array of generic vertex attribute data. |
22519 | ||
8925f36f AW |
22520 | @table @asis |
22521 | @item @var{index} | |
22522 | Specifies the index of the generic vertex attribute to be modified. | |
22523 | ||
22524 | @item @var{size} | |
f37e7e3d DH |
22525 | Specifies the number of components per generic vertex attribute. Must be |
22526 | 1, 2, 3, or 4. The initial value is 4. | |
8925f36f AW |
22527 | |
22528 | @item @var{type} | |
f37e7e3d | 22529 | Specifies the data type of each component in the array. Symbolic |
8925f36f AW |
22530 | constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, |
22531 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
f37e7e3d | 22532 | @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is |
8925f36f AW |
22533 | @code{GL_FLOAT}. |
22534 | ||
22535 | @item @var{normalized} | |
22536 | Specifies whether fixed-point data values should be normalized | |
22537 | (@code{GL_TRUE}) or converted directly as fixed-point values | |
22538 | (@code{GL_FALSE}) when they are accessed. | |
22539 | ||
22540 | @item @var{stride} | |
22541 | Specifies the byte offset between consecutive generic vertex attributes. | |
22542 | If @var{stride} is 0, the generic vertex attributes are understood to be | |
f37e7e3d | 22543 | tightly packed in the array. The initial value is 0. |
8925f36f AW |
22544 | |
22545 | @item @var{pointer} | |
22546 | Specifies a pointer to the first component of the first generic vertex | |
f37e7e3d | 22547 | attribute in the array. The initial value is 0. |
8925f36f AW |
22548 | |
22549 | @end table | |
22550 | ||
8925f36f AW |
22551 | @code{glVertexAttribPointer} specifies the location and data format of |
22552 | the array of generic vertex attributes at index @var{index} to use when | |
f37e7e3d DH |
22553 | rendering. @var{size} specifies the number of components per attribute |
22554 | and must be 1, 2, 3, or 4. @var{type} specifies the data type of each | |
8925f36f AW |
22555 | component, and @var{stride} specifies the byte stride from one attribute |
22556 | to the next, allowing vertices and attributes to be packed into a single | |
f37e7e3d | 22557 | array or stored in separate arrays. If set to @code{GL_TRUE}, |
8925f36f AW |
22558 | @var{normalized} indicates that values stored in an integer format are |
22559 | to be mapped to the range [-1,1] (for signed values) or [0,1] (for | |
22560 | unsigned values) when they are accessed and converted to floating point. | |
22561 | Otherwise, values will be converted to floats directly without | |
22562 | normalization. | |
22563 | ||
22564 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
22565 | target (see @code{glBindBuffer}) while a generic vertex attribute array | |
22566 | is specified, @var{pointer} is treated as a byte offset into the buffer | |
f37e7e3d | 22567 | object's data store. Also, the buffer object binding |
8925f36f AW |
22568 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as generic vertex attribute |
22569 | array client-side state (@code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING}) | |
22570 | for index @var{index}. | |
22571 | ||
22572 | When a generic vertex attribute array is specified, @var{size}, | |
22573 | @var{type}, @var{normalized}, @var{stride}, and @var{pointer} are saved | |
22574 | as client-side state, in addition to the current vertex array buffer | |
22575 | object binding. | |
22576 | ||
22577 | To enable and disable a generic vertex attribute array, call | |
22578 | @code{glEnableVertexAttribArray} and @code{glDisableVertexAttribArray} | |
f37e7e3d DH |
22579 | with @var{index}. If enabled, the generic vertex attribute array is used |
22580 | when @code{glArrayElement}, @code{glDrawArrays}, | |
8925f36f AW |
22581 | @code{glMultiDrawArrays}, @code{glDrawElements}, |
22582 | @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called. | |
22583 | ||
8925f36f AW |
22584 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
22585 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
22586 | ||
22587 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4. | |
22588 | ||
22589 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
22590 | value. | |
22591 | ||
22592 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
22593 | ||
bb894c9d AW |
22594 | @end deftypefun |
22595 | ||
ca09631c AW |
22596 | @deftypefun void glVertexAttrib1f index v0 |
22597 | @deftypefunx void glVertexAttrib1s index v0 | |
d172eed9 | 22598 | @deftypefunx void glVertexAttrib1d index v0 |
ca09631c | 22599 | @deftypefunx void glVertexAttrib2f index v0 v1 |
bb894c9d | 22600 | @deftypefunx void glVertexAttrib2s index v0 v1 |
d172eed9 | 22601 | @deftypefunx void glVertexAttrib2d index v0 v1 |
ca09631c | 22602 | @deftypefunx void glVertexAttrib3f index v0 v1 v2 |
bb894c9d | 22603 | @deftypefunx void glVertexAttrib3s index v0 v1 v2 |
d172eed9 | 22604 | @deftypefunx void glVertexAttrib3d index v0 v1 v2 |
ca09631c | 22605 | @deftypefunx void glVertexAttrib4f index v0 v1 v2 v3 |
bb894c9d | 22606 | @deftypefunx void glVertexAttrib4s index v0 v1 v2 v3 |
d172eed9 | 22607 | @deftypefunx void glVertexAttrib4d index v0 v1 v2 v3 |
bb894c9d | 22608 | @deftypefunx void glVertexAttrib4Nub index v0 v1 v2 v3 |
d172eed9 AW |
22609 | @deftypefunx void glVertexAttrib1fv index v |
22610 | @deftypefunx void glVertexAttrib1sv index v | |
22611 | @deftypefunx void glVertexAttrib1dv index v | |
22612 | @deftypefunx void glVertexAttrib2fv index v | |
22613 | @deftypefunx void glVertexAttrib2sv index v | |
22614 | @deftypefunx void glVertexAttrib2dv index v | |
22615 | @deftypefunx void glVertexAttrib3fv index v | |
22616 | @deftypefunx void glVertexAttrib3sv index v | |
22617 | @deftypefunx void glVertexAttrib3dv index v | |
22618 | @deftypefunx void glVertexAttrib4fv index v | |
22619 | @deftypefunx void glVertexAttrib4sv index v | |
22620 | @deftypefunx void glVertexAttrib4dv index v | |
b002944d | 22621 | @deftypefunx void glVertexAttrib4iv index v |
d172eed9 AW |
22622 | @deftypefunx void glVertexAttrib4bv index v |
22623 | @deftypefunx void glVertexAttrib4ubv index v | |
22624 | @deftypefunx void glVertexAttrib4usv index v | |
b002944d | 22625 | @deftypefunx void glVertexAttrib4uiv index v |
d172eed9 AW |
22626 | @deftypefunx void glVertexAttrib4Nbv index v |
22627 | @deftypefunx void glVertexAttrib4Nsv index v | |
b002944d | 22628 | @deftypefunx void glVertexAttrib4Niv index v |
d172eed9 AW |
22629 | @deftypefunx void glVertexAttrib4Nubv index v |
22630 | @deftypefunx void glVertexAttrib4Nusv index v | |
b002944d | 22631 | @deftypefunx void glVertexAttrib4Nuiv index v |
3c9b6116 AW |
22632 | Specifies the value of a generic vertex attribute. |
22633 | ||
8925f36f AW |
22634 | @table @asis |
22635 | @item @var{index} | |
22636 | Specifies the index of the generic vertex attribute to be modified. | |
22637 | ||
22638 | @item @var{v0}, @var{v1}, @var{v2}, @var{v3} | |
22639 | Specifies the new values to be used for the specified vertex attribute. | |
22640 | ||
22641 | @end table | |
22642 | ||
8925f36f AW |
22643 | OpenGL defines a number of standard vertex attributes that applications |
22644 | can modify with standard API entry points (color, normal, texture | |
f37e7e3d | 22645 | coordinates, etc.). The @code{glVertexAttrib} family of entry points |
8925f36f AW |
22646 | allows an application to pass generic vertex attributes in numbered |
22647 | locations. | |
22648 | ||
22649 | Generic attributes are defined as four-component values that are | |
f37e7e3d | 22650 | organized into an array. The first entry of this array is numbered 0, |
8925f36f | 22651 | and the size of the array is specified by the implementation-dependent |
f37e7e3d DH |
22652 | constant @code{GL_MAX_VERTEX_ATTRIBS}. Individual elements of this array |
22653 | can be modified with a @code{glVertexAttrib} call that specifies the | |
22654 | index of the element to be modified and a value for that element. | |
8925f36f AW |
22655 | |
22656 | These commands can be used to specify one, two, three, or all four | |
f37e7e3d | 22657 | components of the generic vertex attribute specified by @var{index}. A |
8925f36f AW |
22658 | @code{1} in the name of the command indicates that only one value is |
22659 | passed, and it will be used to modify the first component of the generic | |
f37e7e3d DH |
22660 | vertex attribute. The second and third components will be set to 0, and |
22661 | the fourth component will be set to 1. Similarly, a @code{2} in the name | |
22662 | of the command indicates that values are provided for the first two | |
8925f36f | 22663 | components, the third component will be set to 0, and the fourth |
f37e7e3d | 22664 | component will be set to 1. A @code{3} in the name of the command |
8925f36f AW |
22665 | indicates that values are provided for the first three components and |
22666 | the fourth component will be set to 1, whereas a @code{4} in the name | |
22667 | indicates that values are provided for all four components. | |
22668 | ||
22669 | The letters @code{s}, @code{f}, @code{i}, @code{d}, @code{ub}, | |
22670 | @code{us}, and @code{ui} indicate whether the arguments are of type | |
22671 | short, float, int, double, unsigned byte, unsigned short, or unsigned | |
f37e7e3d DH |
22672 | int. When @code{v} is appended to the name, the commands can take a |
22673 | pointer to an array of such values. The commands containing @code{N} | |
8925f36f AW |
22674 | indicate that the arguments will be passed as fixed-point values that |
22675 | are scaled to a normalized range according to the component conversion | |
f37e7e3d | 22676 | rules defined by the OpenGL specification. Signed values are understood |
8925f36f AW |
22677 | to represent fixed-point values in the range [-1,1], and unsigned values |
22678 | are understood to represent fixed-point values in the range [0,1]. | |
22679 | ||
22680 | OpenGL Shading Language attribute variables are allowed to be of type | |
f37e7e3d DH |
22681 | mat2, mat3, or mat4. Attributes of these types may be loaded using the |
22682 | @code{glVertexAttrib} entry points. Matrices must be loaded into | |
8925f36f AW |
22683 | successive generic attribute slots in column major order, with one |
22684 | column of the matrix in each generic attribute slot. | |
22685 | ||
22686 | A user-defined attribute variable declared in a vertex shader can be | |
22687 | bound to a generic attribute index by calling | |
f37e7e3d DH |
22688 | @code{glBindAttribLocation}. This allows an application to use more |
22689 | descriptive variable names in a vertex shader. A subsequent change to | |
8925f36f AW |
22690 | the specified generic vertex attribute will be immediately reflected as |
22691 | a change to the corresponding attribute variable in the vertex shader. | |
22692 | ||
22693 | The binding between a generic vertex attribute index and a user-defined | |
22694 | attribute variable in a vertex shader is part of the state of a program | |
22695 | object, but the current value of the generic vertex attribute is not. | |
22696 | The value of each generic vertex attribute is part of current state, | |
22697 | just like standard vertex attributes, and it is maintained even if a | |
22698 | different program object is used. | |
22699 | ||
22700 | An application may freely modify generic vertex attributes that are not | |
f37e7e3d | 22701 | bound to a named vertex shader attribute variable. These values are |
8925f36f | 22702 | simply maintained as part of current state and will not be accessed by |
f37e7e3d | 22703 | the vertex shader. If a generic vertex attribute bound to an attribute |
8925f36f AW |
22704 | variable in a vertex shader is not updated while the vertex shader is |
22705 | executing, the vertex shader will repeatedly use the current value for | |
22706 | the generic vertex attribute. | |
22707 | ||
22708 | The generic vertex attribute with index 0 is the same as the vertex | |
f37e7e3d | 22709 | position attribute previously defined by OpenGL. A @code{glVertex2}, |
8925f36f AW |
22710 | @code{glVertex3}, or @code{glVertex4} command is completely equivalent |
22711 | to the corresponding @code{glVertexAttrib} command with an index | |
f37e7e3d DH |
22712 | argument of 0. A vertex shader can access generic vertex attribute 0 by |
22713 | using the built-in attribute variable @var{gl_Vertex}. There are no | |
22714 | current values for generic vertex attribute 0. This is the only generic | |
8925f36f AW |
22715 | vertex attribute with this property; calls to set other standard vertex |
22716 | attributes can be freely mixed with calls to set any of the other | |
22717 | generic vertex attributes. | |
22718 | ||
8925f36f AW |
22719 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
22720 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
22721 | ||
bb894c9d | 22722 | @end deftypefun |
8925f36f | 22723 | |
bb894c9d | 22724 | @deftypefun void glVertexPointer size type stride pointer |
3c9b6116 AW |
22725 | Define an array of vertex data. |
22726 | ||
8925f36f AW |
22727 | @table @asis |
22728 | @item @var{size} | |
f37e7e3d | 22729 | Specifies the number of coordinates per vertex. Must be 2, 3, or 4. The |
8925f36f AW |
22730 | initial value is 4. |
22731 | ||
22732 | @item @var{type} | |
f37e7e3d | 22733 | Specifies the data type of each coordinate in the array. Symbolic |
8925f36f | 22734 | constants @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or |
f37e7e3d | 22735 | @code{GL_DOUBLE} are accepted. The initial value is @code{GL_FLOAT}. |
8925f36f AW |
22736 | |
22737 | @item @var{stride} | |
f37e7e3d DH |
22738 | Specifies the byte offset between consecutive vertices. If @var{stride} |
22739 | is 0, the vertices are understood to be tightly packed in the array. The | |
8925f36f AW |
22740 | initial value is 0. |
22741 | ||
22742 | @item @var{pointer} | |
22743 | Specifies a pointer to the first coordinate of the first vertex in the | |
f37e7e3d | 22744 | array. The initial value is 0. |
8925f36f AW |
22745 | |
22746 | @end table | |
22747 | ||
8925f36f | 22748 | @code{glVertexPointer} specifies the location and data format of an |
f37e7e3d DH |
22749 | array of vertex coordinates to use when rendering. @var{size} specifies |
22750 | the number of coordinates per vertex, and must be 2, 3, or 4. @var{type} | |
8925f36f AW |
22751 | specifies the data type of each coordinate, and @var{stride} specifies |
22752 | the byte stride from one vertex to the next, allowing vertices and | |
22753 | attributes to be packed into a single array or stored in separate | |
f37e7e3d | 22754 | arrays. (Single-array storage may be more efficient on some |
8925f36f AW |
22755 | implementations; see @code{glInterleavedArrays}.) |
22756 | ||
22757 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
22758 | target (see @code{glBindBuffer}) while a vertex array is specified, | |
22759 | @var{pointer} is treated as a byte offset into the buffer object's data | |
f37e7e3d | 22760 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) |
8925f36f AW |
22761 | is saved as vertex array client-side state |
22762 | (@code{GL_VERTEX_ARRAY_BUFFER_BINDING}). | |
22763 | ||
22764 | When a vertex array is specified, @var{size}, @var{type}, @var{stride}, | |
22765 | and @var{pointer} are saved as client-side state, in addition to the | |
22766 | current vertex array buffer object binding. | |
22767 | ||
22768 | To enable and disable the vertex array, call @code{glEnableClientState} | |
22769 | and @code{glDisableClientState} with the argument | |
f37e7e3d | 22770 | @code{GL_VERTEX_ARRAY}. If enabled, the vertex array is used when |
8925f36f AW |
22771 | @code{glArrayElement}, @code{glDrawArrays}, @code{glMultiDrawArrays}, |
22772 | @code{glDrawElements}, @code{glMultiDrawElements}, or | |
22773 | @code{glDrawRangeElements} is called. | |
22774 | ||
8925f36f AW |
22775 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 2, 3, or 4. |
22776 | ||
22777 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
22778 | value. | |
22779 | ||
22780 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
22781 | ||
bb894c9d | 22782 | @end deftypefun |
8925f36f | 22783 | |
d172eed9 AW |
22784 | @deftypefun void glVertex2s x y |
22785 | @deftypefunx void glVertex2i x y | |
ca09631c | 22786 | @deftypefunx void glVertex2f x y |
d172eed9 AW |
22787 | @deftypefunx void glVertex2d x y |
22788 | @deftypefunx void glVertex3s x y z | |
bb894c9d | 22789 | @deftypefunx void glVertex3i x y z |
ca09631c | 22790 | @deftypefunx void glVertex3f x y z |
d172eed9 AW |
22791 | @deftypefunx void glVertex3d x y z |
22792 | @deftypefunx void glVertex4s x y z w | |
bb894c9d | 22793 | @deftypefunx void glVertex4i x y z w |
ca09631c | 22794 | @deftypefunx void glVertex4f x y z w |
d172eed9 AW |
22795 | @deftypefunx void glVertex4d x y z w |
22796 | @deftypefunx void glVertex2sv v | |
22797 | @deftypefunx void glVertex2iv v | |
22798 | @deftypefunx void glVertex2fv v | |
22799 | @deftypefunx void glVertex2dv v | |
22800 | @deftypefunx void glVertex3sv v | |
22801 | @deftypefunx void glVertex3iv v | |
22802 | @deftypefunx void glVertex3fv v | |
22803 | @deftypefunx void glVertex3dv v | |
22804 | @deftypefunx void glVertex4sv v | |
22805 | @deftypefunx void glVertex4iv v | |
22806 | @deftypefunx void glVertex4fv v | |
22807 | @deftypefunx void glVertex4dv v | |
3c9b6116 AW |
22808 | Specify a vertex. |
22809 | ||
8925f36f AW |
22810 | @table @asis |
22811 | @item @var{x} | |
22812 | @itemx @var{y} | |
22813 | @itemx @var{z} | |
22814 | @itemx @var{w} | |
22815 | Specify @var{x}, @var{y}, @var{z}, and @var{w} coordinates of a vertex. | |
22816 | Not all parameters are present in all forms of the command. | |
22817 | ||
22818 | @end table | |
22819 | ||
8925f36f | 22820 | @code{glVertex} commands are used within @code{glBegin}/@code{glEnd} |
f37e7e3d | 22821 | pairs to specify point, line, and polygon vertices. The current color, |
8925f36f AW |
22822 | normal, texture coordinates, and fog coordinate are associated with the |
22823 | vertex when @code{glVertex} is called. | |
22824 | ||
3c9b6116 | 22825 | When only @r{@var{x}} and @r{@var{y}} are specified, @r{@var{z}} |
f37e7e3d | 22826 | defaults to 0 and @r{@var{w}} defaults to 1. When @r{@var{x}}, |
3c9b6116 | 22827 | @r{@var{y}}, and @r{@var{z}} are specified, @r{@var{w}} defaults to 1. |
8925f36f | 22828 | |
bb894c9d | 22829 | @end deftypefun |
8925f36f | 22830 | |
bb894c9d | 22831 | @deftypefun void glViewport x y width height |
3c9b6116 AW |
22832 | Set the viewport. |
22833 | ||
8925f36f AW |
22834 | @table @asis |
22835 | @item @var{x} | |
22836 | @itemx @var{y} | |
f37e7e3d | 22837 | Specify the lower left corner of the viewport rectangle, in pixels. The |
8925f36f AW |
22838 | initial value is (0,0). |
22839 | ||
22840 | @item @var{width} | |
22841 | @itemx @var{height} | |
f37e7e3d DH |
22842 | Specify the width and height of the viewport. When a GL context is first |
22843 | attached to a window, @var{width} and @var{height} are set to the | |
8925f36f AW |
22844 | dimensions of that window. |
22845 | ||
22846 | @end table | |
22847 | ||
3c9b6116 AW |
22848 | @code{glViewport} specifies the affine transformation of @r{@var{x}} and |
22849 | @r{@var{y}} from normalized device coordinates to window coordinates. | |
22850 | Let @r{(@var{x}_@var{nd},@var{y}_@var{nd})} be normalized device | |
f37e7e3d | 22851 | coordinates. Then the window coordinates |
3c9b6116 | 22852 | @r{(@var{x}_@var{w},@var{y}_@var{w})} are computed as follows: |
8925f36f | 22853 | |
3c9b6116 | 22854 | @r{@var{x}_@var{w}=(@var{x}_@var{nd}+1,)(@var{width}/2,)+@var{x}} |
8925f36f | 22855 | |
3c9b6116 | 22856 | @r{@var{y}_@var{w}=(@var{y}_@var{nd}+1,)(@var{height}/2,)+@var{y}} |
8925f36f AW |
22857 | |
22858 | Viewport width and height are silently clamped to a range that depends | |
f37e7e3d | 22859 | on the implementation. To query this range, call @code{glGet} with |
8925f36f AW |
22860 | argument @code{GL_MAX_VIEWPORT_DIMS}. |
22861 | ||
8925f36f AW |
22862 | @code{GL_INVALID_VALUE} is generated if either @var{width} or |
22863 | @var{height} is negative. | |
22864 | ||
22865 | @code{GL_INVALID_OPERATION} is generated if @code{glViewport} is | |
22866 | executed between the execution of @code{glBegin} and the corresponding | |
22867 | execution of @code{glEnd}. | |
22868 | ||
bb894c9d | 22869 | @end deftypefun |
8925f36f | 22870 | |
d172eed9 AW |
22871 | @deftypefun void glWindowPos2s x y |
22872 | @deftypefunx void glWindowPos2i x y | |
ca09631c | 22873 | @deftypefunx void glWindowPos2f x y |
d172eed9 AW |
22874 | @deftypefunx void glWindowPos2d x y |
22875 | @deftypefunx void glWindowPos3s x y z | |
bb894c9d | 22876 | @deftypefunx void glWindowPos3i x y z |
ca09631c | 22877 | @deftypefunx void glWindowPos3f x y z |
d172eed9 AW |
22878 | @deftypefunx void glWindowPos3d x y z |
22879 | @deftypefunx void glWindowPos2sv v | |
22880 | @deftypefunx void glWindowPos2iv v | |
22881 | @deftypefunx void glWindowPos2fv v | |
22882 | @deftypefunx void glWindowPos2dv v | |
22883 | @deftypefunx void glWindowPos3sv v | |
22884 | @deftypefunx void glWindowPos3iv v | |
22885 | @deftypefunx void glWindowPos3fv v | |
22886 | @deftypefunx void glWindowPos3dv v | |
3c9b6116 AW |
22887 | Specify the raster position in window coordinates for pixel operations. |
22888 | ||
8925f36f AW |
22889 | @table @asis |
22890 | @item @var{x} | |
22891 | @itemx @var{y} | |
22892 | @itemx @var{z} | |
3c9b6116 AW |
22893 | Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}} coordinates for the |
22894 | raster position. | |
8925f36f AW |
22895 | |
22896 | @end table | |
22897 | ||
f37e7e3d | 22898 | The GL maintains a 3D position in window coordinates. This position, |
8925f36f | 22899 | called the raster position, is used to position pixel and bitmap write |
f37e7e3d | 22900 | operations. It is maintained with subpixel accuracy. See |
8925f36f AW |
22901 | @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}. |
22902 | ||
3c9b6116 AW |
22903 | @code{glWindowPos2} specifies the @r{@var{x}} and @r{@var{y}} |
22904 | coordinates, while @r{@var{z}} is implicitly set to 0. | |
f37e7e3d | 22905 | @code{glWindowPos3} specifies all three coordinates. The @r{@var{w}} |
8925f36f AW |
22906 | coordinate of the current raster position is always set to 1.0. |
22907 | ||
3c9b6116 AW |
22908 | @code{glWindowPos} directly updates the @r{@var{x}} and @r{@var{y}} |
22909 | coordinates of the current raster position with the values specified. | |
22910 | That is, the values are neither transformed by the current modelview and | |
f37e7e3d | 22911 | projection matrices, nor by the viewport-to-window transform. The |
3c9b6116 AW |
22912 | @r{@var{z}} coordinate of the current raster position is updated in the |
22913 | following manner: | |
8925f36f | 22914 | |
3c9b6116 | 22915 | @r{@var{z}=@{(@var{n}), (@var{f}), |
8925f36f AW |
22916 | (@var{n}+@var{z}×(@var{f}-@var{n},),)(@var{if}@var{z}<=0), |
22917 | (@var{if}@var{z}>=1), (@code{otherwise},),} | |
22918 | ||
22919 | ||
22920 | ||
3c9b6116 | 22921 | where @r{@var{n}} is @code{GL_DEPTH_RANGE}'s near value, and @r{@var{f}} |
f37e7e3d | 22922 | is @code{GL_DEPTH_RANGE}'s far value. See @code{glDepthRange}. |
8925f36f AW |
22923 | |
22924 | The specified coordinates are not clip-tested, causing the raster | |
22925 | position to always be valid. | |
22926 | ||
22927 | The current raster position also includes some associated color data and | |
f37e7e3d | 22928 | texture coordinates. If lighting is enabled, then |
8925f36f AW |
22929 | @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or |
22930 | @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color | |
22931 | produced by the lighting calculation (see @code{glLight}, | |
f37e7e3d | 22932 | @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled, |
8925f36f AW |
22933 | current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or |
22934 | color index (in color index mode, state variable | |
22935 | @code{GL_CURRENT_INDEX}) is used to update the current raster color. | |
22936 | @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise | |
22937 | updated. | |
22938 | ||
22939 | Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a | |
22940 | function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture | |
f37e7e3d | 22941 | matrix and the texture generation functions (see @code{glTexGen}). The |
8925f36f AW |
22942 | @code{GL_CURRENT_RASTER_DISTANCE} is set to the |
22943 | @code{GL_CURRENT_FOG_COORD}. | |
22944 | ||
22945 | ||
22946 | ||
8925f36f AW |
22947 | @code{GL_INVALID_OPERATION} is generated if @code{glWindowPos} is |
22948 | executed between the execution of @code{glBegin} and the corresponding | |
22949 | execution of @code{glEnd}. | |
22950 | ||
bb894c9d | 22951 | @end deftypefun |
8925f36f AW |
22952 | |
22953 | ||
22954 | @c %end of fragment |