HCoop / clinton / guile-figl.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
fix distcheck, make valid texinfo that can make pdfs
[clinton/guile-figl.git] / figl / low-level / glu.scm
CommitLineData
8925f36f
AW		 1;;; figl -*- mode: scheme; coding: utf-8 -*-
2;;; Copyright (C) 2013 Andy Wingo <wingo@pobox.com>
3;;;
4;;; Figl is free software: you can redistribute it and/or modify it
5;;; under the terms of the GNU Lesser General Public License as
6;;; published by the Free Software Foundation, either version 3 of the
7;;; License, or (at your option) any later version.
8;;;
9;;; Figl is distributed in the hope that it will be useful, but WITHOUT
10;;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
11;;; or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
12;;; Public License for more details.
13;;;
14;;; You should have received a copy of the GNU Lesser General Public
15;;; License along with this program. If not, see
16;;; <http://www.gnu.org/licenses/>.
17;;;
18;;; Derived from upstream OpenGL documentation.
19;;;
8925f36f
AW		 20;;; Copyright (C) 1991-2006 Silicon Graphics, Inc. This document is licensed
21;;; under the SGI Free Software B License. For details, see
22;;; http://oss.sgi.com/projects/FreeB/ (http://oss.sgi.com/projects/FreeB/).
23;;;
24;;; Automatically generated; you probably don't want to edit this. To
25;;; update, run "make update" in the top-level build tree.
26;;;
27
28(define-module
29 (figl low-level glu)
30 #:use-module
31 (figl low-level support)
32 #:export
33 (gluBeginCurve
34 gluBeginPolygon
35 gluBeginSurface
36 gluBeginTrim
37 gluBuild1DMipmapLevels
38 gluBuild1DMipmaps
39 gluBuild2DMipmapLevels
40 gluBuild2DMipmaps
41 gluBuild3DMipmapLevels
42 gluBuild3DMipmaps
43 gluCheckExtension
44 gluCylinder
45 gluDeleteNurbsRenderer
46 gluDeleteQuadric
47 gluDeleteTess
48 gluDisk
49 gluErrorString
50 gluGetNurbsProperty
51 gluGetString
52 gluGetTessProperty
53 gluLoadSamplingMatrices
54 gluLookAt
55 gluNewNurbsRenderer
56 gluNewQuadric
57 gluNewTess
58 gluNextContour
59 gluNurbsCallbackDataEXT
60 gluNurbsCallbackData
61 gluNurbsCallback
62 gluNurbsCurve
63 gluNurbsProperty
64 gluNurbsSurface
65 gluOrtho2D
66 gluPartialDisk
67 gluPerspective
68 gluPickMatrix
69 gluProject
70 gluPwlCurve
71 gluQuadricCallback
72 gluQuadricDrawStyle
73 gluQuadricNormals
74 gluQuadricOrientation
75 gluQuadricTexture
76 gluScaleImage
77 gluSphere
78 gluTessBeginContour
79 gluTessBeginPolygon
80 gluTessCallback
81 gluTessEndPolygon
82 gluTessNormal
83 gluTessProperty
84 gluTessVertex
85 gluUnProject4
86 gluUnProject))
87
88(define-gl-procedure
89 gluBeginCurve
90 "gluBeginCurve"
91 (funcsynopsis
92 (funcprototype
93 (funcdef "void " (function "gluBeginCurve"))
94 (paramdef "GLUnurbs* " (parameter "nurb"))))
3c9b6116
AW		 95 "Delimit a NURBS curve definition.
96
97NURB
98 Specifies the NURBS object (created with `gluNewNurbsRenderer').
99
100Use `gluBeginCurve' to mark the beginning of a NURBS curve definition.
101After calling `gluBeginCurve', make one or more calls to `gluNurbsCurve'
102to define the attributes of the curve. Exactly one of the calls to
103`gluNurbsCurve' must have a curve type of `GLU_MAP1_VERTEX_3' or
104`GLU_MAP1_VERTEX_4'. To mark the end of the NURBS curve definition, call
105`gluEndCurve'.
106
8925f36f 107GL evaluators are used to render the NURBS curve as a series of line
3c9b6116
AW		 108segments. Evaluator state is preserved during rendering with
109`glPushAttrib'(`GLU_EVAL_BIT') and `glPopAttrib'(). See the
110`glPushAttrib' reference page for details on exactly what state these
111calls preserve.")
8925f36f
AW		 112
113(define-gl-procedure
114 gluBeginPolygon
115 "gluBeginPolygon"
116 (funcsynopsis
117 (funcprototype
118 (funcdef "void " (function "gluBeginPolygon"))
119 (paramdef "GLUtesselator* " (parameter "tess"))))
3c9b6116
AW		 120 "Delimit a polygon description.
121
122TESS
123 Specifies the tessellation object (created with `gluNewTess').
124
125`gluBeginPolygon' and `gluEndPolygon' delimit the definition of a
126nonconvex polygon. To define such a polygon, first call
127`gluBeginPolygon'. Then define the contours of the polygon by calling
128`gluTessVertex' for each vertex and `gluNextContour' to start each new
129contour. Finally, call `gluEndPolygon' to signal the end of the
130definition. See the `gluTessVertex' and `gluNextContour' reference pages
131for more details.
132
133Once `gluEndPolygon' is called, the polygon is tessellated, and the
134resulting triangles are described through callbacks. See
135`gluTessCallback' for descriptions of the callback functions.")
8925f36f
AW		 136
137(define-gl-procedure
138 gluBeginSurface
139 "gluBeginSurface"
140 (funcsynopsis
141 (funcprototype
142 (funcdef "void " (function "gluBeginSurface"))
143 (paramdef "GLUnurbs* " (parameter "nurb"))))
3c9b6116
AW		 144 "Delimit a NURBS surface definition.
145
146NURB
147 Specifies the NURBS object (created with `gluNewNurbsRenderer').
148
149Use `gluBeginSurface' to mark the beginning of a NURBS surface
150definition. After calling `gluBeginSurface', make one or more calls to
151`gluNurbsSurface' to define the attributes of the surface. Exactly one
152of these calls to `gluNurbsSurface' must have a surface type of
153`GLU_MAP2_VERTEX_3' or `GLU_MAP2_VERTEX_4'. To mark the end of the NURBS
154surface definition, call `gluEndSurface'.
155
156Trimming of NURBS surfaces is supported with `gluBeginTrim',
157`gluPwlCurve', `gluNurbsCurve', and `gluEndTrim'. See the `gluBeginTrim'
158reference page for details.
159
8925f36f 160GL evaluators are used to render the NURBS surface as a set of polygons.
3c9b6116
AW		 161Evaluator state is preserved during rendering with
162`glPushAttrib'(`GLU_EVAL_BIT') and `glPopAttrib'. See the `glPushAttrib'
163reference page for details on exactly what state these calls preserve.")
8925f36f
AW		 164
165(define-gl-procedure
166 gluBeginTrim
167 "gluBeginTrim"
168 (funcsynopsis
169 (funcprototype
170 (funcdef "void " (function "gluBeginTrim"))
171 (paramdef "GLUnurbs* " (parameter "nurb"))))
3c9b6116
AW		 172 "Delimit a NURBS trimming loop definition.
173
174NURB
175 Specifies the NURBS object (created with `gluNewNurbsRenderer').
176
177Use `gluBeginTrim' to mark the beginning of a trimming loop and
178`gluEndTrim' to mark the end of a trimming loop. A trimming loop is a
179set of oriented curve segments (forming a closed curve) that define
180boundaries of a NURBS surface. You include these trimming loops in the
181definition of a NURBS surface, between calls to `gluBeginSurface' and
182`gluEndSurface'.
183
184The definition for a NURBS surface can contain many trimming loops. For
185example, if you wrote a definition for a NURBS surface that resembled a
186rectangle with a hole punched out, the definition would contain two
187trimming loops. One loop would define the outer edge of the rectangle;
188the other would define the hole punched out of the rectangle. The
189definitions of each of these trimming loops would be bracketed by a
190`gluBeginTrim'/`gluEndTrim' pair.
191
192The definition of a single closed trimming loop can consist of multiple
193curve segments, each described as a piecewise linear curve (see
194`gluPwlCurve') or as a single NURBS curve (see `gluNurbsCurve'), or as a
195combination of both in any order. The only library calls that can appear
196in a trimming loop definition (between the calls to `gluBeginTrim' and
197`gluEndTrim') are `gluPwlCurve' and `gluNurbsCurve'.
198
199The area of the NURBS surface that is displayed is the region in the
200domain to the left of the trimming curve as the curve parameter
201increases. Thus, the retained region of the NURBS surface is inside a
202counterclockwise trimming loop and outside a clockwise trimming loop.
203For the rectangle mentioned earlier, the trimming loop for the outer
204edge of the rectangle runs counterclockwise, while the trimming loop for
205the punched-out hole runs clockwise.
206
207If you use more than one curve to define a single trimming loop, the
208curve segments must form a closed loop (that is, the endpoint of each
209curve must be the starting point of the next curve, and the endpoint of
210the final curve must be the starting point of the first curve). If the
211endpoints of the curve are sufficiently close together but not exactly
212coincident, they will be coerced to match. If the endpoints are not
213sufficiently close, an error results (see `gluNurbsCallback').
214
215If a trimming loop definition contains multiple curves, the direction of
216the curves must be consistent (that is, the inside must be to the left
217of all of the curves). Nested trimming loops are legal as long as the
218curve orientations alternate correctly. If trimming curves are
219self-intersecting, or intersect one another, an error results.
220
221If no trimming information is given for a NURBS surface, the entire
222surface is drawn.")
8925f36f
AW		 223
224(define-gl-procedure
225 gluBuild1DMipmapLevels
226 "gluBuild1DMipmapLevels"
227 (funcsynopsis
228 (funcprototype
229 (funcdef
230 "GLint "
231 (function "gluBuild1DMipmapLevels"))
232 (paramdef "GLenum " (parameter "target"))
233 (paramdef "GLint " (parameter "internalFormat"))
234 (paramdef "GLsizei " (parameter "width"))
235 (paramdef "GLenum " (parameter "format"))
236 (paramdef "GLenum " (parameter "type"))
237 (paramdef "GLint " (parameter "level"))
238 (paramdef "GLint " (parameter "base"))
239 (paramdef "GLint " (parameter "max"))
240 (paramdef "const void * " (parameter "data"))))
3c9b6116
AW		 241 "Builds a subset of one-dimensional mipmap levels.
242
243TARGET
244 Specifies the target texture. Must be `GLU_TEXTURE_1D'.
245
246INTERNALFORMAT
247 Requests the internal storage format of the texture image. The most
248 current version of the SGI implementation of GLU does not check
249 this value for validity before passing it on to the underlying
250 OpenGL implementation. A value that is not accepted by the OpenGL
251 implementation will lead to an OpenGL error. The benefit of not
252 checking this value at the GLU level is that OpenGL extensions can
253 add new internal texture formats without requiring a revision of
254 the GLU implementation. Older implementations of GLU check this
255 value and raise a GLU error if it is not 1, 2, 3, or 4 or one of
256 the following symbolic constants: `GLU_ALPHA', `GLU_ALPHA4',
257 `GLU_ALPHA8', `GLU_ALPHA12', `GLU_ALPHA16', `GLU_LUMINANCE',
258 `GLU_LUMINANCE4', `GLU_LUMINANCE8', `GLU_LUMINANCE12',
259 `GLU_LUMINANCE16', `GLU_LUMINANCE_ALPHA', `GLU_LUMINANCE4_ALPHA4',
260 `GLU_LUMINANCE6_ALPHA2', `GLU_LUMINANCE8_ALPHA8',
261 `GLU_LUMINANCE12_ALPHA4', `GLU_LUMINANCE12_ALPHA12',
262 `GLU_LUMINANCE16_ALPHA16', `GLU_INTENSITY', `GLU_INTENSITY4',
263 `GLU_INTENSITY8', `GLU_INTENSITY12', `GLU_INTENSITY16', `GLU_RGB',
264 `GLU_R3_G3_B2', `GLU_RGB4', `GLU_RGB5', `GLU_RGB8', `GLU_RGB10',
265 `GLU_RGB12', `GLU_RGB16', `GLU_RGBA', `GLU_RGBA2', `GLU_RGBA4',
266 `GLU_RGB5_A1', `GLU_RGBA8', `GLU_RGB10_A2', `GLU_RGBA12', or
267 `GLU_RGBA16'.
268
269WIDTH
270 Specifies the width in pixels of the texture image. This should be
271 a power of 2.
272
273FORMAT
274 Specifies the format of the pixel data. Must be one of:
275 `GLU_COLOR_INDEX', `GLU_DEPTH_COMPONENT', `GLU_RED', `GLU_GREEN',
276 `GLU_BLUE', `GLU_ALPHA', `GLU_RGB', `GLU_RGBA', `GLU_BGR',
277 `GLU_BGRA', `GLU_LUMINANCE', or `GLU_LUMINANCE_ALPHA'.
278
279TYPE
280 Specifies the data type for DATA. Must be one of:
281 `GLU_UNSIGNED_BYTE', `GLU_BYTE', `GLU_BITMAP',
282 `GLU_UNSIGNED_SHORT', `GLU_SHORT', `GLU_UNSIGNED_INT', `GLU_INT',
283 `GLU_FLOAT', `GLU_UNSIGNED_BYTE_3_3_2',
284 `GLU_UNSIGNED_BYTE_2_3_3_REV', `GLU_UNSIGNED_SHORT_5_6_5',
285 `GLU_UNSIGNED_SHORT_5_6_5_REV', `GLU_UNSIGNED_SHORT_4_4_4_4',
286 `GLU_UNSIGNED_SHORT_4_4_4_4_REV', `GLU_UNSIGNED_SHORT_5_5_5_1',
287 `GLU_UNSIGNED_SHORT_1_5_5_5_REV', `GLU_UNSIGNED_INT_8_8_8_8',
288 `GLU_UNSIGNED_INT_8_8_8_8_REV', `GLU_UNSIGNED_INT_10_10_10_2', or
289 `GLU_UNSIGNED_INT_2_10_10_10_REV'.
290
291LEVEL
292 Specifies the mipmap level of the image data.
293
294BASE
295 Specifies the minimum mipmap level to pass to `glTexImage1D'.
296
297MAX
298 Specifies the maximum mipmap level to pass to `glTexImage1D'.
299
300DATA
301 Specifies a pointer to the image data in memory.
302
303`gluBuild1DMipmapLevels' builds a subset of prefiltered one-dimensional
304texture maps of decreasing resolutions called a mipmap. This is used for
305the antialiasing of texture mapped primitives.
306
8925f36f 307A return value of zero indicates success, otherwise a GLU error code is
3c9b6116
AW		 308returned (see `gluErrorString').
309
310A series of mipmap levels from BASE to MAX is built by decimating DATA
311in half until size 1×1 is reached. At each level, each texel in the
312halved mipmap level is an average of the corresponding two texels in the
313larger mipmap level. `glTexImage1D' is called to load these mipmap
314levels from BASE to MAX. If MAX is larger than the highest mipmap level
315for the texture of the specified size, then a GLU error code is returned
316(see `gluErrorString') and nothing is loaded.
317
318For example, if LEVEL is 2 and WIDTH is 16, the following levels are
319possible: 16×1 , 8×1 , 4×1 , 2×1 , 1×1 . These correspond to levels 2
320through 6 respectively. If BASE is 3 and MAX is 5, then only mipmap
321levels 8×1 , 4×1 and 2×1 are loaded. However, if MAX is 7, then an error
322is returned and nothing is loaded since MAX is larger than the highest
323mipmap level which is, in this case, 6.
324
325The highest mipmap level can be derived from the formula
326LOG_2\u2061(WIDTH×2^LEVEL,) .
327
328See the `glTexImage1D' reference page for a description of the
329acceptable values for TYPE parameter. See the `glDrawPixels' reference
330page for a description of the acceptable values for LEVEL parameter.
331
332`GLU_INVALID_VALUE' is returned if LEVEL > BASE, BASE < 0, MAX < BASE or
333MAX is > the highest mipmap level for DATA.
334
335`GLU_INVALID_VALUE' is returned if WIDTH is < 1.
336
337`GLU_INVALID_ENUM' is returned if INTERNALFORMAT, FORMAT, or TYPE are
338not legal.
339
340`GLU_INVALID_OPERATION' is returned if TYPE is `GLU_UNSIGNED_BYTE_3_3_2'
341or `GLU_UNSIGNED_BYTE_2_3_3_REV' and FORMAT is not `GLU_RGB'.
342
343`GLU_INVALID_OPERATION' is returned if TYPE is
344`GLU_UNSIGNED_SHORT_5_6_5' or `GLU_UNSIGNED_SHORT_5_6_5_REV' and FORMAT
345is not `GLU_RGB'.
346
347`GLU_INVALID_OPERATION' is returned if TYPE is
348`GLU_UNSIGNED_SHORT_4_4_4_4' or `GLU_UNSIGNED_SHORT_4_4_4_4_REV' and
349FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
350
351`GLU_INVALID_OPERATION' is returned if TYPE is
352`GLU_UNSIGNED_SHORT_5_5_5_1' or `GLU_UNSIGNED_SHORT_1_5_5_5_REV' and
353FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
354
355`GLU_INVALID_OPERATION' is returned if TYPE is
356`GLU_UNSIGNED_INT_8_8_8_8' or `GLU_UNSIGNED_INT_8_8_8_8_REV' and FORMAT
357is neither `GLU_RGBA' nor `GLU_BGRA'.
358
359`GLU_INVALID_OPERATION' is returned if TYPE is
360`GLU_UNSIGNED_INT_10_10_10_2' or `GLU_UNSIGNED_INT_2_10_10_10_REV' and
361FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.")
8925f36f
AW		 362
363(define-gl-procedure
364 gluBuild1DMipmaps
365 "gluBuild1DMipmaps"
366 (funcsynopsis
367 (funcprototype
368 (funcdef "GLint " (function "gluBuild1DMipmaps"))
369 (paramdef "GLenum " (parameter "target"))
370 (paramdef "GLint " (parameter "internalFormat"))
371 (paramdef "GLsizei " (parameter "width"))
372 (paramdef "GLenum " (parameter "format"))
373 (paramdef "GLenum " (parameter "type"))
374 (paramdef "const void * " (parameter "data"))))
3c9b6116
AW		 375 "Builds a one-dimensional mipmap.
376
377TARGET
378 Specifies the target texture. Must be `GLU_TEXTURE_1D'.
379
380INTERNALFORMAT
381 Requests the internal storage format of the texture image. The most
382 current version of the SGI implementation of GLU does not check
383 this value for validity before passing it on to the underlying
384 OpenGL implementation. A value that is not accepted by the OpenGL
385 implementation will lead to an OpenGL error. The benefit of not
386 checking this value at the GLU level is that OpenGL extensions can
387 add new internal texture formats without requiring a revision of
388 the GLU implementation. Older implementations of GLU check this
389 value and raise a GLU error if it is not 1, 2, 3, or 4 or one of
390 the following symbolic constants: `GLU_ALPHA', `GLU_ALPHA4',
391 `GLU_ALPHA8', `GLU_ALPHA12', `GLU_ALPHA16', `GLU_LUMINANCE',
392 `GLU_LUMINANCE4', `GLU_LUMINANCE8', `GLU_LUMINANCE12',
393 `GLU_LUMINANCE16', `GLU_LUMINANCE_ALPHA', `GLU_LUMINANCE4_ALPHA4',
394 `GLU_LUMINANCE6_ALPHA2', `GLU_LUMINANCE8_ALPHA8',
395 `GLU_LUMINANCE12_ALPHA4', `GLU_LUMINANCE12_ALPHA12',
396 `GLU_LUMINANCE16_ALPHA16', `GLU_INTENSITY', `GLU_INTENSITY4',
397 `GLU_INTENSITY8', `GLU_INTENSITY12', `GLU_INTENSITY16', `GLU_RGB',
398 `GLU_R3_G3_B2', `GLU_RGB4', `GLU_RGB5', `GLU_RGB8', `GLU_RGB10',
399 `GLU_RGB12', `GLU_RGB16', `GLU_RGBA', `GLU_RGBA2', `GLU_RGBA4',
400 `GLU_RGB5_A1', `GLU_RGBA8', `GLU_RGB10_A2', `GLU_RGBA12', or
401 `GLU_RGBA16'.
402
403WIDTH
404 Specifies the width, in pixels, of the texture image.
405
406FORMAT
407 Specifies the format of the pixel data. Must be one of
408 `GLU_COLOR_INDEX', `GLU_DEPTH_COMPONENT', `GLU_RED', `GLU_GREEN',
409 `GLU_BLUE', `GLU_ALPHA', `GLU_RGB', `GLU_RGBA', `GLU_BGR',
410 `GLU_BGRA', `GLU_LUMINANCE', or `GLU_LUMINANCE_ALPHA'.
411
412TYPE
413 Specifies the data type for DATA. Must be one of
414 `GLU_UNSIGNED_BYTE', `GLU_BYTE', `GLU_BITMAP',
415 `GLU_UNSIGNED_SHORT', `GLU_SHORT', `GLU_UNSIGNED_INT', `GLU_INT',
416 `GLU_FLOAT', `GLU_UNSIGNED_BYTE_3_3_2',
417 `GLU_UNSIGNED_BYTE_2_3_3_REV', `GLU_UNSIGNED_SHORT_5_6_5',
418 `GLU_UNSIGNED_SHORT_5_6_5_REV', `GLU_UNSIGNED_SHORT_4_4_4_4',
419 `GLU_UNSIGNED_SHORT_4_4_4_4_REV', `GLU_UNSIGNED_SHORT_5_5_5_1',
420 `GLU_UNSIGNED_SHORT_1_5_5_5_REV', `GLU_UNSIGNED_INT_8_8_8_8',
421 `GLU_UNSIGNED_INT_8_8_8_8_REV', `GLU_UNSIGNED_INT_10_10_10_2', or
422 `GLU_UNSIGNED_INT_2_10_10_10_REV'.
423
424DATA
425 Specifies a pointer to the image data in memory.
426
427`gluBuild1DMipmaps' builds a series of prefiltered one-dimensional
428texture maps of decreasing resolutions called a mipmap. This is used for
429the antialiasing of texture mapped primitives.
430
8925f36f 431A return value of zero indicates success, otherwise a GLU error code is
3c9b6116
AW		 432returned (see `gluErrorString').
433
434Initially, the WIDTH of DATA is checked to see if it is a power of 2. If
435not, a copy of DATA is scaled up or down to the nearest power of 2. (If
436WIDTH is exactly between powers of 2, then the copy of DATA will scale
437upwards.) This copy will be used for subsequent mipmapping operations
438described below. For example, if WIDTH is 57, then a copy of DATA will
439scale up to 64 before mipmapping takes place.
440
441Then, proxy textures (see `glTexImage1D') are used to determine if the
442implementation can fit the requested texture. If not, WIDTH is
443continually halved until it fits.
444
445Next, a series of mipmap levels is built by decimating a copy of DATA in
446half until size 1×1 is reached. At each level, each texel in the halved
447mipmap level is an average of the corresponding two texels in the larger
448mipmap level.
449
450`glTexImage1D' is called to load each of these mipmap levels. Level 0 is
451a copy of DATA. The highest level is LOG_2,\u2061(WIDTH,) . For example, if
452WIDTH is 64 and the implementation can store a texture of this size, the
453following mipmap levels are built: 64×1 , 32×1 , 16×1 , 8×1 , 4×1 , 2×1
454, and 1×1 . These correspond to levels 0 through 6, respectively.
455
456See the `glTexImage1D' reference page for a description of the
457acceptable values for the TYPE parameter. See the `glDrawPixels'
458reference page for a description of the acceptable values for the DATA
459parameter.
460
461`GLU_INVALID_VALUE' is returned if WIDTH is < 1.
462
463`GLU_INVALID_ENUM' is returned if FORMAT or TYPE are not legal.
464
465`GLU_INVALID_OPERATION' is returned if TYPE is `GLU_UNSIGNED_BYTE_3_3_2'
466or `GLU_UNSIGNED_BYTE_2_3_3_REV' and FORMAT is not `GLU_RGB'.
467
468`GLU_INVALID_OPERATION' is returned if TYPE is
469`GLU_UNSIGNED_SHORT_5_6_5' or `GLU_UNSIGNED_SHORT_5_6_5_REV' and FORMAT
470is not `GLU_RGB'.
471
472`GLU_INVALID_OPERATION' is returned if TYPE is
473`GLU_UNSIGNED_SHORT_4_4_4_4' or `GLU_UNSIGNED_SHORT_4_4_4_4_REV' and
474FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
475
476`GLU_INVALID_OPERATION' is returned if TYPE is
477`GLU_UNSIGNED_SHORT_5_5_5_1' or `GLU_UNSIGNED_SHORT_1_5_5_5_REV' and
478FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
479
480`GLU_INVALID_OPERATION' is returned if TYPE is
481`GLU_UNSIGNED_INT_8_8_8_8' or `GLU_UNSIGNED_INT_8_8_8_8_REV' and FORMAT
482is neither `GLU_RGBA' nor `GLU_BGRA'.
483
484`GLU_INVALID_OPERATION' is returned if TYPE is
485`GLU_UNSIGNED_INT_10_10_10_2' or `GLU_UNSIGNED_INT_2_10_10_10_REV' and
486FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.")
8925f36f
AW		 487
488(define-gl-procedure
489 gluBuild2DMipmapLevels
490 "gluBuild2DMipmapLevels"
491 (funcsynopsis
492 (funcprototype
493 (funcdef
494 "GLint "
495 (function "gluBuild2DMipmapLevels"))
496 (paramdef "GLenum " (parameter "target"))
497 (paramdef "GLint " (parameter "internalFormat"))
498 (paramdef "GLsizei " (parameter "width"))
499 (paramdef "GLsizei " (parameter "height"))
500 (paramdef "GLenum " (parameter "format"))
501 (paramdef "GLenum " (parameter "type"))
502 (paramdef "GLint " (parameter "level"))
503 (paramdef "GLint " (parameter "base"))
504 (paramdef "GLint " (parameter "max"))
505 (paramdef "const void * " (parameter "data"))))
3c9b6116
AW		 506 "Builds a subset of two-dimensional mipmap levels.
507
508TARGET
509 Specifies the target texture. Must be `GLU_TEXTURE_2D'.
510
511INTERNALFORMAT
512 Requests the internal storage format of the texture image. The most
513 current version of the SGI implementation of GLU does not check
514 this value for validity before passing it on to the underlying
515 OpenGL implementation. A value that is not accepted by the OpenGL
516 implementation will lead to an OpenGL error. The benefit of not
517 checking this value at the GLU level is that OpenGL extensions can
518 add new internal texture formats without requiring a revision of
519 the GLU implementation. Older implementations of GLU check this
520 value and raise a GLU error if it is not 1, 2, 3, or 4 or one of
521 the following symbolic constants: `GLU_ALPHA', `GLU_ALPHA4',
522 `GLU_ALPHA8', `GLU_ALPHA12', `GLU_ALPHA16', `GLU_LUMINANCE',
523 `GLU_LUMINANCE4', `GLU_LUMINANCE8', `GLU_LUMINANCE12',
524 `GLU_LUMINANCE16', `GLU_LUMINANCE_ALPHA', `GLU_LUMINANCE4_ALPHA4',
525 `GLU_LUMINANCE6_ALPHA2', `GLU_LUMINANCE8_ALPHA8',
526 `GLU_LUMINANCE12_ALPHA4', `GLU_LUMINANCE12_ALPHA12',
527 `GLU_LUMINANCE16_ALPHA16', `GLU_INTENSITY', `GLU_INTENSITY4',
528 `GLU_INTENSITY8', `GLU_INTENSITY12', `GLU_INTENSITY16', `GLU_RGB',
529 `GLU_R3_G3_B2', `GLU_RGB4', `GLU_RGB5', `GLU_RGB8', `GLU_RGB10',
530 `GLU_RGB12', `GLU_RGB16', `GLU_RGBA', `GLU_RGBA2', `GLU_RGBA4',
531 `GLU_RGB5_A1', `GLU_RGBA8', `GLU_RGB10_A2', `GLU_RGBA12', or
532 `GLU_RGBA16'.
533
534WIDTH
535 HEIGHT
536
537 Specifies the width and height, respectively, in pixels of the
538 texture image. These should be a power of 2.
539
540FORMAT
541 Specifies the format of the pixel data. Must be one of
542 `GLU_COLOR_INDEX', `GLU_DEPTH_COMPONENT', `GLU_RED', `GLU_GREEN',
543 `GLU_BLUE', `GLU_ALPHA', `GLU_RGB', `GLU_RGBA', `GLU_BGR',
544 `GLU_BGRA', `GLU_LUMINANCE', or `GLU_LUMINANCE_ALPHA'.
545
546TYPE
547 Specifies the data type for DATA. Must be one of
548 `GLU_UNSIGNED_BYTE', `GLU_BYTE', `GLU_BITMAP',
549 `GLU_UNSIGNED_SHORT', `GLU_SHORT', `GLU_UNSIGNED_INT', `GLU_INT',
550 `GLU_FLOAT', `GLU_UNSIGNED_BYTE_3_3_2',
551 `GLU_UNSIGNED_BYTE_2_3_3_REV', `GLU_UNSIGNED_SHORT_5_6_5',
552 `GLU_UNSIGNED_SHORT_5_6_5_REV', `GLU_UNSIGNED_SHORT_4_4_4_4',
553 `GLU_UNSIGNED_SHORT_4_4_4_4_REV', `GLU_UNSIGNED_SHORT_5_5_5_1',
554 `GLU_UNSIGNED_SHORT_1_5_5_5_REV', `GLU_UNSIGNED_INT_8_8_8_8',
555 `GLU_UNSIGNED_INT_8_8_8_8_REV', `GLU_UNSIGNED_INT_10_10_10_2', or
556 `GLU_UNSIGNED_INT_2_10_10_10_REV'.
557
558LEVEL
559 Specifies the mipmap level of the image data.
560
561BASE
562 Specifies the minimum mipmap level to pass to `glTexImage2D'.
563
564MAX
565 Specifies the maximum mipmap level to pass to `glTexImage2D'.
566
567DATA
568 Specifies a pointer to the image data in memory.
569
570`gluBuild2DMipmapLevels' builds a subset of prefiltered two-dimensional
571texture maps of decreasing resolutions called a mipmap. This is used for
572the antialiasing of texture mapped primitives.
573
8925f36f 574A return value of zero indicates success, otherwise a GLU error code is
3c9b6116
AW		 575returned (see `gluErrorString').
576
577A series of mipmap levels from BASE to MAX is built by decimating DATA
578in half along both dimensions until size 1×1 is reached. At each level,
579each texel in the halved mipmap level is an average of the corresponding
580four texels in the larger mipmap level. (In the case of rectangular
581images, the decimation will ultimately reach an N×1 or 1×N
582configuration. Here, two texels are averaged instead.) `glTexImage2D' is
583called to load these mipmap levels from BASE to MAX. If MAX is larger
584than the highest mipmap level for the texture of the specified size,
585then a GLU error code is returned (see `gluErrorString') and nothing is
586loaded.
587
588For example, if LEVEL is 2 and WIDTH is 16 and HEIGHT is 8, the
589following levels are possible: 16×8 , 8×4 , 4×2 , 2×1 , 1×1 . These
590correspond to levels 2 through 6 respectively. If BASE is 3 and MAX is
5915, then only mipmap levels 8×4 , 4×2 , and 2×1 are loaded. However, if
592MAX is 7, then an error is returned and nothing is loaded since MAX is
593larger than the highest mipmap level which is, in this case, 6.
594
595The highest mipmap level can be derived from the formula
596LOG_2\u2061(MAX\u2061(WIDTH,HEIGHT)×2^LEVEL,) .
597
598See the `glTexImage1D' reference page for a description of the
599acceptable values for FORMAT parameter. See the `glDrawPixels' reference
600page for a description of the acceptable values for TYPE parameter.
601
602`GLU_INVALID_VALUE' is returned if LEVEL > BASE, BASE < 0, MAX < BASE,
603or MAX is > the highest mipmap level for DATA.
604
605`GLU_INVALID_VALUE' is returned if WIDTH or HEIGHT is < 1.
606
607`GLU_INVALID_ENUM' is returned if INTERNALFORMAT, FORMAT, or TYPE is not
608legal.
609
610`GLU_INVALID_OPERATION' is returned if TYPE is `GLU_UNSIGNED_BYTE_3_3_2'
611or `GLU_UNSIGNED_BYTE_2_3_3_REV' and FORMAT is not `GLU_RGB'.
612
613`GLU_INVALID_OPERATION' is returned if TYPE is
614`GLU_UNSIGNED_SHORT_5_6_5' or `GLU_UNSIGNED_SHORT_5_6_5_REV' and FORMAT
615is not `GLU_RGB'.
616
617`GLU_INVALID_OPERATION' is returned if TYPE is
618`GLU_UNSIGNED_SHORT_4_4_4_4' or `GLU_UNSIGNED_SHORT_4_4_4_4_REV' and
619FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
620
621`GLU_INVALID_OPERATION' is returned if TYPE is
622`GLU_UNSIGNED_SHORT_5_5_5_1' or `GLU_UNSIGNED_SHORT_1_5_5_5_REV' and
623FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
624
625`GLU_INVALID_OPERATION' is returned if TYPE is
626`GLU_UNSIGNED_INT_8_8_8_8' or `GLU_UNSIGNED_INT_8_8_8_8_REV' and FORMAT
627is neither `GLU_RGBA' nor `GLU_BGRA'.
628
629`GLU_INVALID_OPERATION' is returned if TYPE is
630`GLU_UNSIGNED_INT_10_10_10_2' or `GLU_UNSIGNED_INT_2_10_10_10_REV' and
631FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.")
8925f36f
AW		 632
633(define-gl-procedure
634 gluBuild2DMipmaps
635 "gluBuild2DMipmaps"
636 (funcsynopsis
637 (funcprototype
638 (funcdef "GLint " (function "gluBuild2DMipmaps"))
639 (paramdef "GLenum " (parameter "target"))
640 (paramdef "GLint " (parameter "internalFormat"))
641 (paramdef "GLsizei " (parameter "width"))
642 (paramdef "GLsizei " (parameter "height"))
643 (paramdef "GLenum " (parameter "format"))
644 (paramdef "GLenum " (parameter "type"))
645 (paramdef "const void * " (parameter "data"))))
3c9b6116
AW		 646 "Builds a two-dimensional mipmap.
647
648TARGET
649 Specifies the target texture. Must be `GLU_TEXTURE_2D'.
650
651INTERNALFORMAT
652 Requests the internal storage format of the texture image. The most
653 current version of the SGI implementation of GLU does not check
654 this value for validity before passing it on to the underlying
655 OpenGL implementation. A value that is not accepted by the OpenGL
656 implementation will lead to an OpenGL error. The benefit of not
657 checking this value at the GLU level is that OpenGL extensions can
658 add new internal texture formats without requiring a revision of
659 the GLU implementation. Older implementations of GLU check this
660 value and raise a GLU error if it is not 1, 2, 3, or 4 or one of
661 the following symbolic constants: `GLU_ALPHA', `GLU_ALPHA4',
662 `GLU_ALPHA8', `GLU_ALPHA12', `GLU_ALPHA16', `GLU_LUMINANCE',
663 `GLU_LUMINANCE4', `GLU_LUMINANCE8', `GLU_LUMINANCE12',
664 `GLU_LUMINANCE16', `GLU_LUMINANCE_ALPHA', `GLU_LUMINANCE4_ALPHA4',
665 `GLU_LUMINANCE6_ALPHA2', `GLU_LUMINANCE8_ALPHA8',
666 `GLU_LUMINANCE12_ALPHA4', `GLU_LUMINANCE12_ALPHA12',
667 `GLU_LUMINANCE16_ALPHA16', `GLU_INTENSITY', `GLU_INTENSITY4',
668 `GLU_INTENSITY8', `GLU_INTENSITY12', `GLU_INTENSITY16', `GLU_RGB',
669 `GLU_R3_G3_B2', `GLU_RGB4', `GLU_RGB5', `GLU_RGB8', `GLU_RGB10',
670 `GLU_RGB12', `GLU_RGB16', `GLU_RGBA', `GLU_RGBA2', `GLU_RGBA4',
671 `GLU_RGB5_A1', `GLU_RGBA8', `GLU_RGB10_A2', `GLU_RGBA12', or
672 `GLU_RGBA16'.
673
674WIDTH
675 HEIGHT
676
677 Specifies in pixels the width and height, respectively, of the
678 texture image.
679
680FORMAT
681 Specifies the format of the pixel data. Must be one of
682 `GLU_COLOR_INDEX', `GLU_DEPTH_COMPONENT', `GLU_RED', `GLU_GREEN',
683 `GLU_BLUE', `GLU_ALPHA', `GLU_RGB', `GLU_RGBA', `GLU_BGR',
684 `GLU_BGRA', `GLU_LUMINANCE', or `GLU_LUMINANCE_ALPHA'.
685
686TYPE
687 Specifies the data type for DATA. Must be one of
688 `GLU_UNSIGNED_BYTE', `GLU_BYTE', `GLU_BITMAP',
689 `GLU_UNSIGNED_SHORT', `GLU_SHORT', `GLU_UNSIGNED_INT', `GLU_INT',
690 `GLU_FLOAT', `GLU_UNSIGNED_BYTE_3_3_2',
691 `GLU_UNSIGNED_BYTE_2_3_3_REV', `GLU_UNSIGNED_SHORT_5_6_5',
692 `GLU_UNSIGNED_SHORT_5_6_5_REV', `GLU_UNSIGNED_SHORT_4_4_4_4',
693 `GLU_UNSIGNED_SHORT_4_4_4_4_REV', `GLU_UNSIGNED_SHORT_5_5_5_1',
694 `GLU_UNSIGNED_SHORT_1_5_5_5_REV', `GLU_UNSIGNED_INT_8_8_8_8',
695 `GLU_UNSIGNED_INT_8_8_8_8_REV', `GLU_UNSIGNED_INT_10_10_10_2', or
696 `GLU_UNSIGNED_INT_2_10_10_10_REV'.
697
698DATA
699 Specifies a pointer to the image data in memory.
700
701`gluBuild2DMipmaps' builds a series of prefiltered two-dimensional
702texture maps of decreasing resolutions called a mipmap. This is used for
703the antialiasing of texture-mapped primitives.
704
8925f36f 705A return value of zero indicates success, otherwise a GLU error code is
3c9b6116
AW		 706returned (see `gluErrorString').
707
708Initially, the WIDTH and HEIGHT of DATA are checked to see if they are a
709power of 2. If not, a copy of DATA (not DATA), is scaled up or down to
710the nearest power of 2. This copy will be used for subsequent mipmapping
711operations described below. (If WIDTH or HEIGHT is exactly between
712powers of 2, then the copy of DATA will scale upwards.) For example, if
713WIDTH is 57 and HEIGHT is 23, then a copy of DATA will scale up to 64 in
714WIDTH and down to 16 in depth, before mipmapping takes place.
715
716Then, proxy textures (see `glTexImage2D') are used to determine if the
717implementation can fit the requested texture. If not, both dimensions
718are continually halved until it fits. (If the OpenGL version is \\(<=
7191.0, both maximum texture dimensions are clamped to the value returned
720by `glGetIntegerv' with the argument `GLU_MAX_TEXTURE_SIZE'.)
721
722Next, a series of mipmap levels is built by decimating a copy of DATA in
723half along both dimensions until size 1×1 is reached. At each level,
724each texel in the halved mipmap level is an average of the corresponding
725four texels in the larger mipmap level. (In the case of rectangular
726images, the decimation will ultimately reach an N×1 or 1×N
727configuration. Here, two texels are averaged instead.)
728
729`glTexImage2D' is called to load each of these mipmap levels. Level 0 is
730a copy of DATA. The highest level is LOG_2,\u2061(MAX\u2061(WIDTH,HEIGHT),) . For
731example, if WIDTH is 64 and HEIGHT is 16 and the implementation can
732store a texture of this size, the following mipmap levels are built:
73364×16 , 32×8 , 16×4 , 8×2 , 4×1 , 2×1 , and 1×1 These correspond to
734levels 0 through 6, respectively.
735
736See the `glTexImage1D' reference page for a description of the
737acceptable values for FORMAT parameter. See the `glDrawPixels' reference
738page for a description of the acceptable values for TYPE parameter.
739
740`GLU_INVALID_VALUE' is returned if WIDTH or HEIGHT is < 1.
741
742`GLU_INVALID_ENUM' is returned if INTERNALFORMAT, FORMAT, or TYPE is not
743legal.
744
745`GLU_INVALID_OPERATION' is returned if TYPE is `GLU_UNSIGNED_BYTE_3_3_2'
746or `GLU_UNSIGNED_BYTE_2_3_3_REV' and FORMAT is not `GLU_RGB'.
747
748`GLU_INVALID_OPERATION' is returned if TYPE is
749`GLU_UNSIGNED_SHORT_5_6_5' or `GLU_UNSIGNED_SHORT_5_6_5_REV' and FORMAT
750is not `GLU_RGB'.
751
752`GLU_INVALID_OPERATION' is returned if TYPE is
753`GLU_UNSIGNED_SHORT_4_4_4_4' or `GLU_UNSIGNED_SHORT_4_4_4_4_REV' and
754FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
755
756`GLU_INVALID_OPERATION' is returned if TYPE is
757`GLU_UNSIGNED_SHORT_5_5_5_1' or `GLU_UNSIGNED_SHORT_1_5_5_5_REV' and
758FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
759
760`GLU_INVALID_OPERATION' is returned if TYPE is
761`GLU_UNSIGNED_INT_8_8_8_8' or `GLU_UNSIGNED_INT_8_8_8_8_REV' and FORMAT
762is neither `GLU_RGBA' nor `GLU_BGRA'.
763
764`GLU_INVALID_OPERATION' is returned if TYPE is
765`GLU_UNSIGNED_INT_10_10_10_2' or `GLU_UNSIGNED_INT_2_10_10_10_REV' and
766FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.")
8925f36f
AW		 767
768(define-gl-procedure
769 gluBuild3DMipmapLevels
770 "gluBuild3DMipmapLevels"
771 (funcsynopsis
772 (funcprototype
773 (funcdef
774 "GLint "
775 (function "gluBuild3DMipmapLevels"))
776 (paramdef "GLenum " (parameter "target"))
777 (paramdef "GLint " (parameter "internalFormat"))
778 (paramdef "GLsizei " (parameter "width"))
779 (paramdef "GLsizei " (parameter "height"))
780 (paramdef "GLsizei " (parameter "depth"))
781 (paramdef "GLenum " (parameter "format"))
782 (paramdef "GLenum " (parameter "type"))
783 (paramdef "GLint " (parameter "level"))
784 (paramdef "GLint " (parameter "base"))
785 (paramdef "GLint " (parameter "max"))
786 (paramdef "const void * " (parameter "data"))))
3c9b6116
AW		 787 "Builds a subset of three-dimensional mipmap levels.
788
789TARGET
790 Specifies the target texture. Must be `GLU_TEXTURE_3D'.
791
792INTERNALFORMAT
793 Requests the internal storage format of the texture image. The most
794 current version of the SGI implementation of GLU does not check
795 this value for validity before passing it on to the underlying
796 OpenGL implementation. A value that is not accepted by the OpenGL
797 implementation will lead to an OpenGL error. The benefit of not
798 checking this value at the GLU level is that OpenGL extensions can
799 add new internal texture formats without requiring a revision of
800 the GLU implementation. Older implementations of GLU check this
801 value and raise a GLU error if it is not 1, 2, 3, or 4 or one of
802 the following symbolic constants: `GLU_ALPHA', `GLU_ALPHA4',
803 `GLU_ALPHA8', `GLU_ALPHA12', `GLU_ALPHA16', `GLU_LUMINANCE',
804 `GLU_LUMINANCE4', `GLU_LUMINANCE8', `GLU_LUMINANCE12',
805 `GLU_LUMINANCE16', `GLU_LUMINANCE_ALPHA', `GLU_LUMINANCE4_ALPHA4',
806 `GLU_LUMINANCE6_ALPHA2', `GLU_LUMINANCE8_ALPHA8',
807 `GLU_LUMINANCE12_ALPHA4', `GLU_LUMINANCE12_ALPHA12',
808 `GLU_LUMINANCE16_ALPHA16', `GLU_INTENSITY', `GLU_INTENSITY4',
809 `GLU_INTENSITY8', `GLU_INTENSITY12', `GLU_INTENSITY16', `GLU_RGB',
810 `GLU_R3_G3_B2', `GLU_RGB4', `GLU_RGB5', `GLU_RGB8', `GLU_RGB10',
811 `GLU_RGB12', `GLU_RGB16', `GLU_RGBA', `GLU_RGBA2', `GLU_RGBA4',
812 `GLU_RGB5_A1', `GLU_RGBA8', `GLU_RGB10_A2', `GLU_RGBA12', or
813 `GLU_RGBA16'.
814
815WIDTH
816 HEIGHT
817
818 DEPTH
819
820 Specifies in pixels the width, height and depth respectively, of
821 the texture image. These should be a power of 2.
822
823FORMAT
824 Specifies the format of the pixel data. Must be one of
825 `GLU_COLOR_INDEX', `GLU_DEPTH_COMPONENT', `GLU_RED', `GLU_GREEN',
826 `GLU_BLUE', `GLU_ALPHA', `GLU_RGB', `GLU_RGBA', `GLU_BGR',
827 `GLU_BGRA', `GLU_LUMINANCE', or `GLU_LUMINANCE_ALPHA'.
828
829TYPE
830 Specifies the data type for DATA. Must be one of
831 `GLU_UNSIGNED_BYTE', `GLU_BYTE', `GLU_BITMAP',
832 `GLU_UNSIGNED_SHORT', `GLU_SHORT', `GLU_UNSIGNED_INT', `GLU_INT',
833 `GLU_FLOAT', `GLU_UNSIGNED_BYTE_3_3_2',
834 `GLU_UNSIGNED_BYTE_2_3_3_REV', `GLU_UNSIGNED_SHORT_5_6_5',
835 `GLU_UNSIGNED_SHORT_5_6_5_REV', `GLU_UNSIGNED_SHORT_4_4_4_4',
836 `GLU_UNSIGNED_SHORT_4_4_4_4_REV', `GLU_UNSIGNED_SHORT_5_5_5_1',
837 `GLU_UNSIGNED_SHORT_1_5_5_5_REV', `GLU_UNSIGNED_INT_8_8_8_8',
838 `GLU_UNSIGNED_INT_8_8_8_8_REV', `GLU_UNSIGNED_INT_10_10_10_2', or
839 `GLU_UNSIGNED_INT_2_10_10_10_REV'.
840
841LEVEL
842 Specifies the mipmap level of the image data.
843
844BASE
845 Specifies the minimum mipmap level to pass to `glTexImage3D'.
846
847MAX
848 Specifies the maximum mipmap level to pass to `glTexImage3D'.
849
850DATA
851 Specifies a pointer to the image data in memory.
852
853`gluBuild3DMipmapLevels' builds a subset of prefiltered
854three-dimensional texture maps of decreasing resolutions called a
855mipmap. This is used for the antialiasing of texture mapped primitives.
856
8925f36f 857A return value of zero indicates success, otherwise a GLU error code is
3c9b6116
AW		 858returned (see `gluErrorString').
859
860A series of mipmap levels from BASE to MAX is built by decimating DATA
861in half along both dimensions until size 1×1×1 is reached. At each
862level, each texel in the halved mipmap level is an average of the
863corresponding eight texels in the larger mipmap level. (If exactly one
864of the dimensions is 1, four texels are averaged. If exactly two of the
865dimensions are 1, two texels are averaged.) `glTexImage3D' is called to
866load these mipmap levels from BASE to MAX. If MAX is larger than the
867highest mipmap level for the texture of the specified size, then a GLU
868error code is returned (see `gluErrorString') and nothing is loaded.
869
870For example, if LEVEL is 2 and WIDTH is 16, HEIGHT is 8 and DEPTH is 4,
871the following levels are possible: 16×8×4 , 8×4×2 , 4×2×1 , 2×1×1 ,
8721×1×1 . These correspond to levels 2 through 6 respectively. If BASE is
8733 and MAX is 5, then only mipmap levels 8×4×2 , 4×2×1 , and 2×1×1 are
874loaded. However, if MAX is 7, then an error is returned and nothing is
875loaded, since MAX is larger than the highest mipmap level which is, in
876this case, 6.
877
878The highest mipmap level can be derived from the formula
879LOG_2\u2061(MAX\u2061(WIDTH,HEIGHTDEPTH)×2^LEVEL,) .
880
881See the `glTexImage1D' reference page for a description of the
882acceptable values for FORMAT parameter. See the `glDrawPixels' reference
883page for a description of the acceptable values for TYPE parameter.
884
885`GLU_INVALID_VALUE' is returned if LEVEL > BASE, BASE < 0, MAX < BASE,
886or MAX is > the highest mipmap level for DATA.
887
888`GLU_INVALID_VALUE' is returned if WIDTH, HEIGHT, or DEPTH is < 1.
889
890`GLU_INVALID_ENUM' is returned if INTERNALFORMAT, FORMAT, or TYPE is not
891legal.
892
893`GLU_INVALID_OPERATION' is returned if TYPE is `GLU_UNSIGNED_BYTE_3_3_2'
894or `GLU_UNSIGNED_BYTE_2_3_3_REV' and FORMAT is not `GLU_RGB'.
895
896`GLU_INVALID_OPERATION' is returned if TYPE is
897`GLU_UNSIGNED_SHORT_5_6_5' or `GLU_UNSIGNED_SHORT_5_6_5_REV' and FORMAT
898is not `GLU_RGB'.
899
900`GLU_INVALID_OPERATION' is returned if TYPE is
901`GLU_UNSIGNED_SHORT_4_4_4_4' or `GLU_UNSIGNED_SHORT_4_4_4_4_REV' and
902FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
903
904`GLU_INVALID_OPERATION' is returned if TYPE is
905`GLU_UNSIGNED_SHORT_5_5_5_1' or `GLU_UNSIGNED_SHORT_1_5_5_5_REV' and
906FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
907
908`GLU_INVALID_OPERATION' is returned if TYPE is
909`GLU_UNSIGNED_INT_8_8_8_8' or `GLU_UNSIGNED_INT_8_8_8_8_REV' and FORMAT
910is neither `GLU_RGBA' nor `GLU_BGRA'.
911
912`GLU_INVALID_OPERATION' is returned if TYPE is
913`GLU_UNSIGNED_INT_10_10_10_2' or `GLU_UNSIGNED_INT_2_10_10_10_REV' and
914FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.")
8925f36f
AW		 915
916(define-gl-procedure
917 gluBuild3DMipmaps
918 "gluBuild3DMipmaps"
919 (funcsynopsis
920 (funcprototype
921 (funcdef "GLint " (function "gluBuild3DMipmaps"))
922 (paramdef "GLenum " (parameter "target"))
923 (paramdef "GLint " (parameter "internalFormat"))
924 (paramdef "GLsizei " (parameter "width"))
925 (paramdef "GLsizei " (parameter "height"))
926 (paramdef "GLsizei " (parameter "depth"))
927 (paramdef "GLenum " (parameter "format"))
928 (paramdef "GLenum " (parameter "type"))
929 (paramdef "const void * " (parameter "data"))))
3c9b6116
AW		 930 "Builds a three-dimensional mipmap.
931
932TARGET
933 Specifies the target texture. Must be `GLU_TEXTURE_3D'.
934
935INTERNALFORMAT
936 Requests the internal storage format of the texture image. The most
937 current version of the SGI implementation of GLU does not check
938 this value for validity before passing it on to the underlying
939 OpenGL implementation. A value that is not accepted by the OpenGL
940 implementation will lead to an OpenGL error. The benefit of not
941 checking this value at the GLU level is that OpenGL extensions can
942 add new internal texture formats without requiring a revision of
943 the GLU implementation. Older implementations of GLU check this
944 value and raise a GLU error if it is not 1, 2, 3, or 4 or one of
945 the following symbolic constants: `GLU_ALPHA', `GLU_ALPHA4',
946 `GLU_ALPHA8', `GLU_ALPHA12', `GLU_ALPHA16', `GLU_LUMINANCE',
947 `GLU_LUMINANCE4', `GLU_LUMINANCE8', `GLU_LUMINANCE12',
948 `GLU_LUMINANCE16', `GLU_LUMINANCE_ALPHA', `GLU_LUMINANCE4_ALPHA4',
949 `GLU_LUMINANCE6_ALPHA2', `GLU_LUMINANCE8_ALPHA8',
950 `GLU_LUMINANCE12_ALPHA4', `GLU_LUMINANCE12_ALPHA12',
951 `GLU_LUMINANCE16_ALPHA16', `GLU_INTENSITY', `GLU_INTENSITY4',
952 `GLU_INTENSITY8', `GLU_INTENSITY12', `GLU_INTENSITY16', `GLU_RGB',
953 `GLU_R3_G3_B2', `GLU_RGB4', `GLU_RGB5', `GLU_RGB8', `GLU_RGB10',
954 `GLU_RGB12', `GLU_RGB16', `GLU_RGBA', `GLU_RGBA2', `GLU_RGBA4',
955 `GLU_RGB5_A1', `GLU_RGBA8', `GLU_RGB10_A2', `GLU_RGBA12', or
956 `GLU_RGBA16'.
957
958WIDTH
959 HEIGHT
960
961 DEPTH
962
963 Specifies in pixels the width, height and depth respectively, in
964 pixels of the texture image.
965
966FORMAT
967 Specifies the format of the pixel data. Must be one of
968 `GLU_COLOR_INDEX', `GLU_DEPTH_COMPONENT', `GLU_RED', `GLU_GREEN',
969 `GLU_BLUE', `GLU_ALPHA', `GLU_RGB', `GLU_RGBA', `GLU_BGR',
970 `GLU_BGRA', `GLU_LUMINANCE', or `GLU_LUMINANCE_ALPHA'.
971
972TYPE
973 Specifies the data type for DATA. Must be one of:
974 `GLU_UNSIGNED_BYTE', `GLU_BYTE', `GLU_BITMAP',
975 `GLU_UNSIGNED_SHORT', `GLU_SHORT', `GLU_UNSIGNED_INT', `GLU_INT',
976 `GLU_FLOAT', `GLU_UNSIGNED_BYTE_3_3_2',
977 `GLU_UNSIGNED_BYTE_2_3_3_REV', `GLU_UNSIGNED_SHORT_5_6_5',
978 `GLU_UNSIGNED_SHORT_5_6_5_REV', `GLU_UNSIGNED_SHORT_4_4_4_4',
979 `GLU_UNSIGNED_SHORT_4_4_4_4_REV', `GLU_UNSIGNED_SHORT_5_5_5_1',
980 `GLU_UNSIGNED_SHORT_1_5_5_5_REV', `GLU_UNSIGNED_INT_8_8_8_8',
981 `GLU_UNSIGNED_INT_8_8_8_8_REV', `GLU_UNSIGNED_INT_10_10_10_2', or
982 `GLU_UNSIGNED_INT_2_10_10_10_REV'.
983
984DATA
985 Specifies a pointer to the image data in memory.
986
987`gluBuild3DMipmaps' builds a series of prefiltered three-dimensional
988texture maps of decreasing resolutions called a mipmap. This is used for
989the antialiasing of texture-mapped primitives.
990
8925f36f 991A return value of zero indicates success, otherwise a GLU error code is
3c9b6116
AW		 992returned (see `gluErrorString').
993
994Initially, the WIDTH, HEIGHT and DEPTH of DATA are checked to see if
995they are a power of 2. If not, a copy of DATA is made and scaled up or
996down to the nearest power of 2. (If WIDTH, HEIGHT, or DEPTH is exactly
997between powers of 2, then the copy of DATA will scale upwards.) This
998copy will be used for subsequent mipmapping operations described below.
999For example, if WIDTH is 57, HEIGHT is 23, and DEPTH is 24, then a copy
1000of DATA will scale up to 64 in width, down to 16 in height, and up to 32
1001in depth before mipmapping takes place.
1002
1003Then, proxy textures (see `glTexImage3D') are used to determine if the
1004implementation can fit the requested texture. If not, all three
1005dimensions are continually halved until it fits.
1006
1007Next, a series of mipmap levels is built by decimating a copy of DATA in
1008half along all three dimensions until size 1×1×1 is reached. At each
1009level, each texel in the halved mipmap level is an average of the
1010corresponding eight texels in the larger mipmap level. (If exactly one
1011of the dimensions is 1, four texels are averaged. If exactly two of the
1012dimensions are 1, two texels are averaged.)
1013
1014`glTexImage3D' is called to load each of these mipmap levels. Level 0 is
1015a copy of DATA. The highest level is LOG_2,\u2061(MAX\u2061(WIDTH,HEIGHTDEPTH),) .
1016For example, if WIDTH is 64, HEIGHT is 16, and DEPTH is 32, and the
1017implementation can store a texture of this size, the following mipmap
1018levels are built: 64×16×32 , 32×8×16 , 16×4×8 , 8×2×4 , 4×1×2 , 2×1×1 ,
1019and 1×1×1 . These correspond to levels 0 through 6, respectively.
1020
1021See the `glTexImage1D' reference page for a description of the
1022acceptable values for FORMAT parameter. See the `glDrawPixels' reference
1023page for a description of the acceptable values for TYPE parameter.
1024
1025`GLU_INVALID_VALUE' is returned if WIDTH, HEIGHT, or DEPTH is < 1.
1026
1027`GLU_INVALID_ENUM' is returned if INTERNALFORMAT, FORMAT, or TYPE is not
1028legal.
1029
1030`GLU_INVALID_OPERATION' is returned if TYPE is `GLU_UNSIGNED_BYTE_3_3_2'
1031or `GLU_UNSIGNED_BYTE_2_3_3_REV' and FORMAT is not `GLU_RGB'.
1032
1033`GLU_INVALID_OPERATION' is returned if TYPE is
1034`GLU_UNSIGNED_SHORT_5_6_5' or `GLU_UNSIGNED_SHORT_5_6_5_REV' and FORMAT
1035is not `GLU_RGB'.
1036
1037`GLU_INVALID_OPERATION' is returned if TYPE is
1038`GLU_UNSIGNED_SHORT_4_4_4_4' or `GLU_UNSIGNED_SHORT_4_4_4_4_REV' and
1039FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
1040
1041`GLU_INVALID_OPERATION' is returned if TYPE is
1042`GLU_UNSIGNED_SHORT_5_5_5_1' or `GLU_UNSIGNED_SHORT_1_5_5_5_REV' and
1043FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
1044
1045`GLU_INVALID_OPERATION' is returned if TYPE is
1046`GLU_UNSIGNED_INT_8_8_8_8' or `GLU_UNSIGNED_INT_8_8_8_8_REV' and FORMAT
1047is neither `GLU_RGBA' nor `GLU_BGRA'.
1048
1049`GLU_INVALID_OPERATION' is returned if TYPE is
1050`GLU_UNSIGNED_INT_10_10_10_2' or `GLU_UNSIGNED_INT_2_10_10_10_REV' and
1051FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.")
8925f36f
AW		 1052
1053(define-gl-procedure
1054 gluCheckExtension
1055 "gluCheckExtension"
1056 (funcsynopsis
1057 (funcprototype
1058 (funcdef
1059 "GLboolean "
1060 (function "gluCheckExtension"))
1061 (paramdef
1062 "const GLubyte * "
1063 (parameter "extName"))
1064 (paramdef
1065 "const GLubyte * "
1066 (parameter "extString"))))
3c9b6116
AW		 1067 "Determines if an extension name is supported.
1068
1069EXTNAME
1070 Specifies an extension name.
1071
1072EXTSTRING
1073 Specifies a space-separated list of extension names supported.
1074
1075`gluCheckExtension' returns `GLU_TRUE' if EXTNAME is supported otherwise
1076`GLU_FALSE' is returned.
1077
1078This is used to check for the presence for OpenGL, GLU, or GLX extension
1079names by passing the extension strings returned by `glGetString',
1080`gluGetString', `glXGetClientString', `glXQueryExtensionsString', or
1081`glXQueryServerString', respectively, as EXTSTRING.")
8925f36f
AW		 1082
1083(define-gl-procedure
1084 gluCylinder
1085 "gluCylinder"
1086 (funcsynopsis
1087 (funcprototype
1088 (funcdef "void " (function "gluCylinder"))
1089 (paramdef "GLUquadric* " (parameter "quad"))
1090 (paramdef "GLdouble " (parameter "base"))
1091 (paramdef "GLdouble " (parameter "top"))
1092 (paramdef "GLdouble " (parameter "height"))
1093 (paramdef "GLint " (parameter "slices"))
1094 (paramdef "GLint " (parameter "stacks"))))
3c9b6116
AW		 1095 "Draw a cylinder.
1096
1097QUAD
1098 Specifies the quadrics object (created with `gluNewQuadric').
1099
1100BASE
1101 Specifies the radius of the cylinder at Z = 0.
1102
1103TOP
1104 Specifies the radius of the cylinder at Z = HEIGHT.
1105
1106HEIGHT
1107 Specifies the height of the cylinder.
1108
1109SLICES
1110 Specifies the number of subdivisions around the Z axis.
1111
1112STACKS
1113 Specifies the number of subdivisions along the Z axis.
1114
1115`gluCylinder' draws a cylinder oriented along the Z axis. The base of
1116the cylinder is placed at Z = 0 and the top at Z=HEIGHT . Like a sphere,
1117a cylinder is subdivided around the Z axis into slices and along the Z
1118axis into stacks.
1119
1120Note that if TOP is set to 0.0, this routine generates a cone.
1121
1122If the orientation is set to `GLU_OUTSIDE' (with
1123`gluQuadricOrientation'), then any generated normals point away from the
1124Z axis. Otherwise, they point toward the Z axis.
1125
1126If texturing is turned on (with `gluQuadricTexture'), then texture
1127coordinates are generated so that T ranges linearly from 0.0 at Z = 0 to
11281.0 at Z = HEIGHT, and S ranges from 0.0 at the +Y axis, to 0.25 at the
1129+X axis, to 0.5 at the -Y axis, to 0.75 at the \\-X axis, and back to 1.0
1130at the +Y axis.")
8925f36f
AW		 1131
1132(define-gl-procedure
1133 gluDeleteNurbsRenderer
1134 "gluDeleteNurbsRenderer"
1135 (funcsynopsis
1136 (funcprototype
1137 (funcdef
1138 "void "
1139 (function "gluDeleteNurbsRenderer"))
1140 (paramdef "GLUnurbs* " (parameter "nurb"))))
3c9b6116
AW		 1141 "Destroy a NURBS object.
1142
1143NURB
1144 Specifies the NURBS object to be destroyed.
1145
1146`gluDeleteNurbsRenderer' destroys the NURBS object (which was created
1147with `gluNewNurbsRenderer') and frees any memory it uses. Once
1148`gluDeleteNurbsRenderer' has been called, NURB cannot be used again.")
8925f36f
AW		 1149
1150(define-gl-procedure
1151 gluDeleteQuadric
1152 "gluDeleteQuadric"
1153 (funcsynopsis
1154 (funcprototype
1155 (funcdef "void " (function "gluDeleteQuadric"))
1156 (paramdef "GLUquadric* " (parameter "quad"))))
3c9b6116
AW		 1157 "Destroy a quadrics object.
1158
1159QUAD
1160 Specifies the quadrics object to be destroyed.
1161
1162`gluDeleteQuadric' destroys the quadrics object (created with
1163`gluNewQuadric') and frees any memory it uses. Once `gluDeleteQuadric'
1164has been called, QUAD cannot be used again.")
8925f36f
AW		 1165
1166(define-gl-procedure
1167 gluDeleteTess
1168 "gluDeleteTess"
1169 (funcsynopsis
1170 (funcprototype
1171 (funcdef "void " (function "gluDeleteTess"))
1172 (paramdef "GLUtesselator* " (parameter "tess"))))
3c9b6116
AW		 1173 "Destroy a tessellation object.
1174
1175TESS
1176 Specifies the tessellation object to destroy.
1177
1178`gluDeleteTess' destroys the indicated tessellation object (which was
1179created with `gluNewTess') and frees any memory that it used.")
8925f36f
AW		 1180
1181(define-gl-procedure
1182 gluDisk
1183 "gluDisk"
1184 (funcsynopsis
1185 (funcprototype
1186 (funcdef "void " (function "gluDisk"))
1187 (paramdef "GLUquadric* " (parameter "quad"))
1188 (paramdef "GLdouble " (parameter "inner"))
1189 (paramdef "GLdouble " (parameter "outer"))
1190 (paramdef "GLint " (parameter "slices"))
1191 (paramdef "GLint " (parameter "loops"))))
3c9b6116
AW		 1192 "Draw a disk.
1193
1194QUAD
1195 Specifies the quadrics object (created with `gluNewQuadric').
1196
1197INNER
1198 Specifies the inner radius of the disk (may be 0).
1199
1200OUTER
1201 Specifies the outer radius of the disk.
1202
1203SLICES
1204 Specifies the number of subdivisions around the Z axis.
1205
1206LOOPS
1207 Specifies the number of concentric rings about the origin into
1208 which the disk is subdivided.
1209
1210`gluDisk' renders a disk on the Z = 0 plane. The disk has a radius of
1211OUTER and contains a concentric circular hole with a radius of INNER. If
1212INNER is 0, then no hole is generated. The disk is subdivided around the
1213Z axis into slices (like pizza slices) and also about the Z axis into
1214rings (as specified by SLICES and LOOPS, respectively).
1215
1216With respect to orientation, the +Z side of the disk is considered to be
1217``outside'' (see `gluQuadricOrientation'). This means that if the
1218orientation is set to `GLU_OUTSIDE', then any normals generated point
1219along the +Z axis. Otherwise, they point along the \\-Z axis.
1220
1221If texturing has been turned on (with `gluQuadricTexture'), texture
1222coordinates are generated linearly such that where R=OUTER , the value
1223at (R, 0, 0) is (1, 0.5), at (0, R, 0) it is (0.5, 1), at (\\-R, 0, 0) it
1224is (0, 0.5), and at (0, \\-R, 0) it is (0.5, 0).")
8925f36f
AW		 1225
1226(define-gl-procedure
1227 gluErrorString
1228 "gluErrorString"
1229 (funcsynopsis
1230 (funcprototype
1231 (funcdef
1232 "const GLubyte * "
1233 (function "gluErrorString"))
1234 (paramdef "GLenum " (parameter "error"))))
3c9b6116
AW		 1235 "Produce an error string from a GL or GLU error code.
1236
1237ERROR
1238 Specifies a GL or GLU error code.
1239
1240`gluErrorString' produces an error string from a GL or GLU error code.
1241The string is in ISO Latin 1 format. For example,
1242`gluErrorString'(`GLU_OUT_OF_MEMORY') returns the string OUT OF MEMORY.
1243
1244The standard GLU error codes are `GLU_INVALID_ENUM',
1245`GLU_INVALID_VALUE', and `GLU_OUT_OF_MEMORY'. Certain other GLU
1246functions can return specialized error codes through callbacks. See the
1247`glGetError' reference page for the list of GL error codes.
1248
1249`NULL' is returned if ERROR is not a valid GL or GLU error code.")
8925f36f
AW		 1250
1251(define-gl-procedure
1252 gluGetNurbsProperty
1253 "gluGetNurbsProperty"
1254 (funcsynopsis
1255 (funcprototype
1256 (funcdef
1257 "void "
1258 (function "gluGetNurbsProperty"))
1259 (paramdef "GLUnurbs* " (parameter "nurb"))
1260 (paramdef "GLenum " (parameter "property"))
1261 (paramdef "GLfloat* " (parameter "data"))))
3c9b6116
AW		 1262 "Get a NURBS property.
1263
1264NURB
1265 Specifies the NURBS object (created with `gluNewNurbsRenderer').
1266
1267PROPERTY
1268 Specifies the property whose value is to be fetched. Valid values
1269 are `GLU_CULLING', `GLU_SAMPLING_TOLERANCE', `GLU_DISPLAY_MODE',
1270 `GLU_AUTO_LOAD_MATRIX', `GLU_PARAMETRIC_TOLERANCE',
1271 `GLU_SAMPLING_METHOD', `GLU_U_STEP', `GLU_V_STEP', and
1272 `GLU_NURBS_MODE'.
1273
1274DATA
1275 Specifies a pointer to the location into which the value of the
1276 named property is written.
1277
1278`gluGetNurbsProperty' retrieves properties stored in a NURBS object.
1279These properties affect the way that NURBS curves and surfaces are
1280rendered. See the `gluNurbsProperty' reference page for information
1281about what the properties are and what they do.")
8925f36f
AW		 1282
1283(define-gl-procedure
1284 gluGetString
1285 "gluGetString"
1286 (funcsynopsis
1287 (funcprototype
1288 (funcdef
1289 "const GLubyte * "
1290 (function "gluGetString"))
1291 (paramdef "GLenum " (parameter "name"))))
3c9b6116
AW		 1292 "Return a string describing the GLU version or GLU extensions .
1293
1294NAME
1295 Specifies a symbolic constant, one of `GLU_VERSION', or
1296 `GLU_EXTENSIONS'.
1297
1298`gluGetString' returns a pointer to a static string describing the GLU
1299version or the GLU extensions that are supported.
1300
1301The version number is one of the following forms:
1302
1303MAJOR_NUMBER.MINOR_NUMBERMAJOR_NUMBER.MINOR_NUMBER.RELEASE_NUMBER.
1304
1305The version string is of the following form:
1306
1307VERSION NUMBER<SPACE>VENDOR-SPECIFIC INFORMATION
1308
1309Vendor-specific information is optional. Its format and contents depend
1310on the implementation.
1311
1312The standard GLU contains a basic set of features and capabilities. If a
1313company or group of companies wish to support other features, these may
1314be included as extensions to the GLU. If NAME is `GLU_EXTENSIONS', then
1315`gluGetString' returns a space-separated list of names of supported GLU
1316extensions. (Extension names never contain spaces.)
1317
1318All strings are null-terminated.
1319
1320NULL is returned if NAME is not `GLU_VERSION' or `GLU_EXTENSIONS'.")
8925f36f
AW		 1321
1322(define-gl-procedure
1323 gluGetTessProperty
1324 "gluGetTessProperty"
1325 (funcsynopsis
1326 (funcprototype
1327 (funcdef "void " (function "gluGetTessProperty"))
1328 (paramdef "GLUtesselator* " (parameter "tess"))
1329 (paramdef "GLenum " (parameter "which"))
1330 (paramdef "GLdouble* " (parameter "data"))))
3c9b6116
AW		 1331 "Get a tessellation object property.
1332
1333TESS
1334 Specifies the tessellation object (created with `gluNewTess').
1335
1336WHICH
1337 Specifies the property whose value is to be fetched. Valid values
1338 are `GLU_TESS_WINDING_RULE', `GLU_TESS_BOUNDARY_ONLY', and
1339 `GLU_TESS_TOLERANCE'.
1340
1341DATA
1342 Specifies a pointer to the location into which the value of the
1343 named property is written.
1344
1345`gluGetTessProperty' retrieves properties stored in a tessellation
1346object. These properties affect the way that tessellation objects are
1347interpreted and rendered. See the `gluTessProperty' reference page for
1348information about the properties and what they do.")
8925f36f
AW		 1349
1350(define-gl-procedure
1351 gluLoadSamplingMatrices
1352 "gluLoadSamplingMatrices"
1353 (funcsynopsis
1354 (funcprototype
1355 (funcdef
1356 "void "
1357 (function "gluLoadSamplingMatrices"))
1358 (paramdef "GLUnurbs* " (parameter "nurb"))
1359 (paramdef "const GLfloat * " (parameter "model"))
1360 (paramdef
1361 "const GLfloat * "
1362 (parameter "perspective"))
1363 (paramdef "const GLint * " (parameter "view"))))
3c9b6116
AW		 1364 "Load NURBS sampling and culling matrices.
1365
1366NURB
1367 Specifies the NURBS object (created with `gluNewNurbsRenderer').
1368
1369MODEL
1370 Specifies a modelview matrix (as from a `glGetFloatv' call).
1371
1372PERSPECTIVE
1373 Specifies a projection matrix (as from a `glGetFloatv' call).
1374
1375VIEW
1376 Specifies a viewport (as from a `glGetIntegerv' call).
1377
1378`gluLoadSamplingMatrices' uses MODEL, PERSPECTIVE, and VIEW to recompute
1379the sampling and culling matrices stored in NURB. The sampling matrix
1380determines how finely a NURBS curve or surface must be tessellated to
1381satisfy the sampling tolerance (as determined by the
1382`GLU_SAMPLING_TOLERANCE' property). The culling matrix is used in
1383deciding if a NURBS curve or surface should be culled before rendering
1384(when the `GLU_CULLING' property is turned on).
1385
1386`gluLoadSamplingMatrices' is necessary only if the
1387`GLU_AUTO_LOAD_MATRIX' property is turned off (see `gluNurbsProperty').
1388Although it can be convenient to leave the `GLU_AUTO_LOAD_MATRIX'
1389property turned on, there can be a performance penalty for doing so. (A
1390round trip to the GL server is needed to fetch the current values of the
1391modelview matrix, projection matrix, and viewport.)")
8925f36f
AW		 1392
1393(define-gl-procedure
1394 gluLookAt
1395 "gluLookAt"
1396 (funcsynopsis
1397 (funcprototype
1398 (funcdef "void " (function "gluLookAt"))
1399 (paramdef "GLdouble " (parameter "eyeX"))
1400 (paramdef "GLdouble " (parameter "eyeY"))
1401 (paramdef "GLdouble " (parameter "eyeZ"))
1402 (paramdef "GLdouble " (parameter "centerX"))
1403 (paramdef "GLdouble " (parameter "centerY"))
1404 (paramdef "GLdouble " (parameter "centerZ"))
1405 (paramdef "GLdouble " (parameter "upX"))
1406 (paramdef "GLdouble " (parameter "upY"))
1407 (paramdef "GLdouble " (parameter "upZ"))))
3c9b6116
AW		 1408 "Define a viewing transformation.
1409
1410EYEX
1411 EYEY
1412
1413 EYEZ
1414
1415 Specifies the position of the eye point.
1416
1417CENTERX
1418 CENTERY
1419
1420 CENTERZ
1421
1422 Specifies the position of the reference point.
1423
1424UPX
1425 UPY
1426
1427 UPZ
1428
1429 Specifies the direction of the UP vector.
1430
1431`gluLookAt' creates a viewing matrix derived from an eye point, a
1432reference point indicating the center of the scene, and an UP vector.
1433
1434The matrix maps the reference point to the negative Z axis and the eye
1435point to the origin. When a typical projection matrix is used, the
1436center of the scene therefore maps to the center of the viewport.
1437Similarly, the direction described by the UP vector projected onto the
1438viewing plane is mapped to the positive Y axis so that it points upward
1439in the viewport. The UP vector must not be parallel to the line of sight
1440from the eye point to the reference point.
1441
1442Let
1443
1444F=((CENTERX-EYEX), (CENTERY-EYEY), (CENTERZ-EYEZ),)
1445
1446
1447
1448Let UP be the vector (UPX,UPYUPZ) .
1449
1450Then normalize as follows: F=F/∥F,∥,
1451
1452UP^″=UP/∥UP,∥,
1453
1454
1455
1456Finally, let S=F×UP^″ , and U=S×F .
1457
1458
1459
1460M is then constructed as follows: M=((S\u2061[0,] S\u2061[1,] S\u2061[2,] 0), (U\u2061[0,]
1461U\u2061[1,] U\u2061[2,] 0), (-F\u2061[0,] -F\u2061[1,] -F\u2061[2,] 0), (0 0 0 1),)
1462
1463and `gluLookAt' is equivalent to
1464
1465
1466 glMultMatrixf(M);
1467 glTranslated(-eyex, -eyey, -eyez);")
8925f36f
AW		 1468
1469(define-gl-procedure
1470 gluNewNurbsRenderer
1471 "gluNewNurbsRenderer"
1472 (funcsynopsis
1473 (funcprototype
1474 (funcdef
1475 "GLUnurbs* "
1476 (function "gluNewNurbsRenderer"))))
3c9b6116
AW		 1477 "Create a NURBS object.
1478
1479`gluNewNurbsRenderer' creates and returns a pointer to a new NURBS
1480object. This object must be referred to when calling NURBS rendering and
1481control functions. A return value of 0 means that there is not enough
1482memory to allocate the object.")
8925f36f
AW		 1483
1484(define-gl-procedure
1485 gluNewQuadric
1486 "gluNewQuadric"
1487 (funcsynopsis
1488 (funcprototype
1489 (funcdef
1490 "GLUquadric* "
1491 (function "gluNewQuadric"))))
3c9b6116
AW		 1492 "Create a quadrics object.
1493
1494`gluNewQuadric' creates and returns a pointer to a new quadrics object.
1495This object must be referred to when calling quadrics rendering and
1496control functions. A return value of 0 means that there is not enough
1497memory to allocate the object.")
8925f36f
AW		 1498
1499(define-gl-procedure
1500 gluNewTess
1501 "gluNewTess"
1502 (funcsynopsis
1503 (funcprototype
1504 (funcdef
1505 "GLUtesselator* "
1506 (function "gluNewTess"))))
3c9b6116
AW		 1507 "Create a tessellation object.
1508
1509`gluNewTess' creates and returns a pointer to a new tessellation object.
1510This object must be referred to when calling tessellation functions. A
1511return value of 0 means that there is not enough memory to allocate the
1512object.")
8925f36f
AW		 1513
1514(define-gl-procedure
1515 gluNextContour
1516 "gluNextContour"
1517 (funcsynopsis
1518 (funcprototype
1519 (funcdef "void " (function "gluNextContour"))
1520 (paramdef "GLUtesselator* " (parameter "tess"))
1521 (paramdef "GLenum " (parameter "type"))))
3c9b6116 1522 "Mark the beginning of another contour.
8925f36f 1523
3c9b6116
AW		 1524TESS
1525 Specifies the tessellation object (created with `gluNewTess').
1526
1527TYPE
1528 Specifies the type of the contour being defined. Valid values are
1529 `GLU_EXTERIOR', `GLU_INTERIOR', `GLU_UNKNOWN', `GLU_CCW', and
1530 `GLU_CW'.
1531
1532`gluNextContour' is used in describing polygons with multiple contours.
1533After the first contour has been described through a series of
1534`gluTessVertex' calls, a `gluNextContour' call indicates that the
1535previous contour is complete and that the next contour is about to
1536begin. Another series of `gluTessVertex' calls is then used to describe
1537the new contour. This process can be repeated until all contours have
1538been described.
1539
1540TYPE defines what type of contour follows. The legal contour types are
1541as follows:
1542
1543`GLU_EXTERIOR'
1544 An exterior contour defines an exterior boundary of the polygon.
1545
1546`GLU_INTERIOR'
1547 An interior contour defines an interior boundary of the polygon
1548 (such as a hole).
1549
1550`GLU_UNKNOWN'
1551 An unknown contour is analyzed by the library to determine if it is
1552 interior or exterior.
1553
1554`GLU_CCW',
1555`GLU_CW'
1556 The first `GLU_CCW' or `GLU_CW' contour defined is considered to be
1557 exterior. All other contours are considered to be exterior if they
1558 are oriented in the same direction (clockwise or counterclockwise)
1559 as the first contour, and interior if they are not.
1560
1561If one contour is of type `GLU_CCW' or `GLU_CW', then all contours must
1562be of the same type (if they are not, then all `GLU_CCW' and `GLU_CW'
1563contours will be changed to `GLU_UNKNOWN').
1564
1565Note that there is no real difference between the `GLU_CCW' and `GLU_CW'
1566contour types.
1567
1568Before the first contour is described, `gluNextContour' can be called to
1569define the type of the first contour. If `gluNextContour' is not called
1570before the first contour, then the first contour is marked
1571`GLU_EXTERIOR'.
1572
1573This command is obsolete and is provided for backward compatibility
1574only. Calls to `gluNextContour' are mapped to `gluTessEndContour'
1575followed by `gluTessBeginContour'.")
1576
1577(define-gl-procedure
1578 gluNurbsCallbackDataEXT
1579 "gluNurbsCallbackDataEXT"
1580 (funcsynopsis
1581 (funcprototype
1582 (funcdef
1583 "void "
1584 (function "gluNurbsCallbackDataEXT"))
1585 (paramdef "GLUnurbs* " (parameter "nurb"))
1586 (paramdef "GLvoid* " (parameter "userData"))))
1587 "Set a user data pointer.
1588
1589NURB
1590 Specifies the NURBS object (created with `gluNewNurbsRenderer').
1591
1592USERDATA
1593 Specifies a pointer to the user's data.
1594
1595`gluNurbsCallbackDataEXT' is used to pass a pointer to the application's
1596data to NURBS tessellator. A copy of this pointer will be passed by the
1597tessellator in the NURBS callback functions (set by `gluNurbsCallback').")
8925f36f
AW		 1598
1599(define-gl-procedure
1600 gluNurbsCallbackData
1601 "gluNurbsCallbackData"
1602 (funcsynopsis
1603 (funcprototype
1604 (funcdef
1605 "void "
1606 (function "gluNurbsCallbackData"))
1607 (paramdef "GLUnurbs* " (parameter "nurb"))
1608 (paramdef "GLvoid* " (parameter "userData"))))
3c9b6116
AW		 1609 "Set a user data pointer.
1610
1611NURB
1612 Specifies the NURBS object (created with `gluNewNurbsRenderer').
1613
1614USERDATA
1615 Specifies a pointer to the user's data.
1616
1617`gluNurbsCallbackData' is used to pass a pointer to the application's
1618data to NURBS tessellator. A copy of this pointer will be passed by the
1619tessellator in the NURBS callback functions (set by `gluNurbsCallback').")
8925f36f
AW		 1620
1621(define-gl-procedure
1622 gluNurbsCallback
1623 "gluNurbsCallback"
1624 (funcsynopsis
1625 (funcprototype
1626 (funcdef "void " (function "gluNurbsCallback"))
1627 (paramdef "GLUnurbs* " (parameter "nurb"))
1628 (paramdef "GLenum " (parameter "which"))
1629 (paramdef
1630 "_GLUfuncptr "
1631 (parameter "CallBackFunc"))))
3c9b6116
AW		 1632 "Define a callback for a NURBS object.
1633
1634NURB
1635 Specifies the NURBS object (created with `gluNewNurbsRenderer').
1636
1637WHICH
1638 Specifies the callback being defined. Valid values are
1639 `GLU_NURBS_BEGIN', `GLU_NURBS_VERTEX', `GLU_NURBS_NORMAL',
1640 `GLU_NURBS_COLOR', `GLU_NURBS_TEXTURE_COORD', `GLU_NURBS_END',
1641 `GLU_NURBS_BEGIN_DATA', `GLU_NURBS_VERTEX_DATA',
1642 `GLU_NURBS_NORMAL_DATA', `GLU_NURBS_COLOR_DATA',
1643 `GLU_NURBS_TEXTURE_COORD_DATA', `GLU_NURBS_END_DATA', and
1644 `GLU_NURBS_ERROR'.
1645
1646CALLBACKFUNC
1647 Specifies the function that the callback calls.
1648
1649`gluNurbsCallback' is used to define a callback to be used by a NURBS
1650object. If the specified callback is already defined, then it is
1651replaced. If CALLBACKFUNC is NULL, then this callback will not get
1652invoked and the related data, if any, will be lost.
1653
1654Except the error callback, these callbacks are used by NURBS tessellator
1655(when `GLU_NURBS_MODE' is set to be `GLU_NURBS_TESSELLATOR') to return
1656back the OpenGL polygon primitives resulting from the tessellation. Note
1657that there are two versions of each callback: one with a user data
1658pointer and one without. If both versions for a particular callback are
1659specified then the callback with the user data pointer will be used.
1660Note that ``userData'' is a copy of the pointer that was specified at
1661the last call to `gluNurbsCallbackData'.
1662
1663The error callback function is effective no matter which value that
1664`GLU_NURBS_MODE' is set to. All other callback functions are effective
1665only when `GLU_NURBS_MODE' is set to `GLU_NURBS_TESSELLATOR'.
1666
1667The legal callbacks are as follows:
1668
1669`GLU_NURBS_BEGIN'
1670
1671
1672 The begin callback indicates the start of a primitive. The function
1673 takes a single argument of type GLenum, which can be one of
1674 `GLU_LINES', `GLU_LINE_STRIP', `GLU_TRIANGLE_FAN',
1675 `GLU_TRIANGLE_STRIP', `GLU_TRIANGLES', or `GLU_QUAD_STRIP'. The
1676 default begin callback function is NULL. The function prototype for
1677 this callback looks like:
1678
1679`GLU_NURBS_BEGIN_DATA'
1680
1681
1682 The same as the `GLU_NURBS_BEGIN' callback except that it takes an
1683 additional pointer argument. This pointer is a copy of the pointer
1684 that was specified at the last call to `gluNurbsCallbackData'. The
1685 default callback function is NULL. The function prototype for this
1686 callback function looks like:
1687
1688`GLU_NURBS_VERTEX'
1689
1690
1691 The vertex callback indicates a vertex of the primitive. The
1692 coordinates of the vertex are stored in the parameter ``vertex''.
1693 All the generated vertices have dimension 3; that is, homogeneous
1694 coordinates have been transformed into affine coordinates. The
1695 default vertex callback function is NULL. The function prototype
1696 for this callback function looks like:
1697
1698`GLU_NURBS_VERTEX_DATA'
1699
1700
1701 This is the same as the `GLU_NURBS_VERTEX' callback, except that it
1702 takes an additional pointer argument. This pointer is a copy of the
1703 pointer that was specified at the last call to
1704 `gluNurbsCallbackData'. The default callback function is NULL. The
1705 function prototype for this callback function looks like:
1706
1707`GLU_NURBS_NORMAL'
1708
1709
1710 The normal callback is invoked as the vertex normal is generated.
1711 The components of the normal are stored in the parameter
1712 ``normal.'' In the case of a NURBS curve, the callback function is
1713 effective only when the user provides a normal map
1714 (`GLU_MAP1_NORMAL'). In the case of a NURBS surface, if a normal
1715 map (`GLU_MAP2_NORMAL') is provided, then the generated normal is
1716 computed from the normal map. If a normal map is not provided, then
1717 a surface normal is computed in a manner similar to that described
1718 for evaluators when `GLU_AUTO_NORMAL' is enabled. The default
1719 normal callback function is NULL. The function prototype for this
1720 callback function looks like:
1721
1722`GLU_NURBS_NORMAL_DATA'
1723
1724
1725 The same as the `GLU_NURBS_NORMAL' callback except that it takes an
1726 additional pointer argument. This pointer is a copy of the pointer
1727 that was specified at the last call to `gluNurbsCallbackData'. The
1728 default callback function is NULL. The function prototype for this
1729 callback function looks like:
1730
1731`GLU_NURBS_COLOR'
1732
1733
1734 The color callback is invoked as the color of a vertex is
1735 generated. The components of the color are stored in the parameter
1736 ``color.'' This callback is effective only when the user provides a
1737 color map (`GLU_MAP1_COLOR_4' or `GLU_MAP2_COLOR_4'). ``color''
1738 contains four components: R, G, B, A. The default color callback
1739 function is NULL. The prototype for this callback function looks
1740 like:
1741
1742`GLU_NURBS_COLOR_DATA'
1743
1744
1745 The same as the `GLU_NURBS_COLOR' callback except that it takes an
1746 additional pointer argument. This pointer is a copy of the pointer
1747 that was specified at the last call to `gluNurbsCallbackData'. The
1748 default callback function is NULL. The function prototype for this
1749 callback function looks like:
1750
1751`GLU_NURBS_TEXTURE_COORD'
1752
1753
1754 The texture callback is invoked as the texture coordinates of a
1755 vertex are generated. These coordinates are stored in the parameter
1756 ``texCoord.'' The number of texture coordinates can be 1, 2, 3, or
1757 4 depending on which type of texture map is specified
1758 (`GLU_MAP1_TEXTURE_COORD_1', `GLU_MAP1_TEXTURE_COORD_2',
1759 `GLU_MAP1_TEXTURE_COORD_3', `GLU_MAP1_TEXTURE_COORD_4',
1760 `GLU_MAP2_TEXTURE_COORD_1', `GLU_MAP2_TEXTURE_COORD_2',
1761 `GLU_MAP2_TEXTURE_COORD_3', `GLU_MAP2_TEXTURE_COORD_4'). If no
1762 texture map is specified, this callback function will not be
1763 called. The default texture callback function is NULL. The function
1764 prototype for this callback function looks like:
1765
1766`GLU_NURBS_TEXTURE_COORD_DATA'
1767
1768
1769 This is the same as the `GLU_NURBS_TEXTURE_COORD' callback, except
1770 that it takes an additional pointer argument. This pointer is a
1771 copy of the pointer that was specified at the last call to
1772 `gluNurbsCallbackData'. The default callback function is NULL. The
1773 function prototype for this callback function looks like:
1774
1775`GLU_NURBS_END'
1776
1777
1778 The end callback is invoked at the end of a primitive. The default
1779 end callback function is NULL. The function prototype for this
1780 callback function looks like:
1781
1782`GLU_NURBS_END_DATA'
1783
1784
1785 This is the same as the `GLU_NURBS_END' callback, except that it
1786 takes an additional pointer argument. This pointer is a copy of the
1787 pointer that was specified at the last call to
1788 `gluNurbsCallbackData'. The default callback function is NULL. The
1789 function prototype for this callback function looks like:
1790
1791`GLU_NURBS_ERROR'
1792
1793
1794 The error function is called when an error is encountered. Its
1795 single argument is of type GLenum, and it indicates the specific
1796 error that occurred. There are 37 errors unique to NURBS, named
1797 `GLU_NURBS_ERROR1' through `GLU_NURBS_ERROR37'. Character strings
1798 describing these errors can be retrieved with `gluErrorString'.
1799
1800
1801 void begin( GLenum type );
1802
1803
1804 void beginData(GLenum type, void *userData);
1805
1806
1807 void vertex( GLfloat *vertex );
1808
1809
1810 void vertexData( GLfloat *vertex, void *userData );
1811
1812
1813 void normal( GLfloat *normal );
1814
1815
1816 void normalData( GLfloat *normal, void *userData );
1817
1818
1819 void color( GLfloat *color );
1820
1821
1822 void colorData( GLfloat *color, void *userData );
1823
1824
1825 void texCoord( GLfloat *texCoord );
1826
1827
1828 void texCoordData( GLfloat *texCoord, void *userData );
1829
1830
1831 void end( void );
1832
1833
1834 void endData( void *userData );")
8925f36f
AW		 1835
1836(define-gl-procedure
1837 gluNurbsCurve
1838 "gluNurbsCurve"
1839 (funcsynopsis
1840 (funcprototype
1841 (funcdef "void " (function "gluNurbsCurve"))
1842 (paramdef "GLUnurbs* " (parameter "nurb"))
1843 (paramdef "GLint " (parameter "knotCount"))
1844 (paramdef "GLfloat * " (parameter "knots"))
1845 (paramdef "GLint " (parameter "stride"))
1846 (paramdef "GLfloat * " (parameter "control"))
1847 (paramdef "GLint " (parameter "order"))
1848 (paramdef "GLenum " (parameter "type"))))
3c9b6116
AW		 1849 "Define the shape of a NURBS curve.
1850
1851NURB
1852 Specifies the NURBS object (created with `gluNewNurbsRenderer').
1853
1854KNOTCOUNT
1855 Specifies the number of knots in KNOTS. KNOTCOUNT equals the number
1856 of control points plus the order.
1857
1858KNOTS
1859 Specifies an array of KNOTCOUNT nondecreasing knot values.
1860
1861STRIDE
1862 Specifies the offset (as a number of single-precision
1863 floating-point values) between successive curve control points.
1864
1865CONTROL
1866 Specifies a pointer to an array of control points. The coordinates
1867 must agree with TYPE, specified below.
1868
1869ORDER
1870 Specifies the order of the NURBS curve. ORDER equals degree + 1,
1871 hence a cubic curve has an order of 4.
1872
1873TYPE
1874 Specifies the type of the curve. If this curve is defined within a
1875 `gluBeginCurve'/`gluEndCurve' pair, then the type can be any of the
1876 valid one-dimensional evaluator types (such as `GLU_MAP1_VERTEX_3'
1877 or `GLU_MAP1_COLOR_4'). Between a `gluBeginTrim'/`gluEndTrim' pair,
1878 the only valid types are `GLU_MAP1_TRIM_2' and `GLU_MAP1_TRIM_3'.
1879
1880Use `gluNurbsCurve' to describe a NURBS curve.
1881
1882When `gluNurbsCurve' appears between a `gluBeginCurve'/`gluEndCurve'
1883pair, it is used to describe a curve to be rendered. Positional,
1884texture, and color coordinates are associated by presenting each as a
1885separate `gluNurbsCurve' between a `gluBeginCurve'/`gluEndCurve' pair.
1886No more than one call to `gluNurbsCurve' for each of color, position,
1887and texture data can be made within a single
1888`gluBeginCurve'/`gluEndCurve' pair. Exactly one call must be made to
1889describe the position of the curve (a TYPE of `GLU_MAP1_VERTEX_3' or
1890`GLU_MAP1_VERTEX_4').
1891
1892When `gluNurbsCurve' appears between a `gluBeginTrim'/`gluEndTrim' pair,
1893it is used to describe a trimming curve on a NURBS surface. If TYPE is
1894`GLU_MAP1_TRIM_2', then it describes a curve in two-dimensional (U and
1895V) parameter space. If it is `GLU_MAP1_TRIM_3', then it describes a
1896curve in two-dimensional homogeneous (U, V, and W) parameter space. See
1897the `gluBeginTrim' reference page for more discussion about trimming
1898curves.")
8925f36f
AW		 1899
1900(define-gl-procedure
1901 gluNurbsProperty
1902 "gluNurbsProperty"
1903 (funcsynopsis
1904 (funcprototype
1905 (funcdef "void " (function "gluNurbsProperty"))
1906 (paramdef "GLUnurbs* " (parameter "nurb"))
1907 (paramdef "GLenum " (parameter "property"))
1908 (paramdef "GLfloat " (parameter "value"))))
3c9b6116
AW		 1909 "Set a NURBS property.
1910
1911NURB
1912 Specifies the NURBS object (created with `gluNewNurbsRenderer').
1913
1914PROPERTY
1915 Specifies the property to be set. Valid values are
1916 `GLU_SAMPLING_TOLERANCE', `GLU_DISPLAY_MODE', `GLU_CULLING',
1917 `GLU_AUTO_LOAD_MATRIX', `GLU_PARAMETRIC_TOLERANCE',
1918 `GLU_SAMPLING_METHOD', `GLU_U_STEP', `GLU_V_STEP', or
1919 `GLU_NURBS_MODE'.
1920
1921VALUE
1922 Specifies the value of the indicated property. It may be a numeric
1923 value or one of `GLU_OUTLINE_POLYGON', `GLU_FILL',
1924 `GLU_OUTLINE_PATCH', `GLU_TRUE', `GLU_FALSE', `GLU_PATH_LENGTH',
1925 `GLU_PARAMETRIC_ERROR', `GLU_DOMAIN_DISTANCE',
1926 `GLU_NURBS_RENDERER', or `GLU_NURBS_TESSELLATOR'.
1927
1928`gluNurbsProperty' is used to control properties stored in a NURBS
1929object. These properties affect the way that a NURBS curve is rendered.
1930The accepted values for PROPERTY are as follows:
1931
1932`GLU_NURBS_MODE'
1933 VALUE should be set to be either `GLU_NURBS_RENDERER' or
1934 `GLU_NURBS_TESSELLATOR'. When set to `GLU_NURBS_RENDERER', NURBS
1935 objects are tessellated into OpenGL primitives and sent to the
1936 pipeline for rendering. When set to `GLU_NURBS_TESSELLATOR', NURBS
1937 objects are tessellated into OpenGL primitives but the vertices,
1938 normals, colors, and/or textures are retrieved back through a
1939 callback interface (see `gluNurbsCallback'). This allows the user
1940 to cache the tessellated results for further processing. The
1941 initial value is `GLU_NURBS_RENDERER'.
1942
1943`GLU_SAMPLING_METHOD'
1944 Specifies how a NURBS surface should be tessellated. VALUE may be
1945 one of `GLU_PATH_LENGTH', `GLU_PARAMETRIC_ERROR',
1946 `GLU_DOMAIN_DISTANCE', `GLU_OBJECT_PATH_LENGTH', or
1947 `GLU_OBJECT_PARAMETRIC_ERROR'. When set to `GLU_PATH_LENGTH', the
1948 surface is rendered so that the maximum length, in pixels, of the
1949 edges of the tessellation polygons is no greater than what is
1950 specified by `GLU_SAMPLING_TOLERANCE'.
1951
1952 `GLU_PARAMETRIC_ERROR' specifies that the surface is rendered in
1953 such a way that the value specified by `GLU_PARAMETRIC_TOLERANCE'
1954 describes the maximum distance, in pixels, between the tessellation
1955 polygons and the surfaces they approximate.
1956
1957 `GLU_DOMAIN_DISTANCE' allows users to specify, in parametric
1958 coordinates, how many sample points per unit length are taken in U,
1959 V direction.
1960
1961 `GLU_OBJECT_PATH_LENGTH' is similar to `GLU_PATH_LENGTH' except
1962 that it is view independent; that is, the surface is rendered so
1963 that the maximum length, in object space, of edges of the
1964 tessellation polygons is no greater than what is specified by
1965 `GLU_SAMPLING_TOLERANCE'.
1966
1967 `GLU_OBJECT_PARAMETRIC_ERROR' is similar to `GLU_PARAMETRIC_ERROR'
1968 except that it is view independent; that is, the surface is
1969 rendered in such a way that the value specified by
1970 `GLU_PARAMETRIC_TOLERANCE' describes the maximum distance, in
1971 object space, between the tessellation polygons and the surfaces
1972 they approximate.
1973
1974 The initial value of `GLU_SAMPLING_METHOD' is `GLU_PATH_LENGTH'.
1975
1976`GLU_SAMPLING_TOLERANCE'
1977 Specifies the maximum length, in pixels or in object space length
1978 unit, to use when the sampling method is set to `GLU_PATH_LENGTH'
1979 or `GLU_OBJECT_PATH_LENGTH'. The NURBS code is conservative when
1980 rendering a curve or surface, so the actual length can be somewhat
1981 shorter. The initial value is 50.0 pixels.
1982
1983`GLU_PARAMETRIC_TOLERANCE'
1984 Specifies the maximum distance, in pixels or in object space length
1985 unit, to use when the sampling method is `GLU_PARAMETRIC_ERROR' or
1986 `GLU_OBJECT_PARAMETRIC_ERROR'. The initial value is 0.5.
1987
1988`GLU_U_STEP'
1989 Specifies the number of sample points per unit length taken along
1990 the U axis in parametric coordinates. It is needed when
1991 `GLU_SAMPLING_METHOD' is set to `GLU_DOMAIN_DISTANCE'. The initial
1992 value is 100.
1993
1994`GLU_V_STEP'
1995 Specifies the number of sample points per unit length taken along
1996 the V axis in parametric coordinate. It is needed when
1997 `GLU_SAMPLING_METHOD' is set to `GLU_DOMAIN_DISTANCE'. The initial
1998 value is 100.
1999
2000`GLU_DISPLAY_MODE'
2001 VALUE can be set to `GLU_OUTLINE_POLYGON', `GLU_FILL', or
2002 `GLU_OUTLINE_PATCH'. When `GLU_NURBS_MODE' is set to be
2003 `GLU_NURBS_RENDERER', VALUE defines how a NURBS surface should be
2004 rendered. When VALUE is set to `GLU_FILL', the surface is rendered
2005 as a set of polygons. When VALUE is set to `GLU_OUTLINE_POLYGON',
2006 the NURBS library draws only the outlines of the polygons created
2007 by tessellation. When VALUE is set to `GLU_OUTLINE_PATCH' just the
2008 outlines of patches and trim curves defined by the user are drawn.
2009
2010 When `GLU_NURBS_MODE' is set to be `GLU_NURBS_TESSELLATOR', VALUE
2011 defines how a NURBS surface should be tessellated. When
2012 `GLU_DISPLAY_MODE' is set to `GLU_FILL' or `GLU_OUTLINE_POLYGON',
2013 the NURBS surface is tessellated into OpenGL triangle primitives
2014 that can be retrieved back through callback functions. If
2015 `GLU_DISPLAY_MODE' is set to `GLU_OUTLINE_PATCH', only the outlines
2016 of the patches and trim curves are generated as a sequence of line
2017 strips that can be retrieved back through callback functions.
2018
2019 The initial value is `GLU_FILL'.
2020
2021`GLU_CULLING'
2022 VALUE is a boolean value that, when set to `GLU_TRUE', indicates
2023 that a NURBS curve should be discarded prior to tessellation if its
2024 control points lie outside the current viewport. The initial value
2025 is `GLU_FALSE'.
2026
2027`GLU_AUTO_LOAD_MATRIX'
2028 VALUE is a boolean value. When set to `GLU_TRUE', the NURBS code
2029 downloads the projection matrix, the modelview matrix, and the
2030 viewport from the GL server to compute sampling and culling
2031 matrices for each NURBS curve that is rendered. Sampling and
2032 culling matrices are required to determine the tessellation of a
2033 NURBS surface into line segments or polygons and to cull a NURBS
2034 surface if it lies outside the viewport.
2035
2036 If this mode is set to `GLU_FALSE', then the program needs to
2037 provide a projection matrix, a modelview matrix, and a viewport for
2038 the NURBS renderer to use to construct sampling and culling
2039 matrices. This can be done with the `gluLoadSamplingMatrices'
2040 function. This mode is initially set to `GLU_TRUE'. Changing it
2041 from `GLU_TRUE' to `GLU_FALSE' does not affect the sampling and
2042 culling matrices until `gluLoadSamplingMatrices' is called.")
8925f36f
AW		 2043
2044(define-gl-procedure
2045 gluNurbsSurface
2046 "gluNurbsSurface"
2047 (funcsynopsis
2048 (funcprototype
2049 (funcdef "void " (function "gluNurbsSurface"))
2050 (paramdef "GLUnurbs* " (parameter "nurb"))
2051 (paramdef "GLint " (parameter "sKnotCount"))
2052 (paramdef "GLfloat* " (parameter "sKnots"))
2053 (paramdef "GLint " (parameter "tKnotCount"))
2054 (paramdef "GLfloat* " (parameter "tKnots"))
2055 (paramdef "GLint " (parameter "sStride"))
2056 (paramdef "GLint " (parameter "tStride"))
2057 (paramdef "GLfloat* " (parameter "control"))
2058 (paramdef "GLint " (parameter "sOrder"))
2059 (paramdef "GLint " (parameter "tOrder"))
2060 (paramdef "GLenum " (parameter "type"))))
3c9b6116
AW		 2061 "Define the shape of a NURBS surface.
2062
2063NURB
2064 Specifies the NURBS object (created with `gluNewNurbsRenderer').
2065
2066SKNOTCOUNT
2067 Specifies the number of knots in the parametric U direction.
2068
2069SKNOTS
2070 Specifies an array of SKNOTCOUNT nondecreasing knot values in the
2071 parametric U direction.
2072
2073TKNOTCOUNT
2074 Specifies the number of knots in the parametric V direction.
2075
2076TKNOTS
2077 Specifies an array of TKNOTCOUNT nondecreasing knot values in the
2078 parametric V direction.
2079
2080SSTRIDE
2081 Specifies the offset (as a number of single-precision
2082 floating-point values) between successive control points in the
2083 parametric U direction in CONTROL.
2084
2085TSTRIDE
2086 Specifies the offset (in single-precision floating-point values)
2087 between successive control points in the parametric V direction in
2088 CONTROL.
2089
2090CONTROL
2091 Specifies an array containing control points for the NURBS surface.
2092 The offsets between successive control points in the parametric U
2093 and V directions are given by SSTRIDE and TSTRIDE.
2094
2095SORDER
2096 Specifies the order of the NURBS surface in the parametric U
2097 direction. The order is one more than the degree, hence a surface
2098 that is cubic in U has a U order of 4.
2099
2100TORDER
2101 Specifies the order of the NURBS surface in the parametric V
2102 direction. The order is one more than the degree, hence a surface
2103 that is cubic in V has a V order of 4.
2104
2105TYPE
2106 Specifies type of the surface. TYPE can be any of the valid
2107 two-dimensional evaluator types (such as `GLU_MAP2_VERTEX_3' or
2108 `GLU_MAP2_COLOR_4').
2109
2110Use `gluNurbsSurface' within a NURBS (Non-Uniform Rational B-Spline)
2111surface definition to describe the shape of a NURBS surface (before any
2112trimming). To mark the beginning of a NURBS surface definition, use the
2113`gluBeginSurface' command. To mark the end of a NURBS surface
2114definition, use the `gluEndSurface' command. Call `gluNurbsSurface'
2115within a NURBS surface definition only.
2116
2117Positional, texture, and color coordinates are associated with a surface
2118by presenting each as a separate `gluNurbsSurface' between a
2119`gluBeginSurface'/`gluEndSurface' pair. No more than one call to
2120`gluNurbsSurface' for each of color, position, and texture data can be
2121made within a single `gluBeginSurface'/`gluEndSurface' pair. Exactly one
2122call must be made to describe the position of the surface (a TYPE of
2123`GLU_MAP2_VERTEX_3' or `GLU_MAP2_VERTEX_4').
2124
2125A NURBS surface can be trimmed by using the commands `gluNurbsCurve' and
2126`gluPwlCurve' between calls to `gluBeginTrim' and `gluEndTrim'.
2127
2128Note that a `gluNurbsSurface' with SKNOTCOUNT knots in the U direction
2129and TKNOTCOUNT knots in the V direction with orders SORDER and TORDER
2130must have (SKNOTCOUNT - SORDER) TIMES (TKNOTCOUNT - TORDER) control
2131points.")
8925f36f
AW		 2132
2133(define-gl-procedure
2134 gluOrtho2D
2135 "gluOrtho2D"
2136 (funcsynopsis
2137 (funcprototype
2138 (funcdef "void " (function "gluOrtho2D"))
2139 (paramdef "GLdouble " (parameter "left"))
2140 (paramdef "GLdouble " (parameter "right"))
2141 (paramdef "GLdouble " (parameter "bottom"))
2142 (paramdef "GLdouble " (parameter "top"))))
3c9b6116
AW		 2143 "Define a 2D orthographic projection matrix.
2144
2145LEFT
2146 RIGHT
2147
2148 Specify the coordinates for the left and right vertical clipping
2149 planes.
2150
2151BOTTOM
2152 TOP
2153
2154 Specify the coordinates for the bottom and top horizontal clipping
2155 planes.
2156
2157`gluOrtho2D' sets up a two-dimensional orthographic viewing region. This
2158is equivalent to calling `glOrtho' with NEAR=-1 and FAR=1 .")
8925f36f
AW		 2159
2160(define-gl-procedure
2161 gluPartialDisk
2162 "gluPartialDisk"
2163 (funcsynopsis
2164 (funcprototype
2165 (funcdef "void " (function "gluPartialDisk"))
2166 (paramdef "GLUquadric* " (parameter "quad"))
2167 (paramdef "GLdouble " (parameter "inner"))
2168 (paramdef "GLdouble " (parameter "outer"))
2169 (paramdef "GLint " (parameter "slices"))
2170 (paramdef "GLint " (parameter "loops"))
2171 (paramdef "GLdouble " (parameter "start"))
2172 (paramdef "GLdouble " (parameter "sweep"))))
3c9b6116
AW		 2173 "Draw an arc of a disk.
2174
2175QUAD
2176 Specifies a quadrics object (created with `gluNewQuadric').
2177
2178INNER
2179 Specifies the inner radius of the partial disk (can be 0).
2180
2181OUTER
2182 Specifies the outer radius of the partial disk.
2183
2184SLICES
2185 Specifies the number of subdivisions around the Z axis.
2186
2187LOOPS
2188 Specifies the number of concentric rings about the origin into
2189 which the partial disk is subdivided.
2190
2191START
2192 Specifies the starting angle, in degrees, of the disk portion.
2193
2194SWEEP
2195 Specifies the sweep angle, in degrees, of the disk portion.
2196
2197`gluPartialDisk' renders a partial disk on the Z=0 plane. A partial disk
2198is similar to a full disk, except that only the subset of the disk from
2199START through START + SWEEP is included (where 0 degrees is along the
2200+\\f2y\\f axis, 90 degrees along the +X axis, 180 degrees along the \\-Y
2201axis, and 270 degrees along the \\-X axis).
2202
2203The partial disk has a radius of OUTER and contains a concentric
2204circular hole with a radius of INNER. If INNER is 0, then no hole is
2205generated. The partial disk is subdivided around the Z axis into slices
2206(like pizza slices) and also about the Z axis into rings (as specified
2207by SLICES and LOOPS, respectively).
2208
2209With respect to orientation, the +Z side of the partial disk is
2210considered to be outside (see `gluQuadricOrientation'). This means that
2211if the orientation is set to `GLU_OUTSIDE', then any normals generated
2212point along the +Z axis. Otherwise, they point along the \\-Z axis.
2213
2214If texturing is turned on (with `gluQuadricTexture'), texture
2215coordinates are generated linearly such that where R=OUTER , the value
2216at (R, 0, 0) is (1.0, 0.5), at (0, R, 0) it is (0.5, 1.0), at (\\-R, 0,
22170) it is (0.0, 0.5), and at (0, \\-R, 0) it is (0.5, 0.0).")
8925f36f
AW		 2218
2219(define-gl-procedure
2220 gluPerspective
2221 "gluPerspective"
2222 (funcsynopsis
2223 (funcprototype
2224 (funcdef "void " (function "gluPerspective"))
2225 (paramdef "GLdouble " (parameter "fovy"))
2226 (paramdef "GLdouble " (parameter "aspect"))
2227 (paramdef "GLdouble " (parameter "zNear"))
2228 (paramdef "GLdouble " (parameter "zFar"))))
3c9b6116
AW		 2229 "Set up a perspective projection matrix.
2230
2231FOVY
2232 Specifies the field of view angle, in degrees, in the Y direction.
2233
2234ASPECT
2235 Specifies the aspect ratio that determines the field of view in the
2236 X direction. The aspect ratio is the ratio of X (width) to Y
2237 (height).
2238
2239ZNEAR
2240 Specifies the distance from the viewer to the near clipping plane
2241 (always positive).
2242
2243ZFAR
2244 Specifies the distance from the viewer to the far clipping plane
2245 (always positive).
2246
2247`gluPerspective' specifies a viewing frustum into the world coordinate
2248system. In general, the aspect ratio in `gluPerspective' should match
2249the aspect ratio of the associated viewport. For example, ASPECT=2.0
2250means the viewer's angle of view is twice as wide in X as it is in Y. If
2251the viewport is twice as wide as it is tall, it displays the image
2252without distortion.
2253
2254The matrix generated by `gluPerspective' is multipled by the current
2255matrix, just as if `glMultMatrix' were called with the generated matrix.
2256To load the perspective matrix onto the current matrix stack instead,
2257precede the call to `gluPerspective' with a call to `glLoadIdentity'.
2258
2259Given F defined as follows:
2260
2261F=COTANGENT\u2061(FOVY/2,) The generated matrix is
2262
2263((F/ASPECT 0 0 0), (0 F 0 0), (0 0 ZFAR+ZNEAR,/ZNEAR-ZFAR,
22642×ZFAR×ZNEAR,/ZNEAR-ZFAR,), (0 0 -1 0),)")
8925f36f
AW		 2265
2266(define-gl-procedure
2267 gluPickMatrix
2268 "gluPickMatrix"
2269 (funcsynopsis
2270 (funcprototype
2271 (funcdef "void " (function "gluPickMatrix"))
2272 (paramdef "GLdouble " (parameter "x"))
2273 (paramdef "GLdouble " (parameter "y"))
2274 (paramdef "GLdouble " (parameter "delX"))
2275 (paramdef "GLdouble " (parameter "delY"))
2276 (paramdef "GLint * " (parameter "viewport"))))
3c9b6116
AW		 2277 "Define a picking region.
2278
2279X
2280 Y
2281
2282 Specify the center of a picking region in window coordinates.
2283
2284DELX
2285 DELY
2286
2287 Specify the width and height, respectively, of the picking region
2288 in window coordinates.
2289
2290VIEWPORT
2291 Specifies the current viewport (as from a `glGetIntegerv' call).
2292
2293`gluPickMatrix' creates a projection matrix that can be used to restrict
2294drawing to a small region of the viewport. This is typically useful to
2295determine what objects are being drawn near the cursor. Use
2296`gluPickMatrix' to restrict drawing to a small region around the cursor.
2297Then, enter selection mode (with `glRenderMode') and rerender the scene.
2298All primitives that would have been drawn near the cursor are identified
2299and stored in the selection buffer.
2300
2301The matrix created by `gluPickMatrix' is multiplied by the current
2302matrix just as if `glMultMatrix' is called with the generated matrix. To
2303effectively use the generated pick matrix for picking, first call
2304`glLoadIdentity' to load an identity matrix onto the perspective matrix
2305stack. Then call `gluPickMatrix', and, finally, call a command (such as
2306`gluPerspective') to multiply the perspective matrix by the pick matrix.
2307
2308When using `gluPickMatrix' to pick NURBS, be careful to turn off the
2309NURBS property `GLU_AUTO_LOAD_MATRIX'. If `GLU_AUTO_LOAD_MATRIX' is not
2310turned off, then any NURBS surface rendered is subdivided differently
2311with the pick matrix than the way it was subdivided without the pick
2312matrix.")
8925f36f
AW		 2313
2314(define-gl-procedure
2315 gluProject
2316 "gluProject"
2317 (funcsynopsis
2318 (funcprototype
2319 (funcdef "GLint " (function "gluProject"))
2320 (paramdef "GLdouble " (parameter "objX"))
2321 (paramdef "GLdouble " (parameter "objY"))
2322 (paramdef "GLdouble " (parameter "objZ"))
2323 (paramdef
2324 "const GLdouble * "
2325 (parameter "model"))
2326 (paramdef "const GLdouble * " (parameter "proj"))
2327 (paramdef "const GLint * " (parameter "view"))
2328 (paramdef "GLdouble* " (parameter "winX"))
2329 (paramdef "GLdouble* " (parameter "winY"))
2330 (paramdef "GLdouble* " (parameter "winZ"))))
3c9b6116
AW		 2331 "Map object coordinates to window coordinates.
2332
2333OBJX
2334 OBJY
2335
2336 OBJZ
2337
2338 Specify the object coordinates.
2339
2340MODEL
2341 Specifies the current modelview matrix (as from a `glGetDoublev'
2342 call).
2343
2344PROJ
2345 Specifies the current projection matrix (as from a `glGetDoublev'
2346 call).
2347
2348VIEW
2349 Specifies the current viewport (as from a `glGetIntegerv' call).
2350
2351WINX
2352 WINY
2353
2354 WINZ
2355
2356 Return the computed window coordinates.
2357
2358`gluProject' transforms the specified object coordinates into window
2359coordinates using MODEL, PROJ, and VIEW. The result is stored in WINX,
2360WINY, and WINZ. A return value of `GLU_TRUE' indicates success, a return
2361value of `GLU_FALSE' indicates failure.
2362
2363To compute the coordinates, let V=(OBJX,OBJYOBJZ1.0) represented as a
2364matrix with 4 rows and 1 column. Then `gluProject' computes V^″ as
2365follows:
2366
2367V^″=P×M×V
2368
2369where P is the current projection matrix PROJ and M is the current
2370modelview matrix MODEL (both represented as 4×4 matrices in column-major
2371order).
2372
2373The window coordinates are then computed as follows:
2374
2375WINX=VIEW\u2061(0,)+VIEW\u2061(2,)×(V^″\u2061(0,)+1,)/2
2376WINY=VIEW\u2061(1,)+VIEW\u2061(3,)×(V^″\u2061(1,)+1,)/2 WINZ=(V^″\u2061(2,)+1,)/2")
8925f36f
AW		 2377
2378(define-gl-procedure
2379 gluPwlCurve
2380 "gluPwlCurve"
2381 (funcsynopsis
2382 (funcprototype
2383 (funcdef "void " (function "gluPwlCurve"))
2384 (paramdef "GLUnurbs* " (parameter "nurb"))
2385 (paramdef "GLint " (parameter "count"))
2386 (paramdef "GLfloat* " (parameter "data"))
2387 (paramdef "GLint " (parameter "stride"))
2388 (paramdef "GLenum " (parameter "type"))))
3c9b6116
AW		 2389 "Describe a piecewise linear NURBS trimming curve.
2390
2391NURB
2392 Specifies the NURBS object (created with `gluNewNurbsRenderer').
2393
2394COUNT
2395 Specifies the number of points on the curve.
2396
2397DATA
2398 Specifies an array containing the curve points.
2399
2400STRIDE
2401 Specifies the offset (a number of single-precision floating-point
2402 values) between points on the curve.
2403
2404TYPE
2405 Specifies the type of curve. Must be either `GLU_MAP1_TRIM_2' or
2406 `GLU_MAP1_TRIM_3'.
2407
2408`gluPwlCurve' describes a piecewise linear trimming curve for a NURBS
2409surface. A piecewise linear curve consists of a list of coordinates of
2410points in the parameter space for the NURBS surface to be trimmed. These
2411points are connected with line segments to form a curve. If the curve is
2412an approximation to a curve that is not piecewise linear, the points
2413should be close enough in parameter space that the resulting path
2414appears curved at the resolution used in the application.
2415
2416If TYPE is `GLU_MAP1_TRIM_2', then it describes a curve in
2417two-dimensional (U and V) parameter space. If it is `GLU_MAP1_TRIM_3',
2418then it describes a curve in two-dimensional homogeneous (U, V, and W)
2419parameter space. See the `gluBeginTrim' reference page for more
2420information about trimming curves.")
8925f36f
AW		 2421
2422(define-gl-procedure
2423 gluQuadricCallback
2424 "gluQuadricCallback"
2425 (funcsynopsis
2426 (funcprototype
2427 (funcdef "void " (function "gluQuadricCallback"))
2428 (paramdef "GLUquadric* " (parameter "quad"))
2429 (paramdef "GLenum " (parameter "which"))
2430 (paramdef
2431 "_GLUfuncptr "
2432 (parameter "CallBackFunc"))))
3c9b6116
AW		 2433 "Define a callback for a quadrics object.
2434
2435QUAD
2436 Specifies the quadrics object (created with `gluNewQuadric').
2437
2438WHICH
2439 Specifies the callback being defined. The only valid value is
2440 `GLU_ERROR'.
2441
2442CALLBACKFUNC
2443 Specifies the function to be called.
2444
2445`gluQuadricCallback' is used to define a new callback to be used by a
2446quadrics object. If the specified callback is already defined, then it
2447is replaced. If CALLBACKFUNC is NULL, then any existing callback is
2448erased.
2449
2450The one legal callback is `GLU_ERROR':
2451
2452`GLU_ERROR'
2453 The function is called when an error is encountered. Its single
2454 argument is of type GLenum, and it indicates the specific error
2455 that occurred. Character strings describing these errors can be
2456 retrieved with the `gluErrorString' call.")
8925f36f
AW		 2457
2458(define-gl-procedure
2459 gluQuadricDrawStyle
2460 "gluQuadricDrawStyle"
2461 (funcsynopsis
2462 (funcprototype
2463 (funcdef
2464 "void "
2465 (function "gluQuadricDrawStyle"))
2466 (paramdef "GLUquadric* " (parameter "quad"))
2467 (paramdef "GLenum " (parameter "draw"))))
3c9b6116
AW		 2468 "Specify the draw style desired for quadrics.
2469
2470QUAD
2471 Specifies the quadrics object (created with `gluNewQuadric').
2472
2473DRAW
2474 Specifies the desired draw style. Valid values are `GLU_FILL',
2475 `GLU_LINE', `GLU_SILHOUETTE', and `GLU_POINT'.
2476
2477`gluQuadricDrawStyle' specifies the draw style for quadrics rendered
2478with QUAD. The legal values are as follows:
2479
2480`GLU_FILL'
2481 Quadrics are rendered with polygon primitives. The polygons are
2482 drawn in a counterclockwise fashion with respect to their normals
2483 (as defined with `gluQuadricOrientation').
2484
2485`GLU_LINE'
2486 Quadrics are rendered as a set of lines.
2487
2488`GLU_SILHOUETTE'
2489 Quadrics are rendered as a set of lines, except that edges
2490 separating coplanar faces will not be drawn.
2491
2492`GLU_POINT'
2493 Quadrics are rendered as a set of points.")
8925f36f
AW		 2494
2495(define-gl-procedure
2496 gluQuadricNormals
2497 "gluQuadricNormals"
2498 (funcsynopsis
2499 (funcprototype
2500 (funcdef "void " (function "gluQuadricNormals"))
2501 (paramdef "GLUquadric* " (parameter "quad"))
2502 (paramdef "GLenum " (parameter "normal"))))
3c9b6116
AW		 2503 "Specify what kind of normals are desired for quadrics.
2504
2505QUAD
2506 Specifies the quadrics object (created with `gluNewQuadric').
2507
2508NORMAL
2509 Specifies the desired type of normals. Valid values are `GLU_NONE',
2510 `GLU_FLAT', and `GLU_SMOOTH'.
2511
2512`gluQuadricNormals' specifies what kind of normals are desired for
2513quadrics rendered with QUAD. The legal values are as follows:
2514
2515`GLU_NONE'
2516 No normals are generated.
2517
2518`GLU_FLAT'
2519 One normal is generated for every facet of a quadric.
2520
2521`GLU_SMOOTH'
2522 One normal is generated for every vertex of a quadric. This is the
2523 initial value.")
8925f36f
AW		 2524
2525(define-gl-procedure
2526 gluQuadricOrientation
2527 "gluQuadricOrientation"
2528 (funcsynopsis
2529 (funcprototype
2530 (funcdef
2531 "void "
2532 (function "gluQuadricOrientation"))
2533 (paramdef "GLUquadric* " (parameter "quad"))
2534 (paramdef "GLenum " (parameter "orientation"))))
3c9b6116
AW		 2535 "Specify inside/outside orientation for quadrics.
2536
2537QUAD
2538 Specifies the quadrics object (created with `gluNewQuadric').
2539
2540ORIENTATION
2541 Specifies the desired orientation. Valid values are `GLU_OUTSIDE'
2542 and `GLU_INSIDE'.
2543
2544`gluQuadricOrientation' specifies what kind of orientation is desired
2545for quadrics rendered with QUAD. The ORIENTATION values are as follows:
2546
2547`GLU_OUTSIDE'
2548 Quadrics are drawn with normals pointing outward (the initial
2549 value).
2550
2551`GLU_INSIDE'
2552 Quadrics are drawn with normals pointing inward.
2553
2554Note that the interpretation of OUTWARD and INWARD depends on the
2555quadric being drawn.")
8925f36f
AW		 2556
2557(define-gl-procedure
2558 gluQuadricTexture
2559 "gluQuadricTexture"
2560 (funcsynopsis
2561 (funcprototype
2562 (funcdef "void " (function "gluQuadricTexture"))
2563 (paramdef "GLUquadric* " (parameter "quad"))
2564 (paramdef "GLboolean " (parameter "texture"))))
3c9b6116
AW		 2565 "Specify if texturing is desired for quadrics.
2566
2567QUAD
2568 Specifies the quadrics object (created with `gluNewQuadric').
2569
2570TEXTURE
2571 Specifies a flag indicating if texture coordinates should be
2572 generated.
2573
2574`gluQuadricTexture' specifies if texture coordinates should be generated
2575for quadrics rendered with QUAD. If the value of TEXTURE is `GLU_TRUE',
2576then texture coordinates are generated, and if TEXTURE is `GLU_FALSE',
2577they are not. The initial value is `GLU_FALSE'.
2578
2579The manner in which texture coordinates are generated depends upon the
2580specific quadric rendered.")
8925f36f
AW		 2581
2582(define-gl-procedure
2583 gluScaleImage
2584 "gluScaleImage"
2585 (funcsynopsis
2586 (funcprototype
2587 (funcdef "GLint " (function "gluScaleImage"))
2588 (paramdef "GLenum " (parameter "format"))
2589 (paramdef "GLsizei " (parameter "wIn"))
2590 (paramdef "GLsizei " (parameter "hIn"))
2591 (paramdef "GLenum " (parameter "typeIn"))
2592 (paramdef "const void * " (parameter "dataIn"))
2593 (paramdef "GLsizei " (parameter "wOut"))
2594 (paramdef "GLsizei " (parameter "hOut"))
2595 (paramdef "GLenum " (parameter "typeOut"))
2596 (paramdef "GLvoid* " (parameter "dataOut"))))
3c9b6116
AW		 2597 "Scale an image to an arbitrary size.
2598
2599FORMAT
2600 Specifies the format of the pixel data. The following symbolic
2601 values are valid: `GLU_COLOR_INDEX', `GLU_STENCIL_INDEX',
2602 `GLU_DEPTH_COMPONENT', `GLU_RED', `GLU_GREEN', `GLU_BLUE',
2603 `GLU_ALPHA', `GLU_RGB', `GLU_RGBA', `GLU_BGR', `GLU_BGRA',
2604 `GLU_LUMINANCE', and `GLU_LUMINANCE_ALPHA'.
2605
2606WIN
2607 HIN
2608
2609 Specify in pixels the width and height, respectively, of the source
2610 image.
2611
2612TYPEIN
2613 Specifies the data type for DATAIN. Must be one of
2614 `GLU_UNSIGNED_BYTE', `GLU_BYTE', `GLU_BITMAP',
2615 `GLU_UNSIGNED_SHORT', `GLU_SHORT', `GLU_UNSIGNED_INT', `GLU_INT',
2616 `GLU_FLOAT', `GLU_UNSIGNED_BYTE_3_3_2',
2617 `GLU_UNSIGNED_BYTE_2_3_3_REV', `GLU_UNSIGNED_SHORT_5_6_5',
2618 `GLU_UNSIGNED_SHORT_5_6_5_REV', `GLU_UNSIGNED_SHORT_4_4_4_4',
2619 `GLU_UNSIGNED_SHORT_4_4_4_4_REV', `GLU_UNSIGNED_SHORT_5_5_5_1',
2620 `GLU_UNSIGNED_SHORT_1_5_5_5_REV', `GLU_UNSIGNED_INT_8_8_8_8',
2621 `GLU_UNSIGNED_INT_8_8_8_8_REV', `GLU_UNSIGNED_INT_10_10_10_2', or
2622 `GLU_UNSIGNED_INT_2_10_10_10_REV'.
2623
2624DATAIN
2625 Specifies a pointer to the source image.
2626
2627WOUT
2628 HOUT
2629
2630 Specify the width and height, respectively, in pixels of the
2631 destination image.
2632
2633TYPEOUT
2634 Specifies the data type for DATAOUT. Must be one of
2635 `GLU_UNSIGNED_BYTE', `GLU_BYTE', `GLU_BITMAP',
2636 `GLU_UNSIGNED_SHORT', `GLU_SHORT', `GLU_UNSIGNED_INT', `GLU_INT',
2637 `GLU_FLOAT', `GLU_UNSIGNED_BYTE_3_3_2',
2638 `GLU_UNSIGNED_BYTE_2_3_3_REV', `GLU_UNSIGNED_SHORT_5_6_5',
2639 `GLU_UNSIGNED_SHORT_5_6_5_REV', `GLU_UNSIGNED_SHORT_4_4_4_4',
2640 `GLU_UNSIGNED_SHORT_4_4_4_4_REV', `GLU_UNSIGNED_SHORT_5_5_5_1',
2641 `GLU_UNSIGNED_SHORT_1_5_5_5_REV', `GLU_UNSIGNED_INT_8_8_8_8',
2642 `GLU_UNSIGNED_INT_8_8_8_8_REV', `GLU_UNSIGNED_INT_10_10_10_2', or
2643 `GLU_UNSIGNED_INT_2_10_10_10_REV'.
2644
2645DATAOUT
2646 Specifies a pointer to the destination image.
2647
2648`gluScaleImage' scales a pixel image using the appropriate pixel store
2649modes to unpack data from the source image and pack data into the
2650destination image.
2651
2652When shrinking an image, `gluScaleImage' uses a box filter to sample the
2653source image and create pixels for the destination image. When
2654magnifying an image, the pixels from the source image are linearly
2655interpolated to create the destination image.
2656
2657A return value of zero indicates success, otherwise a GLU error code is
2658returned (see `gluErrorString').
2659
2660See the `glReadPixels' reference page for a description of the
2661acceptable values for the FORMAT, TYPEIN, and TYPEOUT parameters.
2662
2663`GLU_INVALID_VALUE' is returned if WIN, HIN, WOUT, or HOUT is negative.
2664
2665`GLU_INVALID_ENUM' is returned if FORMAT, TYPEIN, or TYPEOUT is not
2666legal.
2667
2668`GLU_INVALID_OPERATION' is returned if TYPEIN or TYPEOUT is
2669`GLU_UNSIGNED_BYTE_3_3_2' or `GLU_UNSIGNED_BYTE_2_3_3_REV' and FORMAT is
2670not `GLU_RGB'.
2671
2672`GLU_INVALID_OPERATION' is returned if TYPEIN or TYPEOUT is
2673`GLU_UNSIGNED_SHORT_5_6_5' or `GLU_UNSIGNED_SHORT_5_6_5_REV' and FORMAT
2674is not `GLU_RGB'.
2675
2676`GLU_INVALID_OPERATION' is returned if TYPEIN or TYPEOUT is
2677`GLU_UNSIGNED_SHORT_4_4_4_4' or `GLU_UNSIGNED_SHORT_4_4_4_4_REV' and
2678FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
2679
2680`GLU_INVALID_OPERATION' is returned if TYPEIN or TYPEOUT is
2681`GLU_UNSIGNED_SHORT_5_5_5_1' or `GLU_UNSIGNED_SHORT_1_5_5_5_REV' and
2682FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.
2683
2684`GLU_INVALID_OPERATION' is returned if TYPEIN or TYPEOUT is
2685`GLU_UNSIGNED_INT_8_8_8_8' or `GLU_UNSIGNED_INT_8_8_8_8_REV' and FORMAT
2686is neither `GLU_RGBA' nor `GLU_BGRA'.
2687
2688`GLU_INVALID_OPERATION' is returned if TYPEIN or TYPEOUT is
2689`GLU_UNSIGNED_INT_10_10_10_2' or `GLU_UNSIGNED_INT_2_10_10_10_REV' and
2690FORMAT is neither `GLU_RGBA' nor `GLU_BGRA'.")
8925f36f
AW		 2691
2692(define-gl-procedure
2693 gluSphere
2694 "gluSphere"
2695 (funcsynopsis
2696 (funcprototype
2697 (funcdef "void " (function "gluSphere"))
2698 (paramdef "GLUquadric* " (parameter "quad"))
2699 (paramdef "GLdouble " (parameter "radius"))
2700 (paramdef "GLint " (parameter "slices"))
2701 (paramdef "GLint " (parameter "stacks"))))
3c9b6116
AW		 2702 "Draw a sphere.
2703
2704QUAD
2705 Specifies the quadrics object (created with `gluNewQuadric').
2706
2707RADIUS
2708 Specifies the radius of the sphere.
2709
2710SLICES
2711 Specifies the number of subdivisions around the Z axis (similar to
2712 lines of longitude).
2713
2714STACKS
2715 Specifies the number of subdivisions along the Z axis (similar to
2716 lines of latitude).
2717
2718`gluSphere' draws a sphere of the given radius centered around the
2719origin. The sphere is subdivided around the Z axis into slices and along
2720the Z axis into stacks (similar to lines of longitude and latitude).
2721
2722If the orientation is set to `GLU_OUTSIDE' (with
2723`gluQuadricOrientation'), then any normals generated point away from the
2724center of the sphere. Otherwise, they point toward the center of the
2725sphere.
2726
2727If texturing is turned on (with `gluQuadricTexture'), then texture
2728coordinates are generated so that T ranges from 0.0 at Z=-RADIUS to 1.0
2729at Z=RADIUS (T increases linearly along longitudinal lines), and S
2730ranges from 0.0 at the +Y axis, to 0.25 at the +X axis, to 0.5 at the
2731\\-Y axis, to 0.75 at the \\-X axis, and back to 1.0 at the +Y axis.")
8925f36f
AW		 2732
2733(define-gl-procedure
2734 gluTessBeginContour
2735 "gluTessBeginContour"
2736 (funcsynopsis
2737 (funcprototype
2738 (funcdef
2739 "void "
2740 (function "gluTessBeginContour"))
2741 (paramdef "GLUtesselator* " (parameter "tess"))))
3c9b6116
AW		 2742 "Delimit a contour description.
2743
2744TESS
2745 Specifies the tessellation object (created with `gluNewTess').
2746
2747`gluTessBeginContour' and `gluTessEndContour' delimit the definition of
2748a polygon contour. Within each `gluTessBeginContour'/`gluTessEndContour'
2749pair, there can be zero or more calls to `gluTessVertex'. The vertices
2750specify a closed contour (the last vertex of each contour is
2751automatically linked to the first). See the `gluTessVertex' reference
2752page for more details. `gluTessBeginContour' can only be called between
2753`gluTessBeginPolygon' and `gluTessEndPolygon'.")
8925f36f
AW		 2754
2755(define-gl-procedure
2756 gluTessBeginPolygon
2757 "gluTessBeginPolygon"
2758 (funcsynopsis
2759 (funcprototype
2760 (funcdef
2761 "void "
2762 (function "gluTessBeginPolygon"))
2763 (paramdef "GLUtesselator* " (parameter "tess"))
2764 (paramdef "GLvoid* " (parameter "data"))))
3c9b6116
AW		 2765 "Delimit a polygon description.
2766
2767TESS
2768 Specifies the tessellation object (created with `gluNewTess').
2769
2770DATA
2771 Specifies a pointer to user polygon data.
2772
2773`gluTessBeginPolygon' and `gluTessEndPolygon' delimit the definition of
2774a convex, concave or self-intersecting polygon. Within each
2775`gluTessBeginPolygon'/`gluTessEndPolygon' pair, there must be one or
2776more calls to `gluTessBeginContour'/`gluTessEndContour'. Within each
2777contour, there are zero or more calls to `gluTessVertex'. The vertices
2778specify a closed contour (the last vertex of each contour is
2779automatically linked to the first). See the `gluTessVertex',
2780`gluTessBeginContour', and `gluTessEndContour' reference pages for more
2781details.
2782
2783DATA is a pointer to a user-defined data structure. If the appropriate
2784callback(s) are specified (see `gluTessCallback'), then this pointer is
2785returned to the callback function(s). Thus, it is a convenient way to
2786store per-polygon information.
2787
2788Once `gluTessEndPolygon' is called, the polygon is tessellated, and the
2789resulting triangles are described through callbacks. See
2790`gluTessCallback' for descriptions of the callback functions.")
8925f36f
AW		 2791
2792(define-gl-procedure
2793 gluTessCallback
2794 "gluTessCallback"
2795 (funcsynopsis
2796 (funcprototype
2797 (funcdef "void " (function "gluTessCallback"))
2798 (paramdef "GLUtesselator* " (parameter "tess"))
2799 (paramdef "GLenum " (parameter "which"))
2800 (paramdef
2801 "_GLUfuncptr "
2802 (parameter "CallBackFunc"))))
3c9b6116
AW		 2803 "Define a callback for a tessellation object.
2804
2805TESS
2806 Specifies the tessellation object (created with `gluNewTess').
2807
2808WHICH
2809 Specifies the callback being defined. The following values are
2810 valid: `GLU_TESS_BEGIN', `GLU_TESS_BEGIN_DATA',
2811 `GLU_TESS_EDGE_FLAG', `GLU_TESS_EDGE_FLAG_DATA', `GLU_TESS_VERTEX',
2812 `GLU_TESS_VERTEX_DATA', `GLU_TESS_END', `GLU_TESS_END_DATA',
2813 `GLU_TESS_COMBINE', `GLU_TESS_COMBINE_DATA', `GLU_TESS_ERROR', and
2814 `GLU_TESS_ERROR_DATA'.
2815
2816CALLBACKFUNC
2817 Specifies the function to be called.
2818
2819`gluTessCallback' is used to indicate a callback to be used by a
2820tessellation object. If the specified callback is already defined, then
2821it is replaced. If CALLBACKFUNC is NULL, then the existing callback
2822becomes undefined.
2823
2824These callbacks are used by the tessellation object to describe how a
2825polygon specified by the user is broken into triangles. Note that there
2826are two versions of each callback: one with user-specified polygon data
2827and one without. If both versions of a particular callback are
2828specified, then the callback with user-specified polygon data will be
2829used. Note that the POLYGON_DATA parameter used by some of the functions
2830is a copy of the pointer that was specified when `gluTessBeginPolygon'
2831was called. The legal callbacks are as follows:
2832
2833`GLU_TESS_BEGIN'
2834 The begin callback is invoked like `glBegin' to indicate the start
2835 of a (triangle) primitive. The function takes a single argument of
2836 type GLenum. If the `GLU_TESS_BOUNDARY_ONLY' property is set to
2837 `GLU_FALSE', then the argument is set to either `GLU_TRIANGLE_FAN',
2838 `GLU_TRIANGLE_STRIP', or `GLU_TRIANGLES'. If the
2839 `GLU_TESS_BOUNDARY_ONLY' property is set to `GLU_TRUE', then the
2840 argument will be set to `GLU_LINE_LOOP'. The function prototype for
2841 this callback is:
2842
2843`GLU_TESS_BEGIN_DATA'
2844 The same as the `GLU_TESS_BEGIN' callback except that it takes an
2845 additional pointer argument. This pointer is identical to the
2846 opaque pointer provided when `gluTessBeginPolygon' was called. The
2847 function prototype for this callback is:
2848
2849`GLU_TESS_EDGE_FLAG'
2850 The edge flag callback is similar to `glEdgeFlag'. The function
2851 takes a single boolean flag that indicates which edges lie on the
2852 polygon boundary. If the flag is `GLU_TRUE', then each vertex that
2853 follows begins an edge that lies on the polygon boundary, that is,
2854 an edge that separates an interior region from an exterior one. If
2855 the flag is `GLU_FALSE', then each vertex that follows begins an
2856 edge that lies in the polygon interior. The edge flag callback (if
2857 defined) is invoked before the first vertex callback.
2858
2859 Since triangle fans and triangle strips do not support edge flags,
2860 the begin callback is not called with `GLU_TRIANGLE_FAN' or
2861 `GLU_TRIANGLE_STRIP' if a non-NULL edge flag callback is provided.
2862 (If the callback is initialized to NULL, there is no impact on
2863 performance). Instead, the fans and strips are converted to
2864 independent triangles. The function prototype for this callback is:
2865
2866`GLU_TESS_EDGE_FLAG_DATA'
2867 The same as the `GLU_TESS_EDGE_FLAG' callback except that it takes
2868 an additional pointer argument. This pointer is identical to the
2869 opaque pointer provided when `gluTessBeginPolygon' was called. The
2870 function prototype for this callback is:
2871
2872`GLU_TESS_VERTEX'
2873 The vertex callback is invoked between the begin and end callbacks.
2874 It is similar to `glVertex', and it defines the vertices of the
2875 triangles created by the tessellation process. The function takes a
2876 pointer as its only argument. This pointer is identical to the
2877 opaque pointer provided by the user when the vertex was described
2878 (see `gluTessVertex'). The function prototype for this callback is:
2879
2880`GLU_TESS_VERTEX_DATA'
2881 The same as the `GLU_TESS_VERTEX' callback except that it takes an
2882 additional pointer argument. This pointer is identical to the
2883 opaque pointer provided when `gluTessBeginPolygon' was called. The
2884 function prototype for this callback is:
2885
2886`GLU_TESS_END'
2887 The end callback serves the same purpose as `glEnd'. It indicates
2888 the end of a primitive and it takes no arguments. The function
2889 prototype for this callback is:
2890
2891`GLU_TESS_END_DATA'
2892 The same as the `GLU_TESS_END' callback except that it takes an
2893 additional pointer argument. This pointer is identical to the
2894 opaque pointer provided when `gluTessBeginPolygon' was called. The
2895 function prototype for this callback is:
2896
2897`GLU_TESS_COMBINE'
2898 The combine callback is called to create a new vertex when the
2899 tessellation detects an intersection or wishes to merge features.
2900 The function takes four arguments: an array of three elements each
2901 of type GLdouble, an array of four pointers, an array of four
2902 elements each of type GLfloat, and a pointer to a pointer. The
2903 prototype is:
2904
2905 The vertex is defined as a linear combination of up to four
2906 existing vertices, stored in VERTEX_DATA. The coefficients of the
2907 linear combination are given by WEIGHT; these weights always add up
2908 to 1. All vertex pointers are valid even when some of the weights
2909 are 0. COORDS gives the location of the new vertex.
2910
2911 The user must allocate another vertex, interpolate parameters using
2912 VERTEX_DATA and WEIGHT, and return the new vertex pointer in
2913 OUTDATA. This handle is supplied during rendering callbacks. The
2914 user is responsible for freeing the memory some time after
2915 `gluTessEndPolygon' is called.
2916
2917 For example, if the polygon lies in an arbitrary plane in 3-space,
2918 and a color is associated with each vertex, the `GLU_TESS_COMBINE'
2919 callback might look like this:
2920
2921 If the tessellation detects an intersection, then the
2922 `GLU_TESS_COMBINE' or `GLU_TESS_COMBINE_DATA' callback (see below)
2923 must be defined, and it must write a non-NULL pointer into DATAOUT.
2924 Otherwise the `GLU_TESS_NEED_COMBINE_CALLBACK' error occurs, and no
2925 output is generated.
2926
2927`GLU_TESS_COMBINE_DATA'
2928 The same as the `GLU_TESS_COMBINE' callback except that it takes an
2929 additional pointer argument. This pointer is identical to the
2930 opaque pointer provided when `gluTessBeginPolygon' was called. The
2931 function prototype for this callback is:
2932
2933`GLU_TESS_ERROR'
2934 The error callback is called when an error is encountered. The one
2935 argument is of type GLenum; it indicates the specific error that
2936 occurred and will be set to one of
2937 `GLU_TESS_MISSING_BEGIN_POLYGON', `GLU_TESS_MISSING_END_POLYGON',
2938 `GLU_TESS_MISSING_BEGIN_CONTOUR', `GLU_TESS_MISSING_END_CONTOUR',
2939 `GLU_TESS_COORD_TOO_LARGE', `GLU_TESS_NEED_COMBINE_CALLBACK', or
2940 `GLU_OUT_OF_MEMORY'. Character strings describing these errors can
2941 be retrieved with the `gluErrorString' call. The function prototype
2942 for this callback is:
2943
2944 The GLU library will recover from the first four errors by
2945 inserting the missing call(s). `GLU_TESS_COORD_TOO_LARGE' indicates
2946 that some vertex coordinate exceeded the predefined constant
2947 `GLU_TESS_MAX_COORD' in absolute value, and that the value has been
2948 clamped. (Coordinate values must be small enough so that two can be
2949 multiplied together without overflow.)
2950 `GLU_TESS_NEED_COMBINE_CALLBACK' indicates that the tessellation
2951 detected an intersection between two edges in the input data, and
2952 the `GLU_TESS_COMBINE' or `GLU_TESS_COMBINE_DATA' callback was not
2953 provided. No output is generated. `GLU_OUT_OF_MEMORY' indicates
2954 that there is not enough memory so no output is generated.
2955
2956`GLU_TESS_ERROR_DATA'
2957 The same as the `GLU_TESS_ERROR' callback except that it takes an
2958 additional pointer argument. This pointer is identical to the
2959 opaque pointer provided when `gluTessBeginPolygon' was called. The
2960 function prototype for this callback is:
2961
2962
2963 void begin( GLenum type );
2964
2965
2966 void beginData( GLenum type, void *polygon_data );
2967
2968
2969 void edgeFlag( GLboolean flag );
2970
2971
2972 void edgeFlagData( GLboolean flag, void *polygon_data );
2973
2974
2975 void vertex( void *vertex_data );
2976
2977
2978 void vertexData( void *vertex_data, void *polygon_data );
2979
2980
2981 void end( void );
2982
2983
2984 void endData( void *polygon_data );
2985
2986
2987 void combine( GLdouble coords[3], void *vertex_data[4],
2988 GLfloat weight[4], void **outData );
2989
2990
2991 void myCombine( GLdouble coords[3], VERTEX *d[4],
2992 GLfloat w[4], VERTEX **dataOut )
2993 {
2994 VERTEX *new = new_vertex();
2995
2996 new->x = coords[0];
2997 new->y = coords[1];
2998 new->z = coords[2];
2999 new->r = w[0]*d[0]->r + w[1]*d[1]->r + w[2]*d[2]->r + w[3]*d[3]->r;
3000 new->g = w[0]*d[0]->g + w[1]*d[1]->g + w[2]*d[2]->g + w[3]*d[3]->g;
3001 new->b = w[0]*d[0]->b + w[1]*d[1]->b + w[2]*d[2]->b + w[3]*d[3]->b;
3002 new->a = w[0]*d[0]->a + w[1]*d[1]->a + w[2]*d[2]->a + w[3]*d[3]->a;
3003 *dataOut = new;
3004 }
3005
3006
3007 void combineData( GLdouble coords[3], void *vertex_data[4],
3008 GLfloat weight[4], void **outData,
3009 void *polygon_data );
3010
3011
3012 void error( GLenum errno );
3013
3014
3015 void errorData( GLenum errno, void *polygon_data );")
8925f36f
AW		 3016
3017(define-gl-procedure
3018 gluTessEndPolygon
3019 "gluTessEndPolygon"
3020 (funcsynopsis
3021 (funcprototype
3022 (funcdef "void " (function "gluTessEndPolygon"))
3023 (paramdef "GLUtesselator* " (parameter "tess"))))
3c9b6116
AW		 3024 "Delimit a polygon description.
3025
3026TESS
3027 Specifies the tessellation object (created with `gluNewTess').
3028
3029`gluTessBeginPolygon' and `gluTessEndPolygon' delimit the definition of
3030a convex, concave, or self-intersecting polygon. Within each
3031`gluTessBeginPolygon'/`gluTessEndPolygon' pair, there must be one or
3032more calls to `gluTessBeginContour'/`gluTessEndContour'. Within each
3033contour, there are zero or more calls to `gluTessVertex'. The vertices
3034specify a closed contour (the last vertex of each contour is
3035automatically linked to the first). See the `gluTessVertex',
3036`gluTessBeginContour', and `gluTessEndContour' reference pages for more
3037details.
3038
3039Once `gluTessEndPolygon' is called, the polygon is tessellated, and the
3040resulting triangles are described through callbacks. See
3041`gluTessCallback' for descriptions of the callback functions.")
8925f36f
AW		 3042
3043(define-gl-procedure
3044 gluTessNormal
3045 "gluTessNormal"
3046 (funcsynopsis
3047 (funcprototype
3048 (funcdef "void " (function "gluTessNormal"))
3049 (paramdef "GLUtesselator* " (parameter "tess"))
3050 (paramdef "GLdouble " (parameter "valueX"))
3051 (paramdef "GLdouble " (parameter "valueY"))
3052 (paramdef "GLdouble " (parameter "valueZ"))))
3c9b6116
AW		 3053 "Specify a normal for a polygon.
3054
3055TESS
3056 Specifies the tessellation object (created with `gluNewTess').
3057
3058VALUEX
3059 Specifies the first component of the normal.
3060
3061VALUEY
3062 Specifies the second component of the normal.
3063
3064VALUEZ
3065 Specifies the third component of the normal.
3066
3067`gluTessNormal' describes a normal for a polygon that the program is
3068defining. All input data will be projected onto a plane perpendicular to
3069one of the three coordinate axes before tessellation and all output
3070triangles will be oriented CCW with respect to the normal (CW
3071orientation can be obtained by reversing the sign of the supplied
3072normal). For example, if you know that all polygons lie in the x-y
3073plane, call `gluTessNormal'(tess, 0.0, 0.0, 1.0) before rendering any
3074polygons.
3075
3076If the supplied normal is (0.0, 0.0, 0.0) (the initial value), the
3077normal is determined as follows. The direction of the normal, up to its
3078sign, is found by fitting a plane to the vertices, without regard to how
3079the vertices are connected. It is expected that the input data lies
3080approximately in the plane; otherwise, projection perpendicular to one
3081of the three coordinate axes may substantially change the geometry. The
3082sign of the normal is chosen so that the sum of the signed areas of all
3083input contours is nonnegative (where a CCW contour has positive area).
3084
3085The supplied normal persists until it is changed by another call to
3086`gluTessNormal'.")
8925f36f
AW		 3087
3088(define-gl-procedure
3089 gluTessProperty
3090 "gluTessProperty"
3091 (funcsynopsis
3092 (funcprototype
3093 (funcdef "void " (function "gluTessProperty"))
3094 (paramdef "GLUtesselator* " (parameter "tess"))
3095 (paramdef "GLenum " (parameter "which"))
3096 (paramdef "GLdouble " (parameter "data"))))
3c9b6116
AW		 3097 "Set a tessellation object property.
3098
3099TESS
3100 Specifies the tessellation object (created with `gluNewTess').
3101
3102WHICH
3103 Specifies the property to be set. Valid values are
3104 `GLU_TESS_WINDING_RULE', `GLU_TESS_BOUNDARY_ONLY', and
3105 `GLU_TESS_TOLERANCE'.
3106
3107DATA
3108 Specifies the value of the indicated property.
3109
3110`gluTessProperty' is used to control properties stored in a tessellation
3111object. These properties affect the way that the polygons are
3112interpreted and rendered. The legal values for WHICH are as follows:
3113
3114`GLU_TESS_WINDING_RULE'
3115 Determines which parts of the polygon are on the ``interior''. DATA
3116 may be set to one of `GLU_TESS_WINDING_ODD',
3117 `GLU_TESS_WINDING_NONZERO', `GLU_TESS_WINDING_POSITIVE',
3118 `GLU_TESS_WINDING_NEGATIVE', or `GLU_TESS_WINDING_ABS_GEQ_TWO'.
3119
3120 To understand how the winding rule works, consider that the input
3121 contours partition the plane into regions. The winding rule
3122 determines which of these regions are inside the polygon.
3123
3124 For a single contour C, the winding number of a point x is simply
3125 the signed number of revolutions we make around x as we travel once
3126 around C (where CCW is positive). When there are several contours,
3127 the individual winding numbers are summed. This procedure
3128 associates a signed integer value with each point x in the plane.
3129 Note that the winding number is the same for all points in a single
3130 region.
3131
3132 The winding rule classifies a region as ``inside'' if its winding
3133 number belongs to the chosen category (odd, nonzero, positive,
3134 negative, or absolute value of at least two). The previous GLU
3135 tessellator (prior to GLU 1.2) used the ``odd'' rule. The
3136 ``nonzero'' rule is another common way to define the interior. The
3137 other three rules are useful for polygon CSG operations.
3138
3139`GLU_TESS_BOUNDARY_ONLY'
3140 Is a boolean value (``value'' should be set to GL_TRUE or
3141 GL_FALSE). When set to GL_TRUE, a set of closed contours separating
3142 the polygon interior and exterior are returned instead of a
3143 tessellation. Exterior contours are oriented CCW with respect to
3144 the normal; interior contours are oriented CW. The `GLU_TESS_BEGIN'
3145 and `GLU_TESS_BEGIN_DATA' callbacks use the type GL_LINE_LOOP for
3146 each contour.
3147
3148`GLU_TESS_TOLERANCE'
3149 Specifies a tolerance for merging features to reduce the size of
3150 the output. For example, two vertices that are very close to each
3151 other might be replaced by a single vertex. The tolerance is
3152 multiplied by the largest coordinate magnitude of any input vertex;
3153 this specifies the maximum distance that any feature can move as
3154 the result of a single merge operation. If a single feature takes
3155 part in several merge operations, the total distance moved could be
3156 larger.
3157
3158 Feature merging is completely optional; the tolerance is only a
3159 hint. The implementation is free to merge in some cases and not in
3160 others, or to never merge features at all. The initial tolerance is
3161 0.
3162
3163 The current implementation merges vertices only if they are exactly
3164 coincident, regardless of the current tolerance. A vertex is
3165 spliced into an edge only if the implementation is unable to
3166 distinguish which side of the edge the vertex lies on. Two edges
3167 are merged only when both endpoints are identical.")
8925f36f
AW		 3168
3169(define-gl-procedure
3170 gluTessVertex
3171 "gluTessVertex"
3172 (funcsynopsis
3173 (funcprototype
3174 (funcdef "void " (function "gluTessVertex"))
3175 (paramdef "GLUtesselator* " (parameter "tess"))
3176 (paramdef "GLdouble * " (parameter "location"))
3177 (paramdef "GLvoid* " (parameter "data"))))
3c9b6116
AW		 3178 "Specify a vertex on a polygon.
3179
3180TESS
3181 Specifies the tessellation object (created with `gluNewTess').
3182
3183LOCATION
3184 Specifies the location of the vertex.
3185
3186DATA
3187 Specifies an opaque pointer passed back to the program with the
3188 vertex callback (as specified by `gluTessCallback').
3189
3190`gluTessVertex' describes a vertex on a polygon that the program
3191defines. Successive `gluTessVertex' calls describe a closed contour. For
3192example, to describe a quadrilateral, `gluTessVertex' should be called
3193four times. `gluTessVertex' can only be called between
3194`gluTessBeginContour' and `gluTessEndContour'.
3195
3196DATA normally points to a structure containing the vertex location, as
3197well as other per-vertex attributes such as color and normal. This
3198pointer is passed back to the user through the `GLU_TESS_VERTEX' or
3199`GLU_TESS_VERTEX_DATA' callback after tessellation (see the
3200`gluTessCallback' reference page).")
8925f36f
AW		 3201
3202(define-gl-procedure
3203 gluUnProject4
3204 "gluUnProject4"
3205 (funcsynopsis
3206 (funcprototype
3207 (funcdef "GLint " (function "gluUnProject4"))
3208 (paramdef "GLdouble " (parameter "winX"))
3209 (paramdef "GLdouble " (parameter "winY"))
3210 (paramdef "GLdouble " (parameter "winZ"))
3211 (paramdef "GLdouble " (parameter "clipW"))
3212 (paramdef
3213 "const GLdouble * "
3214 (parameter "model"))
3215 (paramdef "const GLdouble * " (parameter "proj"))
3216 (paramdef "const GLint * " (parameter "view"))
3217 (paramdef "GLdouble " (parameter "nearVal"))
3218 (paramdef "GLdouble " (parameter "farVal"))
3219 (paramdef "GLdouble* " (parameter "objX"))
3220 (paramdef "GLdouble* " (parameter "objY"))
3221 (paramdef "GLdouble* " (parameter "objZ"))
3222 (paramdef "GLdouble* " (parameter "objW"))))
3c9b6116
AW		 3223 "Map window and clip coordinates to object coordinates.
3224
3225WINX
3226 WINY
3227
3228 WINZ
3229
3230 Specify the window coordinates to be mapped.
3231
3232CLIPW
3233 Specify the clip w coordinate to be mapped.
3234
3235MODEL
3236 Specifies the modelview matrix (as from a `glGetDoublev' call).
3237
3238PROJ
3239 Specifies the projection matrix (as from a `glGetDoublev' call).
3240
3241VIEW
3242 Specifies the viewport (as from a `glGetIntegerv' call).
3243
3244NEARVAL
3245 FARVAL
3246
3247 Specifies the near and far planes (as from a `glGetDoublev' call).
3248
3249OBJX
3250 OBJY
3251
3252 OBJZ
3253
3254 OBJW
3255
3256 Returns the computed object coordinates.
3257
3258`gluUnProject4' maps the specified window coordinatesi: WINX, WINY, and
3259WINZ and its clip w coordinate CLIPW into object coordinates
3260(OBJX,OBJYOBJZOBJW) using MODEL, PROJ, and VIEW. CLIPW can be other than
32611 as for vertices in `glFeedbackBuffer' when data type
3262`GLU_4D_COLOR_TEXTURE' is returned. This also handles the case where the
3263NEARVAL and FARVAL planes are different from the default, 0 and 1,
3264respectively. A return value of `GLU_TRUE' indicates success; a return
3265value of `GLU_FALSE' indicates failure.
3266
3267To compute the coordinates (OBJX,OBJYOBJZOBJW) , `gluUnProject4'
3268multiplies the normalized device coordinates by the inverse of MODEL *
3269PROJ as follows:
3270
3271((OBJX), (OBJY), (OBJZ),
3272(OBJW),)=INV\u2061(P\u2062M,)\u2062((2\u2061(WINX-VIEW\u2061[0,],),/VIEW\u2061[2,],-1),
3273(2\u2061(WINY-VIEW\u2061[1,],),/VIEW\u2061[3,],-1),
3274(2\u2061(WINZ-NEARVAL,),/(FARVAL-NEARVAL,),-1), (CLIPW),)
3275
3276INV denotes matrix inversion.
3277
3278`gluUnProject4' is equivalent to `gluUnProject' when CLIPW is 1, NEARVAL
3279is 0, and FARVAL is 1.")
8925f36f
AW		 3280
3281(define-gl-procedure
3282 gluUnProject
3283 "gluUnProject"
3284 (funcsynopsis
3285 (funcprototype
3286 (funcdef "GLint " (function "gluUnProject"))
3287 (paramdef "GLdouble " (parameter "winX"))
3288 (paramdef "GLdouble " (parameter "winY"))
3289 (paramdef "GLdouble " (parameter "winZ"))
3290 (paramdef
3291 "const GLdouble * "
3292 (parameter "model"))
3293 (paramdef "const GLdouble * " (parameter "proj"))
3294 (paramdef "const GLint * " (parameter "view"))
3295 (paramdef "GLdouble* " (parameter "objX"))
3296 (paramdef "GLdouble* " (parameter "objY"))
3297 (paramdef "GLdouble* " (parameter "objZ"))))
3c9b6116
AW		 3298 "Map window coordinates to object coordinates.
3299
3300WINX
3301 WINY
3302
3303 WINZ
3304
3305 Specify the window coordinates to be mapped.
3306
3307MODEL
3308 Specifies the modelview matrix (as from a `glGetDoublev' call).
3309
3310PROJ
3311 Specifies the projection matrix (as from a `glGetDoublev' call).
3312
3313VIEW
3314 Specifies the viewport (as from a `glGetIntegerv' call).
3315
3316OBJX
3317 OBJY
3318
3319 OBJZ
3320
3321 Returns the computed object coordinates.
3322
3323`gluUnProject' maps the specified window coordinates into object
3324coordinates using MODEL, PROJ, and VIEW. The result is stored in OBJX,
3325OBJY, and OBJZ. A return value of `GLU_TRUE' indicates success; a return
3326value of `GLU_FALSE' indicates failure.
3327
3328To compute the coordinates (OBJX,OBJYOBJZ) , `gluUnProject' multiplies
3329the normalized device coordinates by the inverse of MODEL * PROJ as
3330follows:
3331
3332((OBJX), (OBJY), (OBJZ),
3333(W),)=INV\u2061(P\u2062M,)\u2062((2\u2061(WINX-VIEW\u2061[0,],),/VIEW\u2061[2,],-1),
3334(2\u2061(WINY-VIEW\u2061[1,],),/VIEW\u2061[3,],-1), (2\u2061(WINZ,)-1), (1),) INV denotes
3335matrix inversion. W is an unused variable, included for consistent
3336matrix notation.")
8925f36f 3337
Unnamed repository; edit this file 'description' to name the repository.