HCoop / clinton / guile-figl.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
generate separate modules for gl, glu, glx; add info target
[clinton/guile-figl.git] / figl / low-level / glu.scm
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 ;;;
20 ;;; Copyright
21 ;;; =========
22 ;;;
23 ;;; Copyright (C) 1991-2006 Silicon Graphics, Inc. This document is licensed
24 ;;; under the SGI Free Software B License. For details, see
25 ;;; http://oss.sgi.com/projects/FreeB/ (http://oss.sgi.com/projects/FreeB/).
26 ;;;
27 ;;; Automatically generated; you probably don't want to edit this. To
28 ;;; update, run "make update" in the top-level build tree.
29 ;;;
30
31 (define-module
32 (figl low-level glu)
33 #:use-module
34 (figl low-level support)
35 #:export
36 (gluBeginCurve
37 gluBeginPolygon
38 gluBeginSurface
39 gluBeginTrim
40 gluBuild1DMipmapLevels
41 gluBuild1DMipmaps
42 gluBuild2DMipmapLevels
43 gluBuild2DMipmaps
44 gluBuild3DMipmapLevels
45 gluBuild3DMipmaps
46 gluCheckExtension
47 gluCylinder
48 gluDeleteNurbsRenderer
49 gluDeleteQuadric
50 gluDeleteTess
51 gluDisk
52 gluErrorString
53 gluGetNurbsProperty
54 gluGetString
55 gluGetTessProperty
56 gluLoadSamplingMatrices
57 gluLookAt
58 gluNewNurbsRenderer
59 gluNewQuadric
60 gluNewTess
61 gluNextContour
62 gluNurbsCallbackDataEXT
63 gluNurbsCallbackData
64 gluNurbsCallback
65 gluNurbsCurve
66 gluNurbsProperty
67 gluNurbsSurface
68 gluOrtho2D
69 gluPartialDisk
70 gluPerspective
71 gluPickMatrix
72 gluProject
73 gluPwlCurve
74 gluQuadricCallback
75 gluQuadricDrawStyle
76 gluQuadricNormals
77 gluQuadricOrientation
78 gluQuadricTexture
79 gluScaleImage
80 gluSphere
81 gluTessBeginContour
82 gluTessBeginPolygon
83 gluTessCallback
84 gluTessEndPolygon
85 gluTessNormal
86 gluTessProperty
87 gluTessVertex
88 gluUnProject4
89 gluUnProject))
90
91 (define-gl-procedure
92 gluBeginCurve
93 "gluBeginCurve"
94 (funcsynopsis
95 (funcprototype
96 (funcdef "void " (function "gluBeginCurve"))
97 (paramdef "GLUnurbs* " (parameter "nurb"))))
98 '(*fragment*
99 (heading "delimit a NURBS curve definition")
100 (heading "Parameters")
101 (table (% (formatter (asis)))
102 (entry (% (heading (var "nurb")))
103 (para "
104 Specifies the NURBS object (created with "
105 (code "gluNewNurbsRenderer")
106 "). ")))
107 (heading "Description")
108 (para "
109 Use "
110 (code "gluBeginCurve")
111 " to mark the beginning of a NURBS
112 curve definition.
113 After
114 calling "
115 (code "gluBeginCurve")
116 ", make one or more calls to "
117 (code "gluNurbsCurve")
118 " to define the attributes of the curve.
119 Exactly one of the calls to "
120 (code "gluNurbsCurve")
121 " must have
122 a curve type of "
123 (code "GLU_MAP1_VERTEX_3")
124 " or "
125 (code "GLU_MAP1_VERTEX_4")
126 ".
127 To mark the end of the NURBS curve definition, call "
128 (code "gluEndCurve")
129 ". ")
130 (para "
131 GL evaluators are used to render the NURBS curve as a series of line
132 segments.
133 Evaluator state is preserved during rendering
134 with "
135 (code "glPushAttrib")
136 "("
137 (code "GLU_EVAL_BIT")
138 ") and "
139 (code "glPopAttrib")
140 "().
141 See the "
142 (code "glPushAttrib")
143 " reference page for details on exactly what state
144 these calls preserve. ")))
145
146 (define-gl-procedure
147 gluBeginPolygon
148 "gluBeginPolygon"
149 (funcsynopsis
150 (funcprototype
151 (funcdef "void " (function "gluBeginPolygon"))
152 (paramdef "GLUtesselator* " (parameter "tess"))))
153 '(*fragment*
154 (heading "delimit a polygon description")
155 (heading "Parameters")
156 (table (% (formatter (asis)))
157 (entry (% (heading (var "tess")))
158 (para "
159 Specifies the tessellation object (created with "
160 (code "gluNewTess")
161 "). ")))
162 (heading "Description")
163 (para (code "gluBeginPolygon")
164 " and "
165 (code "gluEndPolygon")
166 " delimit the definition of a
167 nonconvex polygon.
168 To define such a polygon, first call "
169 (code "gluBeginPolygon")
170 ".
171 Then define the contours of the polygon
172 by calling "
173 (code "gluTessVertex")
174 " for each vertex
175 and "
176 (code "gluNextContour")
177 " to start each new contour.
178 Finally, call "
179 (code "gluEndPolygon")
180 "
181 to signal the end of the definition.
182 See the "
183 (code "gluTessVertex")
184 " and "
185 (code "gluNextContour")
186 " reference pages for more details. ")
187 (para "
188 Once "
189 (code "gluEndPolygon")
190 " is called, the polygon is tessellated, and the
191 resulting triangles are described through callbacks.
192 See "
193 (code "gluTessCallback")
194 " for descriptions of the callback functions. ")))
195
196 (define-gl-procedure
197 gluBeginSurface
198 "gluBeginSurface"
199 (funcsynopsis
200 (funcprototype
201 (funcdef "void " (function "gluBeginSurface"))
202 (paramdef "GLUnurbs* " (parameter "nurb"))))
203 '(*fragment*
204 (heading "delimit a NURBS surface definition")
205 (heading "Parameters")
206 (table (% (formatter (asis)))
207 (entry (% (heading (var "nurb")))
208 (para "
209 Specifies the NURBS object (created with "
210 (code "gluNewNurbsRenderer")
211 "). ")))
212 (heading "Description")
213 (para "
214 Use "
215 (code "gluBeginSurface")
216 " to mark the beginning of a NURBS
217 surface definition. After
218 calling "
219 (code "gluBeginSurface")
220 ", make one or more calls to "
221 (code "gluNurbsSurface")
222 " to define the attributes of the surface.
223 Exactly one of these calls to "
224 (code "gluNurbsSurface")
225 " must have a
226 surface type of "
227 (code "GLU_MAP2_VERTEX_3")
228 " or "
229 (code "GLU_MAP2_VERTEX_4")
230 ".
231 To mark the end of the NURBS surface definition, call "
232 (code "gluEndSurface")
233 ". ")
234 (para "
235 Trimming of NURBS surfaces is supported with "
236 (code "gluBeginTrim")
237 ", "
238 (code "gluPwlCurve")
239 ", "
240 (code "gluNurbsCurve")
241 ", and "
242 (code "gluEndTrim")
243 ". See the "
244 (code "gluBeginTrim")
245 " reference page for details. ")
246 (para "
247 GL evaluators are used to render the NURBS surface as a set of polygons.
248 Evaluator state is preserved during rendering
249 with "
250 (code "glPushAttrib")
251 "("
252 (code "GLU_EVAL_BIT")
253 ") and "
254 (code "glPopAttrib")
255 ".
256 See the "
257 (code "glPushAttrib")
258 " reference page for details on exactly what state
259 these calls preserve. ")))
260
261 (define-gl-procedure
262 gluBeginTrim
263 "gluBeginTrim"
264 (funcsynopsis
265 (funcprototype
266 (funcdef "void " (function "gluBeginTrim"))
267 (paramdef "GLUnurbs* " (parameter "nurb"))))
268 '(*fragment*
269 (heading
270 "delimit a NURBS trimming loop definition")
271 (heading "Parameters")
272 (table (% (formatter (asis)))
273 (entry (% (heading (var "nurb")))
274 (para "
275 Specifies the NURBS object (created with "
276 (code "gluNewNurbsRenderer")
277 "). ")))
278 (heading "Description")
279 (para "
280 Use "
281 (code "gluBeginTrim")
282 " to mark the beginning of a
283 trimming loop and "
284 (code "gluEndTrim")
285 " to mark the end
286 of a trimming loop. A trimming loop is
287 a set of oriented curve segments (forming a closed curve) that
288 define boundaries of a NURBS surface. You include these
289 trimming loops in the definition of a NURBS
290 surface, between calls to "
291 (code "gluBeginSurface")
292 " and "
293 (code "gluEndSurface")
294 ". ")
295 (para "
296 The definition for a NURBS surface can contain many
297 trimming loops. For example, if you wrote a definition
298 for a NURBS surface that resembled a rectangle with
299 a hole punched out, the definition would contain two
300 trimming loops. One loop would define the outer edge
301 of the rectangle; the other would define
302 the hole punched out of the rectangle. The definitions
303 of each of these trimming loops would be bracketed by a "
304 (code "gluBeginTrim")
305 "/"
306 (code "gluEndTrim")
307 " pair. ")
308 (para "
309 The definition of a single closed trimming loop can consist
310 of multiple curve segments, each described as a piecewise
311 linear curve (see "
312 (code "gluPwlCurve")
313 ") or as a single NURBS
314 curve (see "
315 (code "gluNurbsCurve")
316 "), or as a combination of
317 both in any order. The only library calls that can
318 appear in a trimming loop definition (between the calls
319 to "
320 (code "gluBeginTrim")
321 " and "
322 (code "gluEndTrim")
323 ") are "
324 (code "gluPwlCurve")
325 " and "
326 (code "gluNurbsCurve")
327 ". ")
328 (para "
329 The area of the NURBS surface that is displayed is the
330 region in the domain to the left of the trimming curve
331 as the curve parameter increases. Thus, the retained
332 region of the NURBS surface is inside a
333 counterclockwise trimming loop and outside a clockwise
334 trimming loop. For the rectangle mentioned earlier,
335 the trimming loop for the outer edge of the rectangle runs
336 counterclockwise, while the trimming loop for the punched-out hole
337 runs clockwise. ")
338 (para "
339 If you use more than one curve to define a single trimming
340 loop, the curve segments must form a closed loop (that is,
341 the endpoint of each curve must be the starting point of the
342 next curve, and the endpoint of the final curve must
343 be the starting point of the first curve). If the
344 endpoints of the curve are sufficiently close together
345 but not exactly coincident, they will be coerced to match.
346 If the endpoints are not sufficiently close, an error results
347 (see "
348 (code "gluNurbsCallback")
349 "). ")
350 (para "
351 If a trimming loop definition contains multiple curves,
352 the direction of the curves must be consistent (that is, the
353 inside must be to the left of all of the curves). Nested
354 trimming loops are legal as long as the curve orientations
355 alternate correctly.
356 If trimming curves are self-intersecting,
357 or intersect one another, an error results. ")
358 (para "
359 If no trimming information is given
360 for a NURBS surface, the entire surface is drawn. ")))
361
362 (define-gl-procedure
363 gluBuild1DMipmapLevels
364 "gluBuild1DMipmapLevels"
365 (funcsynopsis
366 (funcprototype
367 (funcdef
368 "GLint "
369 (function "gluBuild1DMipmapLevels"))
370 (paramdef "GLenum " (parameter "target"))
371 (paramdef "GLint " (parameter "internalFormat"))
372 (paramdef "GLsizei " (parameter "width"))
373 (paramdef "GLenum " (parameter "format"))
374 (paramdef "GLenum " (parameter "type"))
375 (paramdef "GLint " (parameter "level"))
376 (paramdef "GLint " (parameter "base"))
377 (paramdef "GLint " (parameter "max"))
378 (paramdef "const void * " (parameter "data"))))
379 '(*fragment*
380 (heading
381 "builds a subset of one-dimensional mipmap levels")
382 (heading "Parameters")
383 (table (% (formatter (asis)))
384 (entry (% (heading (var "target")))
385 (para "
386 Specifies the target texture. Must be "
387 (code "GLU_TEXTURE_1D")
388 ". "))
389 (entry (% (heading (var "internalFormat")))
390 (para "
391 Requests the internal storage format of the texture image. The most
392 current version of the SGI implementation of GLU does not check this
393 value for validity before passing it on to the underlying OpenGL
394 implementation. A value that is not accepted by the OpenGL
395 implementation will lead to an OpenGL error. The benefit of not
396 checking this value at the GLU level is that OpenGL extensions can add
397 new internal texture formats without requiring a revision of the GLU
398 implementation. Older implementations of GLU check this value and
399 raise a GLU error if it is not 1, 2, 3, or 4 or one of the following
400 symbolic constants: "
401 (code "GLU_ALPHA")
402 ", "
403 (code "GLU_ALPHA4")
404 ", "
405 (code "GLU_ALPHA8")
406 ", "
407 (code "GLU_ALPHA12")
408 ", "
409 (code "GLU_ALPHA16")
410 ", "
411 (code "GLU_LUMINANCE")
412 ", "
413 (code "GLU_LUMINANCE4")
414 ", "
415 (code "GLU_LUMINANCE8")
416 ", "
417 (code "GLU_LUMINANCE12")
418 ", "
419 (code "GLU_LUMINANCE16")
420 ", "
421 (code "GLU_LUMINANCE_ALPHA")
422 ", "
423 (code "GLU_LUMINANCE4_ALPHA4")
424 ", "
425 (code "GLU_LUMINANCE6_ALPHA2")
426 ", "
427 (code "GLU_LUMINANCE8_ALPHA8")
428 ", "
429 (code "GLU_LUMINANCE12_ALPHA4")
430 ", "
431 (code "GLU_LUMINANCE12_ALPHA12")
432 ", "
433 (code "GLU_LUMINANCE16_ALPHA16")
434 ", "
435 (code "GLU_INTENSITY")
436 ", "
437 (code "GLU_INTENSITY4")
438 ", "
439 (code "GLU_INTENSITY8")
440 ", "
441 (code "GLU_INTENSITY12")
442 ", "
443 (code "GLU_INTENSITY16")
444 ", "
445 (code "GLU_RGB")
446 ", "
447 (code "GLU_R3_G3_B2")
448 ", "
449 (code "GLU_RGB4")
450 ", "
451 (code "GLU_RGB5")
452 ", "
453 (code "GLU_RGB8")
454 ", "
455 (code "GLU_RGB10")
456 ", "
457 (code "GLU_RGB12")
458 ", "
459 (code "GLU_RGB16")
460 ", "
461 (code "GLU_RGBA")
462 ", "
463 (code "GLU_RGBA2")
464 ", "
465 (code "GLU_RGBA4")
466 ", "
467 (code "GLU_RGB5_A1")
468 ", "
469 (code "GLU_RGBA8")
470 ", "
471 (code "GLU_RGB10_A2")
472 ", "
473 (code "GLU_RGBA12")
474 ", or "
475 (code "GLU_RGBA16")
476 ". "))
477 (entry (% (heading (var "width")))
478 (para "
479 Specifies the width in pixels of the texture image.
480 This should be a power of 2. "))
481 (entry (% (heading (var "format")))
482 (para "
483 Specifies the format of the pixel data.
484 Must be one of: "
485 (code "GLU_COLOR_INDEX")
486 ", "
487 (code "GLU_DEPTH_COMPONENT")
488 ", "
489 (code "GLU_RED")
490 ", "
491 (code "GLU_GREEN")
492 ", "
493 (code "GLU_BLUE")
494 ", "
495 (code "GLU_ALPHA")
496 ", "
497 (code "GLU_RGB")
498 ", "
499 (code "GLU_RGBA")
500 ", "
501 (code "GLU_BGR")
502 ", "
503 (code "GLU_BGRA")
504 ", "
505 (code "GLU_LUMINANCE")
506 ", or "
507 (code "GLU_LUMINANCE_ALPHA")
508 ". "))
509 (entry (% (heading (var "type")))
510 (para "
511 Specifies the data type for "
512 (var "data")
513 ".
514 Must be one of: "
515 (code "GLU_UNSIGNED_BYTE")
516 ", "
517 (code "GLU_BYTE")
518 ", "
519 (code "GLU_BITMAP")
520 ", "
521 (code "GLU_UNSIGNED_SHORT")
522 ", "
523 (code "GLU_SHORT")
524 ", "
525 (code "GLU_UNSIGNED_INT")
526 ", "
527 (code "GLU_INT")
528 ", "
529 (code "GLU_FLOAT")
530 ", "
531 (code "GLU_UNSIGNED_BYTE_3_3_2")
532 ", "
533 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
534 ", "
535 (code "GLU_UNSIGNED_SHORT_5_6_5")
536 ", "
537 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
538 ", "
539 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
540 ", "
541 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
542 ", "
543 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
544 ", "
545 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
546 ", "
547 (code "GLU_UNSIGNED_INT_8_8_8_8")
548 ", "
549 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
550 ", "
551 (code "GLU_UNSIGNED_INT_10_10_10_2")
552 ", or "
553 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
554 ". "))
555 (entry (% (heading (var "level")))
556 (para "
557 Specifies the mipmap level of the image data. "))
558 (entry (% (heading (var "base")))
559 (para "
560 Specifies the minimum mipmap level to pass to "
561 (code "glTexImage1D")
562 ". "))
563 (entry (% (heading (var "max")))
564 (para "
565 Specifies the maximum mipmap level to pass to "
566 (code "glTexImage1D")
567 ". "))
568 (entry (% (heading (var "data")))
569 (para "
570 Specifies a pointer to the image data in memory. ")))
571 (heading "Description")
572 (para (code "gluBuild1DMipmapLevels")
573 " builds a subset of prefiltered one-dimensional texture maps of decreasing
574 resolutions called a mipmap. This is used for the antialiasing of
575 texture mapped primitives. ")
576 (para "
577 A return value of zero indicates success, otherwise a GLU error code is
578 returned (see "
579 (code "gluErrorString")
580 "). ")
581 (para "
582 A series of mipmap levels from "
583 (var "base")
584 " to "
585 (var "max")
586 " is built by decimating "
587 (var "data")
588 " in half
589 until size "
590 (math "1" "×" "1")
591 "
592 is reached. At each level, each texel in the
593 halved mipmap level is an average of the corresponding two texels in the larger
594 mipmap level. "
595 (code "glTexImage1D")
596 " is called to load these mipmap levels from "
597 (var "base")
598 "
599 to "
600 (var "max")
601 ". If "
602 (var "max")
603 " is larger than the highest mipmap level for the
604 texture of the specified size, then a GLU error code is returned (see "
605 (code "gluErrorString")
606 ") and nothing is loaded. ")
607 (para "
608 For example, if "
609 (var "level")
610 " is 2 and "
611 (var "width")
612 " is 16, the
613 following levels are possible: "
614 (math "16" "×" "1")
615 ", "
616 (math "8" "×" "1")
617 ", "
618 (math "4" "×" "1")
619 ", "
620 (math "2" "×" "1")
621 ", "
622 (math "1" "×" "1")
623 ".
624 These correspond
625 to levels 2 through 6 respectively.
626 If "
627 (var "base")
628 " is 3 and "
629 (var "max")
630 " is 5, then only mipmap levels "
631 (math "8" "×" "1")
632 ", "
633 (math "4" "×" "1")
634 "
635 and "
636 (math "2" "×" "1")
637 "
638 are
639 loaded. However, if "
640 (var "max")
641 " is 7, then an error is returned and nothing is
642 loaded since "
643 (var "max")
644 " is larger than the highest mipmap level which is, in
645 this case, 6. ")
646 (para "
647 The highest mipmap level can be derived from the formula "
648 (math (var "log")
649 "_"
650 "2"
651 "\u2061"
652 "("
653 (var "width")
654 "×"
655 "2"
656 "^"
657 (var "level")
658 ","
659 ")")
660 ". ")
661 (para "
662 See the "
663 (code "glTexImage1D")
664 " reference page for a description of the
665 acceptable values for "
666 (var "type")
667 " parameter. See the "
668 (code "glDrawPixels")
669 " reference page for a description of the acceptable values
670 for "
671 (var "level")
672 " parameter. ")
673 (heading "Errors")
674 (para (code "GLU_INVALID_VALUE")
675 " is returned if "
676 (var "level")
677 " > "
678 (var "base")
679 ", "
680 (var "base")
681 " < 0, "
682 (var "max")
683 " < "
684 (var "base")
685 " or "
686 (var "max")
687 " is > the highest mipmap level for "
688 (var "data")
689 ". ")
690 (para (code "GLU_INVALID_VALUE")
691 " is returned if "
692 (var "width")
693 " is < 1. ")
694 (para (code "GLU_INVALID_ENUM")
695 " is returned if "
696 (var "internalFormat")
697 ", "
698 (var "format")
699 ", or "
700 (var "type")
701 " are not
702 legal. ")
703 (para (code "GLU_INVALID_OPERATION")
704 " is returned if "
705 (var "type")
706 " is "
707 (code "GLU_UNSIGNED_BYTE_3_3_2")
708 " or "
709 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
710 "
711 and "
712 (var "format")
713 " is not "
714 (code "GLU_RGB")
715 ". ")
716 (para (code "GLU_INVALID_OPERATION")
717 " is returned if "
718 (var "type")
719 " is "
720 (code "GLU_UNSIGNED_SHORT_5_6_5")
721 " or "
722 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
723 "
724 and "
725 (var "format")
726 " is not "
727 (code "GLU_RGB")
728 ". ")
729 (para (code "GLU_INVALID_OPERATION")
730 " is returned if "
731 (var "type")
732 " is "
733 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
734 " or "
735 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
736 "
737 and "
738 (var "format")
739 " is neither "
740 (code "GLU_RGBA")
741 " nor "
742 (code "GLU_BGRA")
743 ". ")
744 (para (code "GLU_INVALID_OPERATION")
745 " is returned if "
746 (var "type")
747 " is "
748 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
749 " or "
750 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
751 "
752 and "
753 (var "format")
754 " is neither "
755 (code "GLU_RGBA")
756 " nor "
757 (code "GLU_BGRA")
758 ". ")
759 (para (code "GLU_INVALID_OPERATION")
760 " is returned if "
761 (var "type")
762 " is "
763 (code "GLU_UNSIGNED_INT_8_8_8_8")
764 " or "
765 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
766 "
767 and "
768 (var "format")
769 " is neither "
770 (code "GLU_RGBA")
771 " nor "
772 (code "GLU_BGRA")
773 ". ")
774 (para (code "GLU_INVALID_OPERATION")
775 " is returned if "
776 (var "type")
777 " is "
778 (code "GLU_UNSIGNED_INT_10_10_10_2")
779 " or "
780 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
781 "
782 and "
783 (var "format")
784 " is neither "
785 (code "GLU_RGBA")
786 " nor "
787 (code "GLU_BGRA")
788 ". ")))
789
790 (define-gl-procedure
791 gluBuild1DMipmaps
792 "gluBuild1DMipmaps"
793 (funcsynopsis
794 (funcprototype
795 (funcdef "GLint " (function "gluBuild1DMipmaps"))
796 (paramdef "GLenum " (parameter "target"))
797 (paramdef "GLint " (parameter "internalFormat"))
798 (paramdef "GLsizei " (parameter "width"))
799 (paramdef "GLenum " (parameter "format"))
800 (paramdef "GLenum " (parameter "type"))
801 (paramdef "const void * " (parameter "data"))))
802 '(*fragment*
803 (heading "builds a one-dimensional mipmap")
804 (heading "Parameters")
805 (table (% (formatter (asis)))
806 (entry (% (heading (var "target")))
807 (para "
808 Specifies the target texture. Must be "
809 (code "GLU_TEXTURE_1D")
810 ". "))
811 (entry (% (heading (var "internalFormat")))
812 (para "
813 Requests the internal storage format of the texture image. The most
814 current version of the SGI implementation of GLU does not check this
815 value for validity before passing it on to the underlying OpenGL
816 implementation. A value that is not accepted by the OpenGL
817 implementation will lead to an OpenGL error. The benefit of not
818 checking this value at the GLU level is that OpenGL extensions can add
819 new internal texture formats without requiring a revision of the GLU
820 implementation. Older implementations of GLU check this value and
821 raise a GLU error if it is not 1, 2, 3, or 4 or one of the following
822 symbolic constants: "
823 (code "GLU_ALPHA")
824 ", "
825 (code "GLU_ALPHA4")
826 ", "
827 (code "GLU_ALPHA8")
828 ", "
829 (code "GLU_ALPHA12")
830 ", "
831 (code "GLU_ALPHA16")
832 ", "
833 (code "GLU_LUMINANCE")
834 ", "
835 (code "GLU_LUMINANCE4")
836 ", "
837 (code "GLU_LUMINANCE8")
838 ", "
839 (code "GLU_LUMINANCE12")
840 ", "
841 (code "GLU_LUMINANCE16")
842 ", "
843 (code "GLU_LUMINANCE_ALPHA")
844 ", "
845 (code "GLU_LUMINANCE4_ALPHA4")
846 ", "
847 (code "GLU_LUMINANCE6_ALPHA2")
848 ", "
849 (code "GLU_LUMINANCE8_ALPHA8")
850 ", "
851 (code "GLU_LUMINANCE12_ALPHA4")
852 ", "
853 (code "GLU_LUMINANCE12_ALPHA12")
854 ", "
855 (code "GLU_LUMINANCE16_ALPHA16")
856 ", "
857 (code "GLU_INTENSITY")
858 ", "
859 (code "GLU_INTENSITY4")
860 ", "
861 (code "GLU_INTENSITY8")
862 ", "
863 (code "GLU_INTENSITY12")
864 ", "
865 (code "GLU_INTENSITY16")
866 ", "
867 (code "GLU_RGB")
868 ", "
869 (code "GLU_R3_G3_B2")
870 ", "
871 (code "GLU_RGB4")
872 ", "
873 (code "GLU_RGB5")
874 ", "
875 (code "GLU_RGB8")
876 ", "
877 (code "GLU_RGB10")
878 ", "
879 (code "GLU_RGB12")
880 ", "
881 (code "GLU_RGB16")
882 ", "
883 (code "GLU_RGBA")
884 ", "
885 (code "GLU_RGBA2")
886 ", "
887 (code "GLU_RGBA4")
888 ", "
889 (code "GLU_RGB5_A1")
890 ", "
891 (code "GLU_RGBA8")
892 ", "
893 (code "GLU_RGB10_A2")
894 ", "
895 (code "GLU_RGBA12")
896 ", or "
897 (code "GLU_RGBA16")
898 ". "))
899 (entry (% (heading (var "width")))
900 (para "
901 Specifies the width, in pixels, of the texture image. "))
902 (entry (% (heading (var "format")))
903 (para "
904 Specifies the format of the pixel data.
905 Must be one of "
906 (code "GLU_COLOR_INDEX")
907 ", "
908 (code "GLU_DEPTH_COMPONENT")
909 ", "
910 (code "GLU_RED")
911 ", "
912 (code "GLU_GREEN")
913 ", "
914 (code "GLU_BLUE")
915 ", "
916 (code "GLU_ALPHA")
917 ", "
918 (code "GLU_RGB")
919 ", "
920 (code "GLU_RGBA")
921 ", "
922 (code "GLU_BGR")
923 ", "
924 (code "GLU_BGRA")
925 ", "
926 (code "GLU_LUMINANCE")
927 ", or "
928 (code "GLU_LUMINANCE_ALPHA")
929 ". "))
930 (entry (% (heading (var "type")))
931 (para "
932 Specifies the data type for "
933 (var "data")
934 ".
935 Must be one of "
936 (code "GLU_UNSIGNED_BYTE")
937 ", "
938 (code "GLU_BYTE")
939 ", "
940 (code "GLU_BITMAP")
941 ", "
942 (code "GLU_UNSIGNED_SHORT")
943 ", "
944 (code "GLU_SHORT")
945 ", "
946 (code "GLU_UNSIGNED_INT")
947 ", "
948 (code "GLU_INT")
949 ", "
950 (code "GLU_FLOAT")
951 ", "
952 (code "GLU_UNSIGNED_BYTE_3_3_2")
953 ", "
954 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
955 ", "
956 (code "GLU_UNSIGNED_SHORT_5_6_5")
957 ", "
958 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
959 ", "
960 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
961 ", "
962 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
963 ", "
964 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
965 ", "
966 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
967 ", "
968 (code "GLU_UNSIGNED_INT_8_8_8_8")
969 ", "
970 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
971 ", "
972 (code "GLU_UNSIGNED_INT_10_10_10_2")
973 ", or "
974 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
975 ". "))
976 (entry (% (heading (var "data")))
977 (para "
978 Specifies a pointer to the image data in memory. ")))
979 (heading "Description")
980 (para (code "gluBuild1DMipmaps")
981 " builds a series of prefiltered one-dimensional texture maps of decreasing
982 resolutions called a mipmap. This is used for the antialiasing of
983 texture mapped primitives. ")
984 (para "
985 A return value of zero indicates success, otherwise a GLU error code is
986 returned (see "
987 (code "gluErrorString")
988 "). ")
989 (para "
990 Initially, the "
991 (var "width")
992 " of "
993 (var "data")
994 " is checked to see if it is
995 a power of 2. If not, a copy of "
996 (var "data")
997 " is scaled up or down to the
998 nearest power of 2. (If "
999 (var "width")
1000 " is exactly between powers of 2, then
1001 the copy of "
1002 (var "data")
1003 " will scale upwards.) This copy will be used for
1004 subsequent mipmapping operations described below.
1005 For example, if "
1006 (var "width")
1007 " is 57, then a copy of "
1008 (var "data")
1009 "
1010 will scale up to 64 before mipmapping
1011 takes place. ")
1012 (para "
1013 Then, proxy textures (see "
1014 (code "glTexImage1D")
1015 ") are used to determine if
1016 the implementation can fit the requested texture. If not, "
1017 (var "width")
1018 " is
1019 continually halved until it fits. ")
1020 (para "
1021 Next, a series of mipmap levels is built by decimating a copy of "
1022 (var "data")
1023 " in half
1024 until size "
1025 (math "1" "×" "1")
1026 "
1027 is reached. At each level, each texel in the
1028 halved mipmap level is an average of the corresponding two texels in the larger
1029 mipmap level. ")
1030 (para (code "glTexImage1D")
1031 " is called to load each of these mipmap levels.
1032 Level 0 is a copy of "
1033 (var "data")
1034 ".
1035 The highest level is "
1036 (math (var "log")
1037 "_"
1038 "2"
1039 ","
1040 "\u2061"
1041 "("
1042 (var "width")
1043 ","
1044 ")")
1045 ".
1046 For example, if "
1047 (var "width")
1048 " is 64 and the implementation can store a texture of
1049 this size, the following mipmap levels are
1050 built: "
1051 (math "64" "×" "1")
1052 ", "
1053 (math "32" "×" "1")
1054 ", "
1055 (math "16" "×" "1")
1056 ", "
1057 (math "8" "×" "1")
1058 ", "
1059 (math "4" "×" "1")
1060 ", "
1061 (math "2" "×" "1")
1062 ",
1063 and "
1064 (math "1" "×" "1")
1065 ".
1066 These correspond to
1067 levels 0 through 6, respectively. ")
1068 (para "
1069 See the "
1070 (code "glTexImage1D")
1071 " reference page for a description of the
1072 acceptable values for the "
1073 (var "type")
1074 " parameter. See the "
1075 (code "glDrawPixels")
1076 " reference page for a description of the acceptable values
1077 for the "
1078 (var "data")
1079 " parameter. ")
1080 (heading "Errors")
1081 (para (code "GLU_INVALID_VALUE")
1082 " is returned if "
1083 (var "width")
1084 " is < 1. ")
1085 (para (code "GLU_INVALID_ENUM")
1086 " is returned if "
1087 (var "format")
1088 " or "
1089 (var "type")
1090 " are not legal. ")
1091 (para (code "GLU_INVALID_OPERATION")
1092 " is returned if "
1093 (var "type")
1094 " is "
1095 (code "GLU_UNSIGNED_BYTE_3_3_2")
1096 " or "
1097 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
1098 "
1099 and "
1100 (var "format")
1101 " is not "
1102 (code "GLU_RGB")
1103 ". ")
1104 (para (code "GLU_INVALID_OPERATION")
1105 " is returned if "
1106 (var "type")
1107 " is "
1108 (code "GLU_UNSIGNED_SHORT_5_6_5")
1109 " or "
1110 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
1111 "
1112 and "
1113 (var "format")
1114 " is not "
1115 (code "GLU_RGB")
1116 ". ")
1117 (para (code "GLU_INVALID_OPERATION")
1118 " is returned if "
1119 (var "type")
1120 " is "
1121 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
1122 " or "
1123 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
1124 "
1125 and "
1126 (var "format")
1127 " is neither "
1128 (code "GLU_RGBA")
1129 " nor "
1130 (code "GLU_BGRA")
1131 ". ")
1132 (para (code "GLU_INVALID_OPERATION")
1133 " is returned if "
1134 (var "type")
1135 " is "
1136 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
1137 " or "
1138 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
1139 "
1140 and "
1141 (var "format")
1142 " is neither "
1143 (code "GLU_RGBA")
1144 " nor "
1145 (code "GLU_BGRA")
1146 ". ")
1147 (para (code "GLU_INVALID_OPERATION")
1148 " is returned if "
1149 (var "type")
1150 " is "
1151 (code "GLU_UNSIGNED_INT_8_8_8_8")
1152 " or "
1153 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
1154 "
1155 and "
1156 (var "format")
1157 " is neither "
1158 (code "GLU_RGBA")
1159 " nor "
1160 (code "GLU_BGRA")
1161 ". ")
1162 (para (code "GLU_INVALID_OPERATION")
1163 " is returned if "
1164 (var "type")
1165 " is "
1166 (code "GLU_UNSIGNED_INT_10_10_10_2")
1167 " or "
1168 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
1169 "
1170 and "
1171 (var "format")
1172 " is neither "
1173 (code "GLU_RGBA")
1174 " nor "
1175 (code "GLU_BGRA")
1176 ". ")))
1177
1178 (define-gl-procedure
1179 gluBuild2DMipmapLevels
1180 "gluBuild2DMipmapLevels"
1181 (funcsynopsis
1182 (funcprototype
1183 (funcdef
1184 "GLint "
1185 (function "gluBuild2DMipmapLevels"))
1186 (paramdef "GLenum " (parameter "target"))
1187 (paramdef "GLint " (parameter "internalFormat"))
1188 (paramdef "GLsizei " (parameter "width"))
1189 (paramdef "GLsizei " (parameter "height"))
1190 (paramdef "GLenum " (parameter "format"))
1191 (paramdef "GLenum " (parameter "type"))
1192 (paramdef "GLint " (parameter "level"))
1193 (paramdef "GLint " (parameter "base"))
1194 (paramdef "GLint " (parameter "max"))
1195 (paramdef "const void * " (parameter "data"))))
1196 '(*fragment*
1197 (heading
1198 "builds a subset of two-dimensional mipmap levels")
1199 (heading "Parameters")
1200 (table (% (formatter (asis)))
1201 (entry (% (heading (var "target")))
1202 (para "
1203 Specifies the target texture. Must be "
1204 (code "GLU_TEXTURE_2D")
1205 ". "))
1206 (entry (% (heading (var "internalFormat")))
1207 (para "
1208 Requests the internal storage format of the texture image. The most
1209 current version of the SGI implementation of GLU does not check this
1210 value for validity before passing it on to the underlying OpenGL
1211 implementation. A value that is not accepted by the OpenGL
1212 implementation will lead to an OpenGL error. The benefit of not
1213 checking this value at the GLU level is that OpenGL extensions can add
1214 new internal texture formats without requiring a revision of the GLU
1215 implementation. Older implementations of GLU check this value and
1216 raise a GLU error if it is not 1, 2, 3, or 4 or one of the following
1217 symbolic constants: "
1218 (code "GLU_ALPHA")
1219 ", "
1220 (code "GLU_ALPHA4")
1221 ", "
1222 (code "GLU_ALPHA8")
1223 ", "
1224 (code "GLU_ALPHA12")
1225 ", "
1226 (code "GLU_ALPHA16")
1227 ", "
1228 (code "GLU_LUMINANCE")
1229 ", "
1230 (code "GLU_LUMINANCE4")
1231 ", "
1232 (code "GLU_LUMINANCE8")
1233 ", "
1234 (code "GLU_LUMINANCE12")
1235 ", "
1236 (code "GLU_LUMINANCE16")
1237 ", "
1238 (code "GLU_LUMINANCE_ALPHA")
1239 ", "
1240 (code "GLU_LUMINANCE4_ALPHA4")
1241 ", "
1242 (code "GLU_LUMINANCE6_ALPHA2")
1243 ", "
1244 (code "GLU_LUMINANCE8_ALPHA8")
1245 ", "
1246 (code "GLU_LUMINANCE12_ALPHA4")
1247 ", "
1248 (code "GLU_LUMINANCE12_ALPHA12")
1249 ", "
1250 (code "GLU_LUMINANCE16_ALPHA16")
1251 ", "
1252 (code "GLU_INTENSITY")
1253 ", "
1254 (code "GLU_INTENSITY4")
1255 ", "
1256 (code "GLU_INTENSITY8")
1257 ", "
1258 (code "GLU_INTENSITY12")
1259 ", "
1260 (code "GLU_INTENSITY16")
1261 ", "
1262 (code "GLU_RGB")
1263 ", "
1264 (code "GLU_R3_G3_B2")
1265 ", "
1266 (code "GLU_RGB4")
1267 ", "
1268 (code "GLU_RGB5")
1269 ", "
1270 (code "GLU_RGB8")
1271 ", "
1272 (code "GLU_RGB10")
1273 ", "
1274 (code "GLU_RGB12")
1275 ", "
1276 (code "GLU_RGB16")
1277 ", "
1278 (code "GLU_RGBA")
1279 ", "
1280 (code "GLU_RGBA2")
1281 ", "
1282 (code "GLU_RGBA4")
1283 ", "
1284 (code "GLU_RGB5_A1")
1285 ", "
1286 (code "GLU_RGBA8")
1287 ", "
1288 (code "GLU_RGB10_A2")
1289 ", "
1290 (code "GLU_RGBA12")
1291 ", or "
1292 (code "GLU_RGBA16")
1293 ". "))
1294 (entry (% (heading (var "width")))
1295 (itemx (var "height"))
1296 (para "
1297 Specifies the width and height, respectively, in pixels of the texture image.
1298 These should be a power of 2. "))
1299 (entry (% (heading (var "format")))
1300 (para "
1301 Specifies the format of the pixel data.
1302 Must be one of "
1303 (code "GLU_COLOR_INDEX")
1304 ", "
1305 (code "GLU_DEPTH_COMPONENT")
1306 ", "
1307 (code "GLU_RED")
1308 ", "
1309 (code "GLU_GREEN")
1310 ", "
1311 (code "GLU_BLUE")
1312 ", "
1313 (code "GLU_ALPHA")
1314 ", "
1315 (code "GLU_RGB")
1316 ", "
1317 (code "GLU_RGBA")
1318 ", "
1319 (code "GLU_BGR")
1320 ", "
1321 (code "GLU_BGRA")
1322 ", "
1323 (code "GLU_LUMINANCE")
1324 ", or "
1325 (code "GLU_LUMINANCE_ALPHA")
1326 ". "))
1327 (entry (% (heading (var "type")))
1328 (para "
1329 Specifies the data type for "
1330 (var "data")
1331 ".
1332 Must be one of "
1333 (code "GLU_UNSIGNED_BYTE")
1334 ", "
1335 (code "GLU_BYTE")
1336 ", "
1337 (code "GLU_BITMAP")
1338 ", "
1339 (code "GLU_UNSIGNED_SHORT")
1340 ", "
1341 (code "GLU_SHORT")
1342 ", "
1343 (code "GLU_UNSIGNED_INT")
1344 ", "
1345 (code "GLU_INT")
1346 ", "
1347 (code "GLU_FLOAT")
1348 ", "
1349 (code "GLU_UNSIGNED_BYTE_3_3_2")
1350 ", "
1351 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
1352 ", "
1353 (code "GLU_UNSIGNED_SHORT_5_6_5")
1354 ", "
1355 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
1356 ", "
1357 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
1358 ", "
1359 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
1360 ", "
1361 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
1362 ", "
1363 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
1364 ", "
1365 (code "GLU_UNSIGNED_INT_8_8_8_8")
1366 ", "
1367 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
1368 ", "
1369 (code "GLU_UNSIGNED_INT_10_10_10_2")
1370 ", or "
1371 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
1372 ". "))
1373 (entry (% (heading (var "level")))
1374 (para "
1375 Specifies the mipmap level of the image data. "))
1376 (entry (% (heading (var "base")))
1377 (para "
1378 Specifies the minimum mipmap level to pass to "
1379 (code "glTexImage2D")
1380 ". "))
1381 (entry (% (heading (var "max")))
1382 (para "
1383 Specifies the maximum mipmap level to pass to "
1384 (code "glTexImage2D")
1385 ". "))
1386 (entry (% (heading (var "data")))
1387 (para "
1388 Specifies a pointer to the image data in memory. ")))
1389 (heading "Description")
1390 (para (code "gluBuild2DMipmapLevels")
1391 " builds a subset of prefiltered two-dimensional texture maps of decreasing
1392 resolutions called a mipmap. This is used for the antialiasing of
1393 texture mapped primitives. ")
1394 (para "
1395 A return value of zero indicates success, otherwise a GLU error code is
1396 returned (see "
1397 (code "gluErrorString")
1398 "). ")
1399 (para "
1400 A series of mipmap levels from "
1401 (var "base")
1402 " to "
1403 (var "max")
1404 " is built by decimating "
1405 (var "data")
1406 " in half along
1407 both dimensions until size "
1408 (math "1" "×" "1")
1409 "
1410 is reached. At each level, each texel in the
1411 halved mipmap level is an average of the corresponding four texels in the larger
1412 mipmap level. (In the case of rectangular images, the decimation will ultimately
1413 reach an "
1414 (math (var "N") "×" "1")
1415 "
1416 or "
1417 (math "1" "×" (var "N"))
1418 "
1419 configuration. Here, two texels are
1420 averaged instead.) "
1421 (code "glTexImage2D")
1422 " is called to load these mipmap levels from "
1423 (var "base")
1424 "
1425 to "
1426 (var "max")
1427 ". If "
1428 (var "max")
1429 " is larger than the highest mipmap level for the
1430 texture of the specified size, then a GLU error code is returned (see "
1431 (code "gluErrorString")
1432 ") and nothing is loaded. ")
1433 (para "
1434 For example, if "
1435 (var "level")
1436 " is 2 and "
1437 (var "width")
1438 " is 16 and "
1439 (var "height")
1440 " is 8, the
1441 following levels are possible: "
1442 (math "16" "×" "8")
1443 ", "
1444 (math "8" "×" "4")
1445 ", "
1446 (math "4" "×" "2")
1447 ", "
1448 (math "2" "×" "1")
1449 ", "
1450 (math "1" "×" "1")
1451 ".
1452 These correspond to levels 2 through 6
1453 respectively. If "
1454 (var "base")
1455 " is 3 and "
1456 (var "max")
1457 " is 5, then only mipmap levels "
1458 (math "8" "×" "4")
1459 ", "
1460 (math "4" "×" "2")
1461 ",
1462 and "
1463 (math "2" "×" "1")
1464 "
1465 are loaded. However, if "
1466 (var "max")
1467 "
1468 is 7, then an error is returned and nothing is loaded since "
1469 (var "max")
1470 " is
1471 larger than the highest mipmap level which is, in this case, 6. ")
1472 (para "
1473 The highest mipmap level can be derived from the formula "
1474 (math (var "log")
1475 "_"
1476 "2"
1477 "\u2061"
1478 "("
1479 (var "max")
1480 "\u2061"
1481 "("
1482 (var "width")
1483 ","
1484 (var "height")
1485 ")"
1486 "×"
1487 "2"
1488 "^"
1489 (var "level")
1490 ","
1491 ")")
1492 ". ")
1493 (para "
1494 See the "
1495 (code "glTexImage1D")
1496 " reference page for a description of the
1497 acceptable values for "
1498 (var "format")
1499 " parameter. See the "
1500 (code "glDrawPixels")
1501 " reference page for a description of the acceptable values
1502 for "
1503 (var "type")
1504 " parameter. ")
1505 (heading "Errors")
1506 (para (code "GLU_INVALID_VALUE")
1507 " is returned if "
1508 (var "level")
1509 " > "
1510 (var "base")
1511 ", "
1512 (var "base")
1513 " < 0, "
1514 (var "max")
1515 " < "
1516 (var "base")
1517 ", or "
1518 (var "max")
1519 " is > the highest mipmap level for "
1520 (var "data")
1521 ". ")
1522 (para (code "GLU_INVALID_VALUE")
1523 " is returned if "
1524 (var "width")
1525 " or "
1526 (var "height")
1527 " is < 1. ")
1528 (para (code "GLU_INVALID_ENUM")
1529 " is returned if "
1530 (var "internalFormat")
1531 ", "
1532 (var "format")
1533 ", or "
1534 (var "type")
1535 " is not
1536 legal. ")
1537 (para (code "GLU_INVALID_OPERATION")
1538 " is returned if "
1539 (var "type")
1540 " is "
1541 (code "GLU_UNSIGNED_BYTE_3_3_2")
1542 " or "
1543 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
1544 "
1545 and "
1546 (var "format")
1547 " is not "
1548 (code "GLU_RGB")
1549 ". ")
1550 (para (code "GLU_INVALID_OPERATION")
1551 " is returned if "
1552 (var "type")
1553 " is "
1554 (code "GLU_UNSIGNED_SHORT_5_6_5")
1555 " or "
1556 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
1557 "
1558 and "
1559 (var "format")
1560 " is not "
1561 (code "GLU_RGB")
1562 ". ")
1563 (para (code "GLU_INVALID_OPERATION")
1564 " is returned if "
1565 (var "type")
1566 " is "
1567 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
1568 " or "
1569 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
1570 "
1571 and "
1572 (var "format")
1573 " is neither "
1574 (code "GLU_RGBA")
1575 " nor "
1576 (code "GLU_BGRA")
1577 ". ")
1578 (para (code "GLU_INVALID_OPERATION")
1579 " is returned if "
1580 (var "type")
1581 " is "
1582 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
1583 " or "
1584 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
1585 "
1586 and "
1587 (var "format")
1588 " is neither "
1589 (code "GLU_RGBA")
1590 " nor "
1591 (code "GLU_BGRA")
1592 ". ")
1593 (para (code "GLU_INVALID_OPERATION")
1594 " is returned if "
1595 (var "type")
1596 " is "
1597 (code "GLU_UNSIGNED_INT_8_8_8_8")
1598 " or "
1599 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
1600 "
1601 and "
1602 (var "format")
1603 " is neither "
1604 (code "GLU_RGBA")
1605 " nor "
1606 (code "GLU_BGRA")
1607 ". ")
1608 (para (code "GLU_INVALID_OPERATION")
1609 " is returned if "
1610 (var "type")
1611 " is "
1612 (code "GLU_UNSIGNED_INT_10_10_10_2")
1613 " or "
1614 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
1615 "
1616 and "
1617 (var "format")
1618 " is neither "
1619 (code "GLU_RGBA")
1620 " nor "
1621 (code "GLU_BGRA")
1622 ". ")))
1623
1624 (define-gl-procedure
1625 gluBuild2DMipmaps
1626 "gluBuild2DMipmaps"
1627 (funcsynopsis
1628 (funcprototype
1629 (funcdef "GLint " (function "gluBuild2DMipmaps"))
1630 (paramdef "GLenum " (parameter "target"))
1631 (paramdef "GLint " (parameter "internalFormat"))
1632 (paramdef "GLsizei " (parameter "width"))
1633 (paramdef "GLsizei " (parameter "height"))
1634 (paramdef "GLenum " (parameter "format"))
1635 (paramdef "GLenum " (parameter "type"))
1636 (paramdef "const void * " (parameter "data"))))
1637 '(*fragment*
1638 (heading "builds a two-dimensional mipmap")
1639 (heading "Parameters")
1640 (table (% (formatter (asis)))
1641 (entry (% (heading (var "target")))
1642 (para "
1643 Specifies the target texture. Must be "
1644 (code "GLU_TEXTURE_2D")
1645 ". "))
1646 (entry (% (heading (var "internalFormat")))
1647 (para "
1648 Requests the internal storage format of the texture image. The most
1649 current version of the SGI implementation of GLU does not check this
1650 value for validity before passing it on to the underlying OpenGL
1651 implementation. A value that is not accepted by the OpenGL
1652 implementation will lead to an OpenGL error. The benefit of not
1653 checking this value at the GLU level is that OpenGL extensions can add
1654 new internal texture formats without requiring a revision of the GLU
1655 implementation. Older implementations of GLU check this value and
1656 raise a GLU error if it is not 1, 2, 3, or 4 or one of the following
1657 symbolic constants: "
1658 (code "GLU_ALPHA")
1659 ", "
1660 (code "GLU_ALPHA4")
1661 ", "
1662 (code "GLU_ALPHA8")
1663 ", "
1664 (code "GLU_ALPHA12")
1665 ", "
1666 (code "GLU_ALPHA16")
1667 ", "
1668 (code "GLU_LUMINANCE")
1669 ", "
1670 (code "GLU_LUMINANCE4")
1671 ", "
1672 (code "GLU_LUMINANCE8")
1673 ", "
1674 (code "GLU_LUMINANCE12")
1675 ", "
1676 (code "GLU_LUMINANCE16")
1677 ", "
1678 (code "GLU_LUMINANCE_ALPHA")
1679 ", "
1680 (code "GLU_LUMINANCE4_ALPHA4")
1681 ", "
1682 (code "GLU_LUMINANCE6_ALPHA2")
1683 ", "
1684 (code "GLU_LUMINANCE8_ALPHA8")
1685 ", "
1686 (code "GLU_LUMINANCE12_ALPHA4")
1687 ", "
1688 (code "GLU_LUMINANCE12_ALPHA12")
1689 ", "
1690 (code "GLU_LUMINANCE16_ALPHA16")
1691 ", "
1692 (code "GLU_INTENSITY")
1693 ", "
1694 (code "GLU_INTENSITY4")
1695 ", "
1696 (code "GLU_INTENSITY8")
1697 ", "
1698 (code "GLU_INTENSITY12")
1699 ", "
1700 (code "GLU_INTENSITY16")
1701 ", "
1702 (code "GLU_RGB")
1703 ", "
1704 (code "GLU_R3_G3_B2")
1705 ", "
1706 (code "GLU_RGB4")
1707 ", "
1708 (code "GLU_RGB5")
1709 ", "
1710 (code "GLU_RGB8")
1711 ", "
1712 (code "GLU_RGB10")
1713 ", "
1714 (code "GLU_RGB12")
1715 ", "
1716 (code "GLU_RGB16")
1717 ", "
1718 (code "GLU_RGBA")
1719 ", "
1720 (code "GLU_RGBA2")
1721 ", "
1722 (code "GLU_RGBA4")
1723 ", "
1724 (code "GLU_RGB5_A1")
1725 ", "
1726 (code "GLU_RGBA8")
1727 ", "
1728 (code "GLU_RGB10_A2")
1729 ", "
1730 (code "GLU_RGBA12")
1731 ", or "
1732 (code "GLU_RGBA16")
1733 ". "))
1734 (entry (% (heading (var "width")))
1735 (itemx (var "height"))
1736 (para "
1737 Specifies in pixels the width and height, respectively, of the texture image. "))
1738 (entry (% (heading (var "format")))
1739 (para "
1740 Specifies the format of the pixel data.
1741 Must be one of "
1742 (code "GLU_COLOR_INDEX")
1743 ", "
1744 (code "GLU_DEPTH_COMPONENT")
1745 ", "
1746 (code "GLU_RED")
1747 ", "
1748 (code "GLU_GREEN")
1749 ", "
1750 (code "GLU_BLUE")
1751 ", "
1752 (code "GLU_ALPHA")
1753 ", "
1754 (code "GLU_RGB")
1755 ", "
1756 (code "GLU_RGBA")
1757 ", "
1758 (code "GLU_BGR")
1759 ", "
1760 (code "GLU_BGRA")
1761 ", "
1762 (code "GLU_LUMINANCE")
1763 ", or "
1764 (code "GLU_LUMINANCE_ALPHA")
1765 ". "))
1766 (entry (% (heading (var "type")))
1767 (para "
1768 Specifies the data type for "
1769 (var "data")
1770 ".
1771 Must be one of "
1772 (code "GLU_UNSIGNED_BYTE")
1773 ", "
1774 (code "GLU_BYTE")
1775 ", "
1776 (code "GLU_BITMAP")
1777 ", "
1778 (code "GLU_UNSIGNED_SHORT")
1779 ", "
1780 (code "GLU_SHORT")
1781 ", "
1782 (code "GLU_UNSIGNED_INT")
1783 ", "
1784 (code "GLU_INT")
1785 ", "
1786 (code "GLU_FLOAT")
1787 ", "
1788 (code "GLU_UNSIGNED_BYTE_3_3_2")
1789 ", "
1790 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
1791 ", "
1792 (code "GLU_UNSIGNED_SHORT_5_6_5")
1793 ", "
1794 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
1795 ", "
1796 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
1797 ", "
1798 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
1799 ", "
1800 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
1801 ", "
1802 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
1803 ", "
1804 (code "GLU_UNSIGNED_INT_8_8_8_8")
1805 ", "
1806 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
1807 ", "
1808 (code "GLU_UNSIGNED_INT_10_10_10_2")
1809 ", or "
1810 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
1811 ". "))
1812 (entry (% (heading (var "data")))
1813 (para "
1814 Specifies a pointer to the image data in memory. ")))
1815 (heading "Description")
1816 (para (code "gluBuild2DMipmaps")
1817 " builds a series of prefiltered two-dimensional texture maps of decreasing
1818 resolutions called a mipmap. This is used for the antialiasing of
1819 texture-mapped primitives. ")
1820 (para "
1821 A return value of zero indicates success, otherwise a GLU error code is
1822 returned (see "
1823 (code "gluErrorString")
1824 "). ")
1825 (para "
1826 Initially, the "
1827 (var "width")
1828 " and "
1829 (var "height")
1830 " of "
1831 (var "data")
1832 " are checked to see if they
1833 are a power of 2. If not, a copy of "
1834 (var "data")
1835 " (not "
1836 (var "data")
1837 "), is scaled up
1838 or down to the nearest power of 2. This copy will be used for subsequent
1839 mipmapping operations described below. (If "
1840 (var "width")
1841 " or "
1842 (var "height")
1843 " is exactly
1844 between powers of 2, then the copy of "
1845 (var "data")
1846 " will scale upwards.) For
1847 example, if "
1848 (var "width")
1849 " is 57 and "
1850 (var "height")
1851 " is 23, then a copy of "
1852 (var "data")
1853 " will
1854 scale up to 64 in "
1855 (var "width")
1856 " and down to 16 in depth, before mipmapping takes
1857 place. ")
1858 (para "
1859 Then, proxy textures (see "
1860 (code "glTexImage2D")
1861 ") are used to determine if
1862 the implementation can fit the requested texture. If not, both dimensions
1863 are continually halved until it fits. (If the OpenGL version is \\(<= 1.0,
1864 both maximum texture dimensions are clamped to the value returned
1865 by "
1866 (code "glGetIntegerv")
1867 " with the argument "
1868 (code "GLU_MAX_TEXTURE_SIZE")
1869 ".) ")
1870 (para "
1871 Next, a series of mipmap levels is built by decimating a copy of "
1872 (var "data")
1873 "
1874 in half along both dimensions until size "
1875 (math "1" "×" "1")
1876 "
1877 is reached. At
1878 each level,
1879 each texel in the halved mipmap level is an average of the corresponding
1880 four texels in the larger mipmap level. (In the case of rectangular
1881 images, the decimation will ultimately reach an "
1882 (math (var "N") "×" "1")
1883 "
1884 or "
1885 (math "1" "×" (var "N"))
1886 "
1887 configuration. Here, two texels are averaged instead.) ")
1888 (para (code "glTexImage2D")
1889 " is called to load each of these mipmap levels.
1890 Level 0 is a copy of "
1891 (var "data")
1892 ". The highest level is "
1893 (math (var "log")
1894 "_"
1895 "2"
1896 ","
1897 "\u2061"
1898 "("
1899 (var "max")
1900 "\u2061"
1901 "("
1902 (var "width")
1903 ","
1904 (var "height")
1905 ")"
1906 ","
1907 ")")
1908 ".
1909 For example,
1910 if "
1911 (var "width")
1912 " is 64 and "
1913 (var "height")
1914 " is 16
1915 and the implementation can store a texture of this size, the following
1916 mipmap levels are built: "
1917 (math "64" "×" "16")
1918 ", "
1919 (math "32" "×" "8")
1920 ", "
1921 (math "16" "×" "4")
1922 ", "
1923 (math "8" "×" "2")
1924 ", "
1925 (math "4" "×" "1")
1926 ", "
1927 (math "2" "×" "1")
1928 ",
1929 and "
1930 (math "1" "×" "1")
1931 "
1932 These
1933 correspond to levels 0 through 6, respectively. ")
1934 (para "
1935 See the "
1936 (code "glTexImage1D")
1937 " reference page for a description of the
1938 acceptable values for "
1939 (var "format")
1940 " parameter. See the "
1941 (code "glDrawPixels")
1942 " reference page for a description of the acceptable values
1943 for "
1944 (var "type")
1945 " parameter. ")
1946 (heading "Errors")
1947 (para (code "GLU_INVALID_VALUE")
1948 " is returned if "
1949 (var "width")
1950 " or "
1951 (var "height")
1952 " is < 1. ")
1953 (para (code "GLU_INVALID_ENUM")
1954 " is returned if "
1955 (var "internalFormat")
1956 ", "
1957 (var "format")
1958 ", or "
1959 (var "type")
1960 " is not
1961 legal. ")
1962 (para (code "GLU_INVALID_OPERATION")
1963 " is returned if "
1964 (var "type")
1965 " is "
1966 (code "GLU_UNSIGNED_BYTE_3_3_2")
1967 " or "
1968 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
1969 "
1970 and "
1971 (var "format")
1972 " is not "
1973 (code "GLU_RGB")
1974 ". ")
1975 (para (code "GLU_INVALID_OPERATION")
1976 " is returned if "
1977 (var "type")
1978 " is "
1979 (code "GLU_UNSIGNED_SHORT_5_6_5")
1980 " or "
1981 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
1982 "
1983 and "
1984 (var "format")
1985 " is not "
1986 (code "GLU_RGB")
1987 ". ")
1988 (para (code "GLU_INVALID_OPERATION")
1989 " is returned if "
1990 (var "type")
1991 " is "
1992 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
1993 " or "
1994 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
1995 "
1996 and "
1997 (var "format")
1998 " is neither "
1999 (code "GLU_RGBA")
2000 " nor "
2001 (code "GLU_BGRA")
2002 ". ")
2003 (para (code "GLU_INVALID_OPERATION")
2004 " is returned if "
2005 (var "type")
2006 " is "
2007 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
2008 " or "
2009 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
2010 "
2011 and "
2012 (var "format")
2013 " is neither "
2014 (code "GLU_RGBA")
2015 " nor "
2016 (code "GLU_BGRA")
2017 ". ")
2018 (para (code "GLU_INVALID_OPERATION")
2019 " is returned if "
2020 (var "type")
2021 " is "
2022 (code "GLU_UNSIGNED_INT_8_8_8_8")
2023 " or "
2024 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
2025 "
2026 and "
2027 (var "format")
2028 " is neither "
2029 (code "GLU_RGBA")
2030 " nor "
2031 (code "GLU_BGRA")
2032 ". ")
2033 (para (code "GLU_INVALID_OPERATION")
2034 " is returned if "
2035 (var "type")
2036 " is "
2037 (code "GLU_UNSIGNED_INT_10_10_10_2")
2038 " or "
2039 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
2040 "
2041 and "
2042 (var "format")
2043 " is neither "
2044 (code "GLU_RGBA")
2045 " nor "
2046 (code "GLU_BGRA")
2047 ". ")))
2048
2049 (define-gl-procedure
2050 gluBuild3DMipmapLevels
2051 "gluBuild3DMipmapLevels"
2052 (funcsynopsis
2053 (funcprototype
2054 (funcdef
2055 "GLint "
2056 (function "gluBuild3DMipmapLevels"))
2057 (paramdef "GLenum " (parameter "target"))
2058 (paramdef "GLint " (parameter "internalFormat"))
2059 (paramdef "GLsizei " (parameter "width"))
2060 (paramdef "GLsizei " (parameter "height"))
2061 (paramdef "GLsizei " (parameter "depth"))
2062 (paramdef "GLenum " (parameter "format"))
2063 (paramdef "GLenum " (parameter "type"))
2064 (paramdef "GLint " (parameter "level"))
2065 (paramdef "GLint " (parameter "base"))
2066 (paramdef "GLint " (parameter "max"))
2067 (paramdef "const void * " (parameter "data"))))
2068 '(*fragment*
2069 (heading
2070 "builds a subset of three-dimensional mipmap levels")
2071 (heading "Parameters")
2072 (table (% (formatter (asis)))
2073 (entry (% (heading (var "target")))
2074 (para "
2075 Specifies the target texture. Must be "
2076 (code "GLU_TEXTURE_3D")
2077 ". "))
2078 (entry (% (heading (var "internalFormat")))
2079 (para "
2080 Requests the internal storage format of the texture image. The most
2081 current version of the SGI implementation of GLU does not check this
2082 value for validity before passing it on to the underlying OpenGL
2083 implementation. A value that is not accepted by the OpenGL
2084 implementation will lead to an OpenGL error. The benefit of not
2085 checking this value at the GLU level is that OpenGL extensions can add
2086 new internal texture formats without requiring a revision of the GLU
2087 implementation. Older implementations of GLU check this value and
2088 raise a GLU error if it is not 1, 2, 3, or 4 or one of the following
2089 symbolic constants: "
2090 (code "GLU_ALPHA")
2091 ", "
2092 (code "GLU_ALPHA4")
2093 ", "
2094 (code "GLU_ALPHA8")
2095 ", "
2096 (code "GLU_ALPHA12")
2097 ", "
2098 (code "GLU_ALPHA16")
2099 ", "
2100 (code "GLU_LUMINANCE")
2101 ", "
2102 (code "GLU_LUMINANCE4")
2103 ", "
2104 (code "GLU_LUMINANCE8")
2105 ", "
2106 (code "GLU_LUMINANCE12")
2107 ", "
2108 (code "GLU_LUMINANCE16")
2109 ", "
2110 (code "GLU_LUMINANCE_ALPHA")
2111 ", "
2112 (code "GLU_LUMINANCE4_ALPHA4")
2113 ", "
2114 (code "GLU_LUMINANCE6_ALPHA2")
2115 ", "
2116 (code "GLU_LUMINANCE8_ALPHA8")
2117 ", "
2118 (code "GLU_LUMINANCE12_ALPHA4")
2119 ", "
2120 (code "GLU_LUMINANCE12_ALPHA12")
2121 ", "
2122 (code "GLU_LUMINANCE16_ALPHA16")
2123 ", "
2124 (code "GLU_INTENSITY")
2125 ", "
2126 (code "GLU_INTENSITY4")
2127 ", "
2128 (code "GLU_INTENSITY8")
2129 ", "
2130 (code "GLU_INTENSITY12")
2131 ", "
2132 (code "GLU_INTENSITY16")
2133 ", "
2134 (code "GLU_RGB")
2135 ", "
2136 (code "GLU_R3_G3_B2")
2137 ", "
2138 (code "GLU_RGB4")
2139 ", "
2140 (code "GLU_RGB5")
2141 ", "
2142 (code "GLU_RGB8")
2143 ", "
2144 (code "GLU_RGB10")
2145 ", "
2146 (code "GLU_RGB12")
2147 ", "
2148 (code "GLU_RGB16")
2149 ", "
2150 (code "GLU_RGBA")
2151 ", "
2152 (code "GLU_RGBA2")
2153 ", "
2154 (code "GLU_RGBA4")
2155 ", "
2156 (code "GLU_RGB5_A1")
2157 ", "
2158 (code "GLU_RGBA8")
2159 ", "
2160 (code "GLU_RGB10_A2")
2161 ", "
2162 (code "GLU_RGBA12")
2163 ", or "
2164 (code "GLU_RGBA16")
2165 ". "))
2166 (entry (% (heading (var "width")))
2167 (itemx (var "height"))
2168 (itemx (var "depth"))
2169 (para "
2170 Specifies in pixels the width, height and depth respectively, of the texture
2171 image. These should be a power of 2. "))
2172 (entry (% (heading (var "format")))
2173 (para "
2174 Specifies the format of the pixel data.
2175 Must be one of "
2176 (code "GLU_COLOR_INDEX")
2177 ", "
2178 (code "GLU_DEPTH_COMPONENT")
2179 ", "
2180 (code "GLU_RED")
2181 ", "
2182 (code "GLU_GREEN")
2183 ", "
2184 (code "GLU_BLUE")
2185 ", "
2186 (code "GLU_ALPHA")
2187 ", "
2188 (code "GLU_RGB")
2189 ", "
2190 (code "GLU_RGBA")
2191 ", "
2192 (code "GLU_BGR")
2193 ", "
2194 (code "GLU_BGRA")
2195 ", "
2196 (code "GLU_LUMINANCE")
2197 ", or "
2198 (code "GLU_LUMINANCE_ALPHA")
2199 ". "))
2200 (entry (% (heading (var "type")))
2201 (para "
2202 Specifies the data type for "
2203 (var "data")
2204 ".
2205 Must be one of "
2206 (code "GLU_UNSIGNED_BYTE")
2207 ", "
2208 (code "GLU_BYTE")
2209 ", "
2210 (code "GLU_BITMAP")
2211 ", "
2212 (code "GLU_UNSIGNED_SHORT")
2213 ", "
2214 (code "GLU_SHORT")
2215 ", "
2216 (code "GLU_UNSIGNED_INT")
2217 ", "
2218 (code "GLU_INT")
2219 ", "
2220 (code "GLU_FLOAT")
2221 ", "
2222 (code "GLU_UNSIGNED_BYTE_3_3_2")
2223 ", "
2224 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
2225 ", "
2226 (code "GLU_UNSIGNED_SHORT_5_6_5")
2227 ", "
2228 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
2229 ", "
2230 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
2231 ", "
2232 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
2233 ", "
2234 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
2235 ", "
2236 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
2237 ", "
2238 (code "GLU_UNSIGNED_INT_8_8_8_8")
2239 ", "
2240 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
2241 ", "
2242 (code "GLU_UNSIGNED_INT_10_10_10_2")
2243 ", or "
2244 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
2245 ". "))
2246 (entry (% (heading (var "level")))
2247 (para "
2248 Specifies the mipmap level of the image data. "))
2249 (entry (% (heading (var "base")))
2250 (para "
2251 Specifies the minimum mipmap level to pass to "
2252 (code "glTexImage3D")
2253 ". "))
2254 (entry (% (heading (var "max")))
2255 (para "
2256 Specifies the maximum mipmap level to pass to "
2257 (code "glTexImage3D")
2258 ". "))
2259 (entry (% (heading (var "data")))
2260 (para "
2261 Specifies a pointer to the image data in memory. ")))
2262 (heading "Description")
2263 (para (code "gluBuild3DMipmapLevels")
2264 " builds a subset of prefiltered three-dimensional texture maps of
2265 decreasing resolutions called a mipmap. This is used for the antialiasing of
2266 texture mapped primitives. ")
2267 (para "
2268 A return value of zero indicates success, otherwise a GLU error code is
2269 returned (see "
2270 (code "gluErrorString")
2271 "). ")
2272 (para "
2273 A series of mipmap levels from "
2274 (var "base")
2275 " to "
2276 (var "max")
2277 " is built by
2278 decimating "
2279 (var "data")
2280 " in half along both dimensions until size "
2281 (math "1" "×" "1" "×" "1")
2282 "
2283 is reached. At each level, each texel in the halved mipmap
2284 level is an average of the corresponding eight texels in the larger
2285 mipmap level. (If exactly one of the dimensions is 1, four texels are
2286 averaged. If exactly two of the dimensions are 1, two texels are
2287 averaged.) "
2288 (code "glTexImage3D")
2289 " is called to load these mipmap levels
2290 from "
2291 (var "base")
2292 " to "
2293 (var "max")
2294 ". If "
2295 (var "max")
2296 " is larger than the highest mipmap
2297 level for the texture of the specified size, then a GLU error code is
2298 returned (see "
2299 (code "gluErrorString")
2300 ") and nothing is loaded. ")
2301 (para "
2302 For example, if "
2303 (var "level")
2304 " is 2 and "
2305 (var "width")
2306 " is 16, "
2307 (var "height")
2308 " is 8 and "
2309 (var "depth")
2310 "
2311 is 4, the following levels are possible: "
2312 (math "16" "×" "8" "×" "4")
2313 ", "
2314 (math "8" "×" "4" "×" "2")
2315 ", "
2316 (math "4" "×" "2" "×" "1")
2317 ", "
2318 (math "2" "×" "1" "×" "1")
2319 ", "
2320 (math "1" "×" "1" "×" "1")
2321 ".
2322 These correspond to levels 2 through 6 respectively. If "
2323 (var "base")
2324 " is
2325 3 and "
2326 (var "max")
2327 " is 5, then only mipmap levels "
2328 (math "8" "×" "4" "×" "2")
2329 ", "
2330 (math "4" "×" "2" "×" "1")
2331 ",
2332 and "
2333 (math "2" "×" "1" "×" "1")
2334 "
2335 are loaded. However, if "
2336 (var "max")
2337 " is 7, then an error is returned and nothing is loaded, since "
2338 (var "max")
2339 " is larger than the highest mipmap level which is, in this case,
2340 6. ")
2341 (para "
2342 The highest mipmap level can be derived from the formula "
2343 (math (var "log")
2344 "_"
2345 "2"
2346 "\u2061"
2347 "("
2348 (var "max")
2349 "\u2061"
2350 "("
2351 (var "width")
2352 ","
2353 (var "height")
2354 (var "depth")
2355 ")"
2356 "×"
2357 "2"
2358 "^"
2359 (var "level")
2360 ","
2361 ")")
2362 ". ")
2363 (para "
2364 See the "
2365 (code "glTexImage1D")
2366 " reference page for a description of the
2367 acceptable values for "
2368 (var "format")
2369 " parameter. See the "
2370 (code "glDrawPixels")
2371 " reference page for a description of the acceptable values
2372 for "
2373 (var "type")
2374 " parameter. ")
2375 (heading "Errors")
2376 (para (code "GLU_INVALID_VALUE")
2377 " is returned if "
2378 (var "level")
2379 " > "
2380 (var "base")
2381 ", "
2382 (var "base")
2383 " < 0, "
2384 (var "max")
2385 " < "
2386 (var "base")
2387 ", or "
2388 (var "max")
2389 " is > the highest mipmap level for "
2390 (var "data")
2391 ". ")
2392 (para (code "GLU_INVALID_VALUE")
2393 " is returned if "
2394 (var "width")
2395 ", "
2396 (var "height")
2397 ", or "
2398 (var "depth")
2399 " is < 1. ")
2400 (para (code "GLU_INVALID_ENUM")
2401 " is returned if "
2402 (var "internalFormat")
2403 ", "
2404 (var "format")
2405 ", or "
2406 (var "type")
2407 " is not
2408 legal. ")
2409 (para (code "GLU_INVALID_OPERATION")
2410 " is returned if "
2411 (var "type")
2412 " is "
2413 (code "GLU_UNSIGNED_BYTE_3_3_2")
2414 " or "
2415 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
2416 "
2417 and "
2418 (var "format")
2419 " is not "
2420 (code "GLU_RGB")
2421 ". ")
2422 (para (code "GLU_INVALID_OPERATION")
2423 " is returned if "
2424 (var "type")
2425 " is "
2426 (code "GLU_UNSIGNED_SHORT_5_6_5")
2427 " or "
2428 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
2429 "
2430 and "
2431 (var "format")
2432 " is not "
2433 (code "GLU_RGB")
2434 ". ")
2435 (para (code "GLU_INVALID_OPERATION")
2436 " is returned if "
2437 (var "type")
2438 " is "
2439 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
2440 " or "
2441 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
2442 "
2443 and "
2444 (var "format")
2445 " is neither "
2446 (code "GLU_RGBA")
2447 " nor "
2448 (code "GLU_BGRA")
2449 ". ")
2450 (para (code "GLU_INVALID_OPERATION")
2451 " is returned if "
2452 (var "type")
2453 " is "
2454 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
2455 " or "
2456 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
2457 "
2458 and "
2459 (var "format")
2460 " is neither "
2461 (code "GLU_RGBA")
2462 " nor "
2463 (code "GLU_BGRA")
2464 ". ")
2465 (para (code "GLU_INVALID_OPERATION")
2466 " is returned if "
2467 (var "type")
2468 " is "
2469 (code "GLU_UNSIGNED_INT_8_8_8_8")
2470 " or "
2471 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
2472 "
2473 and "
2474 (var "format")
2475 " is neither "
2476 (code "GLU_RGBA")
2477 " nor "
2478 (code "GLU_BGRA")
2479 ". ")
2480 (para (code "GLU_INVALID_OPERATION")
2481 " is returned if "
2482 (var "type")
2483 " is "
2484 (code "GLU_UNSIGNED_INT_10_10_10_2")
2485 " or "
2486 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
2487 "
2488 and "
2489 (var "format")
2490 " is neither "
2491 (code "GLU_RGBA")
2492 " nor "
2493 (code "GLU_BGRA")
2494 ". ")))
2495
2496 (define-gl-procedure
2497 gluBuild3DMipmaps
2498 "gluBuild3DMipmaps"
2499 (funcsynopsis
2500 (funcprototype
2501 (funcdef "GLint " (function "gluBuild3DMipmaps"))
2502 (paramdef "GLenum " (parameter "target"))
2503 (paramdef "GLint " (parameter "internalFormat"))
2504 (paramdef "GLsizei " (parameter "width"))
2505 (paramdef "GLsizei " (parameter "height"))
2506 (paramdef "GLsizei " (parameter "depth"))
2507 (paramdef "GLenum " (parameter "format"))
2508 (paramdef "GLenum " (parameter "type"))
2509 (paramdef "const void * " (parameter "data"))))
2510 '(*fragment*
2511 (heading "builds a three-dimensional mipmap")
2512 (heading "Parameters")
2513 (table (% (formatter (asis)))
2514 (entry (% (heading (var "target")))
2515 (para "
2516 Specifies the target texture. Must be "
2517 (code "GLU_TEXTURE_3D")
2518 ". "))
2519 (entry (% (heading (var "internalFormat")))
2520 (para "
2521 Requests the internal storage format of the texture image. The most
2522 current version of the SGI implementation of GLU does not check this
2523 value for validity before passing it on to the underlying OpenGL
2524 implementation. A value that is not accepted by the OpenGL
2525 implementation will lead to an OpenGL error. The benefit of not
2526 checking this value at the GLU level is that OpenGL extensions can add
2527 new internal texture formats without requiring a revision of the GLU
2528 implementation. Older implementations of GLU check this value and
2529 raise a GLU error if it is not 1, 2, 3, or 4 or one of the following
2530 symbolic constants: "
2531 (code "GLU_ALPHA")
2532 ", "
2533 (code "GLU_ALPHA4")
2534 ", "
2535 (code "GLU_ALPHA8")
2536 ", "
2537 (code "GLU_ALPHA12")
2538 ", "
2539 (code "GLU_ALPHA16")
2540 ", "
2541 (code "GLU_LUMINANCE")
2542 ", "
2543 (code "GLU_LUMINANCE4")
2544 ", "
2545 (code "GLU_LUMINANCE8")
2546 ", "
2547 (code "GLU_LUMINANCE12")
2548 ", "
2549 (code "GLU_LUMINANCE16")
2550 ", "
2551 (code "GLU_LUMINANCE_ALPHA")
2552 ", "
2553 (code "GLU_LUMINANCE4_ALPHA4")
2554 ", "
2555 (code "GLU_LUMINANCE6_ALPHA2")
2556 ", "
2557 (code "GLU_LUMINANCE8_ALPHA8")
2558 ", "
2559 (code "GLU_LUMINANCE12_ALPHA4")
2560 ", "
2561 (code "GLU_LUMINANCE12_ALPHA12")
2562 ", "
2563 (code "GLU_LUMINANCE16_ALPHA16")
2564 ", "
2565 (code "GLU_INTENSITY")
2566 ", "
2567 (code "GLU_INTENSITY4")
2568 ", "
2569 (code "GLU_INTENSITY8")
2570 ", "
2571 (code "GLU_INTENSITY12")
2572 ", "
2573 (code "GLU_INTENSITY16")
2574 ", "
2575 (code "GLU_RGB")
2576 ", "
2577 (code "GLU_R3_G3_B2")
2578 ", "
2579 (code "GLU_RGB4")
2580 ", "
2581 (code "GLU_RGB5")
2582 ", "
2583 (code "GLU_RGB8")
2584 ", "
2585 (code "GLU_RGB10")
2586 ", "
2587 (code "GLU_RGB12")
2588 ", "
2589 (code "GLU_RGB16")
2590 ", "
2591 (code "GLU_RGBA")
2592 ", "
2593 (code "GLU_RGBA2")
2594 ", "
2595 (code "GLU_RGBA4")
2596 ", "
2597 (code "GLU_RGB5_A1")
2598 ", "
2599 (code "GLU_RGBA8")
2600 ", "
2601 (code "GLU_RGB10_A2")
2602 ", "
2603 (code "GLU_RGBA12")
2604 ", or "
2605 (code "GLU_RGBA16")
2606 ". "))
2607 (entry (% (heading (var "width")))
2608 (itemx (var "height"))
2609 (itemx (var "depth"))
2610 (para "
2611 Specifies in pixels the width, height and depth respectively, in pixels
2612 of the texture image. "))
2613 (entry (% (heading (var "format")))
2614 (para "
2615 Specifies the format of the pixel data.
2616 Must be one of "
2617 (code "GLU_COLOR_INDEX")
2618 ", "
2619 (code "GLU_DEPTH_COMPONENT")
2620 ", "
2621 (code "GLU_RED")
2622 ", "
2623 (code "GLU_GREEN")
2624 ", "
2625 (code "GLU_BLUE")
2626 ", "
2627 (code "GLU_ALPHA")
2628 ", "
2629 (code "GLU_RGB")
2630 ", "
2631 (code "GLU_RGBA")
2632 ", "
2633 (code "GLU_BGR")
2634 ", "
2635 (code "GLU_BGRA")
2636 ", "
2637 (code "GLU_LUMINANCE")
2638 ", or "
2639 (code "GLU_LUMINANCE_ALPHA")
2640 ". "))
2641 (entry (% (heading (var "type")))
2642 (para "
2643 Specifies the data type for "
2644 (var "data")
2645 ".
2646 Must be one of: "
2647 (code "GLU_UNSIGNED_BYTE")
2648 ", "
2649 (code "GLU_BYTE")
2650 ", "
2651 (code "GLU_BITMAP")
2652 ", "
2653 (code "GLU_UNSIGNED_SHORT")
2654 ", "
2655 (code "GLU_SHORT")
2656 ", "
2657 (code "GLU_UNSIGNED_INT")
2658 ", "
2659 (code "GLU_INT")
2660 ", "
2661 (code "GLU_FLOAT")
2662 ", "
2663 (code "GLU_UNSIGNED_BYTE_3_3_2")
2664 ", "
2665 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
2666 ", "
2667 (code "GLU_UNSIGNED_SHORT_5_6_5")
2668 ", "
2669 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
2670 ", "
2671 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
2672 ", "
2673 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
2674 ", "
2675 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
2676 ", "
2677 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
2678 ", "
2679 (code "GLU_UNSIGNED_INT_8_8_8_8")
2680 ", "
2681 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
2682 ", "
2683 (code "GLU_UNSIGNED_INT_10_10_10_2")
2684 ", or "
2685 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
2686 ". "))
2687 (entry (% (heading (var "data")))
2688 (para "
2689 Specifies a pointer to the image data in memory. ")))
2690 (heading "Description")
2691 (para (code "gluBuild3DMipmaps")
2692 " builds a series of prefiltered three-dimensional texture maps of
2693 decreasing resolutions called a mipmap. This is used for the antialiasing of
2694 texture-mapped primitives. ")
2695 (para "
2696 A return value of zero indicates success, otherwise a GLU error code is
2697 returned (see "
2698 (code "gluErrorString")
2699 "). ")
2700 (para "
2701 Initially, the "
2702 (var "width")
2703 ", "
2704 (var "height")
2705 " and "
2706 (var "depth")
2707 " of "
2708 (var "data")
2709 " are checked to
2710 see if they are a power of 2. If not, a copy of "
2711 (var "data")
2712 " is made and
2713 scaled up or down to the nearest power of 2. (If "
2714 (var "width")
2715 ", "
2716 (var "height")
2717 ", or "
2718 (var "depth")
2719 " is exactly between powers of 2, then the copy of "
2720 (var "data")
2721 " will
2722 scale upwards.) This copy will be used for subsequent mipmapping
2723 operations described below. For example, if "
2724 (var "width")
2725 " is 57, "
2726 (var "height")
2727 " is
2728 23, and "
2729 (var "depth")
2730 " is 24, then a copy of "
2731 (var "data")
2732 " will scale up to 64 in
2733 width, down to 16 in height, and up to 32 in depth before mipmapping
2734 takes place. ")
2735 (para "
2736 Then, proxy textures (see "
2737 (code "glTexImage3D")
2738 ") are used to determine if
2739 the implementation can fit the requested texture. If not, all three dimensions
2740 are continually halved until it fits. ")
2741 (para "
2742 Next, a series of mipmap levels is built by decimating a copy of "
2743 (var "data")
2744 "
2745 in half along all three dimensions until size "
2746 (math "1" "×" "1" "×" "1")
2747 "
2748 is
2749 reached. At each level, each texel in the halved mipmap level is an
2750 average of the corresponding eight texels in the larger mipmap
2751 level. (If exactly one of the dimensions is 1, four texels are averaged.
2752 If exactly two of the dimensions are 1, two texels are averaged.) ")
2753 (para (code "glTexImage3D")
2754 " is called to load each of these mipmap levels.
2755 Level 0 is a copy of "
2756 (var "data")
2757 ". The highest level is "
2758 (math (var "log")
2759 "_"
2760 "2"
2761 ","
2762 "\u2061"
2763 "("
2764 (var "max")
2765 "\u2061"
2766 "("
2767 (var "width")
2768 ","
2769 (var "height")
2770 (var "depth")
2771 ")"
2772 ","
2773 ")")
2774 ".
2775 For example, if "
2776 (var "width")
2777 " is 64, "
2778 (var "height")
2779 " is
2780 16, and "
2781 (var "depth")
2782 " is 32, and the implementation can store a texture of this
2783 size, the following mipmap levels are built: "
2784 (math "64" "×" "16" "×" "32")
2785 ", "
2786 (math "32" "×" "8" "×" "16")
2787 ", "
2788 (math "16" "×" "4" "×" "8")
2789 ", "
2790 (math "8" "×" "2" "×" "4")
2791 ", "
2792 (math "4" "×" "1" "×" "2")
2793 ", "
2794 (math "2" "×" "1" "×" "1")
2795 ",
2796 and "
2797 (math "1" "×" "1" "×" "1")
2798 ".
2799 These correspond
2800 to levels 0 through 6, respectively. ")
2801 (para "
2802 See the "
2803 (code "glTexImage1D")
2804 " reference page for a description of the
2805 acceptable values for "
2806 (var "format")
2807 " parameter. See the "
2808 (code "glDrawPixels")
2809 " reference page for a description of the acceptable values
2810 for "
2811 (var "type")
2812 " parameter. ")
2813 (heading "Errors")
2814 (para (code "GLU_INVALID_VALUE")
2815 " is returned if "
2816 (var "width")
2817 ", "
2818 (var "height")
2819 ", or "
2820 (var "depth")
2821 " is < 1. ")
2822 (para (code "GLU_INVALID_ENUM")
2823 " is returned if "
2824 (var "internalFormat")
2825 ", "
2826 (var "format")
2827 ", or "
2828 (var "type")
2829 " is not
2830 legal. ")
2831 (para (code "GLU_INVALID_OPERATION")
2832 " is returned if "
2833 (var "type")
2834 " is "
2835 (code "GLU_UNSIGNED_BYTE_3_3_2")
2836 " or "
2837 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
2838 "
2839 and "
2840 (var "format")
2841 " is not "
2842 (code "GLU_RGB")
2843 ". ")
2844 (para (code "GLU_INVALID_OPERATION")
2845 " is returned if "
2846 (var "type")
2847 " is "
2848 (code "GLU_UNSIGNED_SHORT_5_6_5")
2849 " or "
2850 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
2851 "
2852 and "
2853 (var "format")
2854 " is not "
2855 (code "GLU_RGB")
2856 ". ")
2857 (para (code "GLU_INVALID_OPERATION")
2858 " is returned if "
2859 (var "type")
2860 " is "
2861 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
2862 " or "
2863 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
2864 "
2865 and "
2866 (var "format")
2867 " is neither "
2868 (code "GLU_RGBA")
2869 " nor "
2870 (code "GLU_BGRA")
2871 ". ")
2872 (para (code "GLU_INVALID_OPERATION")
2873 " is returned if "
2874 (var "type")
2875 " is "
2876 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
2877 " or "
2878 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
2879 "
2880 and "
2881 (var "format")
2882 " is neither "
2883 (code "GLU_RGBA")
2884 " nor "
2885 (code "GLU_BGRA")
2886 ". ")
2887 (para (code "GLU_INVALID_OPERATION")
2888 " is returned if "
2889 (var "type")
2890 " is "
2891 (code "GLU_UNSIGNED_INT_8_8_8_8")
2892 " or "
2893 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
2894 "
2895 and "
2896 (var "format")
2897 " is neither "
2898 (code "GLU_RGBA")
2899 " nor "
2900 (code "GLU_BGRA")
2901 ". ")
2902 (para (code "GLU_INVALID_OPERATION")
2903 " is returned if "
2904 (var "type")
2905 " is "
2906 (code "GLU_UNSIGNED_INT_10_10_10_2")
2907 " or "
2908 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
2909 "
2910 and "
2911 (var "format")
2912 " is neither "
2913 (code "GLU_RGBA")
2914 " nor "
2915 (code "GLU_BGRA")
2916 ". ")))
2917
2918 (define-gl-procedure
2919 gluCheckExtension
2920 "gluCheckExtension"
2921 (funcsynopsis
2922 (funcprototype
2923 (funcdef
2924 "GLboolean "
2925 (function "gluCheckExtension"))
2926 (paramdef
2927 "const GLubyte * "
2928 (parameter "extName"))
2929 (paramdef
2930 "const GLubyte * "
2931 (parameter "extString"))))
2932 '(*fragment*
2933 (heading
2934 "determines if an extension name is supported")
2935 (heading "Parameters")
2936 (table (% (formatter (asis)))
2937 (entry (% (heading (var "extName")))
2938 (para "
2939 Specifies an extension name. "))
2940 (entry (% (heading (var "extString")))
2941 (para "
2942 Specifies a space-separated list of extension names supported. ")))
2943 (heading "Description")
2944 (para (code "gluCheckExtension")
2945 " returns "
2946 (code "GLU_TRUE")
2947 " if "
2948 (var "extName")
2949 " is supported otherwise "
2950 (code "GLU_FALSE")
2951 " is returned. ")
2952 (para "
2953 This is used to check for the presence for OpenGL, GLU, or GLX extension names
2954 by passing the extension strings returned by "
2955 (code "glGetString")
2956 ", "
2957 (code "gluGetString")
2958 ", "
2959 (code "glXGetClientString")
2960 ", "
2961 (code "glXQueryExtensionsString")
2962 ", or "
2963 (code "glXQueryServerString")
2964 ",
2965 respectively, as "
2966 (var "extString")
2967 ". ")))
2968
2969 (define-gl-procedure
2970 gluCylinder
2971 "gluCylinder"
2972 (funcsynopsis
2973 (funcprototype
2974 (funcdef "void " (function "gluCylinder"))
2975 (paramdef "GLUquadric* " (parameter "quad"))
2976 (paramdef "GLdouble " (parameter "base"))
2977 (paramdef "GLdouble " (parameter "top"))
2978 (paramdef "GLdouble " (parameter "height"))
2979 (paramdef "GLint " (parameter "slices"))
2980 (paramdef "GLint " (parameter "stacks"))))
2981 '(*fragment*
2982 (heading "draw a cylinder")
2983 (heading "Parameters")
2984 (table (% (formatter (asis)))
2985 (entry (% (heading (var "quad")))
2986 (para "
2987 Specifies the quadrics object (created with "
2988 (code "gluNewQuadric")
2989 "). "))
2990 (entry (% (heading (var "base")))
2991 (para "
2992 Specifies the radius of the cylinder at "
2993 (var "z")
2994 " = 0. "))
2995 (entry (% (heading (var "top")))
2996 (para "
2997 Specifies the radius of the cylinder at "
2998 (var "z")
2999 " = "
3000 (var "height")
3001 ". "))
3002 (entry (% (heading (var "height")))
3003 (para "
3004 Specifies the height of the cylinder. "))
3005 (entry (% (heading (var "slices")))
3006 (para "
3007 Specifies the number of subdivisions around the "
3008 (var "z")
3009 " axis. "))
3010 (entry (% (heading (var "stacks")))
3011 (para "
3012 Specifies the number of subdivisions along the "
3013 (var "z")
3014 " axis. ")))
3015 (heading "Description")
3016 (para (code "gluCylinder")
3017 " draws a cylinder oriented along the "
3018 (var "z")
3019 " axis. The base of the cylinder
3020 is placed at "
3021 (var "z")
3022 " = 0 and the top at "
3023 (math (var "z") "=" (var "height"))
3024 ".
3025 Like a sphere,
3026 a cylinder is subdivided around the "
3027 (var "z")
3028 " axis into slices and along the "
3029 (var "z")
3030 " axis into stacks. ")
3031 (para "
3032 Note that if "
3033 (var "top")
3034 " is set to 0.0, this routine generates a cone. ")
3035 (para "
3036 If the orientation is set to "
3037 (code "GLU_OUTSIDE")
3038 " (with "
3039 (code "gluQuadricOrientation")
3040 "), then any generated normals
3041 point away from the "
3042 (var "z")
3043 " axis. Otherwise, they point toward the "
3044 (var "z")
3045 " axis. ")
3046 (para "
3047 If texturing is turned on (with "
3048 (code "gluQuadricTexture")
3049 "), then texture
3050 coordinates are generated so that "
3051 (var "t")
3052 " ranges linearly from 0.0
3053 at "
3054 (var "z")
3055 " = 0 to 1.0 at "
3056 (var "z")
3057 " = "
3058 (var "height")
3059 ", and "
3060 (var "s")
3061 " ranges from 0.0 at the +"
3062 (var "y")
3063 " axis, to 0.25 at the +"
3064 (var "x")
3065 " axis,
3066 to 0.5 at the -"
3067 (var "y")
3068 " axis, to 0.75 at the \\-"
3069 (var "x")
3070 " axis,
3071 and back to 1.0 at the +"
3072 (var "y")
3073 " axis. ")))
3074
3075 (define-gl-procedure
3076 gluDeleteNurbsRenderer
3077 "gluDeleteNurbsRenderer"
3078 (funcsynopsis
3079 (funcprototype
3080 (funcdef
3081 "void "
3082 (function "gluDeleteNurbsRenderer"))
3083 (paramdef "GLUnurbs* " (parameter "nurb"))))
3084 '(*fragment*
3085 (heading "destroy a NURBS object")
3086 (heading "Parameters")
3087 (table (% (formatter (asis)))
3088 (entry (% (heading (var "nurb")))
3089 (para "
3090 Specifies the NURBS object to be destroyed. ")))
3091 (heading "Description")
3092 (para (code "gluDeleteNurbsRenderer")
3093 " destroys the NURBS object (which was created with "
3094 (code "gluNewNurbsRenderer")
3095 ") and frees any memory it uses.
3096 Once "
3097 (code "gluDeleteNurbsRenderer")
3098 " has been called, "
3099 (var "nurb")
3100 " cannot be used again. ")))
3101
3102 (define-gl-procedure
3103 gluDeleteQuadric
3104 "gluDeleteQuadric"
3105 (funcsynopsis
3106 (funcprototype
3107 (funcdef "void " (function "gluDeleteQuadric"))
3108 (paramdef "GLUquadric* " (parameter "quad"))))
3109 '(*fragment*
3110 (heading "destroy a quadrics object")
3111 (heading "Parameters")
3112 (table (% (formatter (asis)))
3113 (entry (% (heading (var "quad")))
3114 (para "
3115 Specifies the quadrics object to be destroyed. ")))
3116 (heading "Description")
3117 (para (code "gluDeleteQuadric")
3118 " destroys the quadrics object (created with "
3119 (code "gluNewQuadric")
3120 ")
3121 and frees any memory it uses.
3122 Once "
3123 (code "gluDeleteQuadric")
3124 " has been called, "
3125 (var "quad")
3126 " cannot be used again. ")))
3127
3128 (define-gl-procedure
3129 gluDeleteTess
3130 "gluDeleteTess"
3131 (funcsynopsis
3132 (funcprototype
3133 (funcdef "void " (function "gluDeleteTess"))
3134 (paramdef "GLUtesselator* " (parameter "tess"))))
3135 '(*fragment*
3136 (heading "destroy a tessellation object")
3137 (heading "Parameters")
3138 (table (% (formatter (asis)))
3139 (entry (% (heading (var "tess")))
3140 (para "
3141 Specifies the tessellation object to destroy. ")))
3142 (heading "Description")
3143 (para (code "gluDeleteTess")
3144 " destroys the indicated tessellation object (which was created
3145 with "
3146 (code "gluNewTess")
3147 ") and frees any memory that it used. ")))
3148
3149 (define-gl-procedure
3150 gluDisk
3151 "gluDisk"
3152 (funcsynopsis
3153 (funcprototype
3154 (funcdef "void " (function "gluDisk"))
3155 (paramdef "GLUquadric* " (parameter "quad"))
3156 (paramdef "GLdouble " (parameter "inner"))
3157 (paramdef "GLdouble " (parameter "outer"))
3158 (paramdef "GLint " (parameter "slices"))
3159 (paramdef "GLint " (parameter "loops"))))
3160 '(*fragment*
3161 (heading "draw a disk")
3162 (heading "Parameters")
3163 (table (% (formatter (asis)))
3164 (entry (% (heading (var "quad")))
3165 (para "
3166 Specifies the quadrics object (created with "
3167 (code "gluNewQuadric")
3168 "). "))
3169 (entry (% (heading (var "inner")))
3170 (para "
3171 Specifies the inner radius of the disk (may be 0). "))
3172 (entry (% (heading (var "outer")))
3173 (para "
3174 Specifies the outer radius of the disk. "))
3175 (entry (% (heading (var "slices")))
3176 (para "
3177 Specifies the number of subdivisions around the "
3178 (var "z")
3179 " axis. "))
3180 (entry (% (heading (var "loops")))
3181 (para "
3182 Specifies the number of concentric rings about the origin into which
3183 the disk is subdivided. ")))
3184 (heading "Description")
3185 (para (code "gluDisk")
3186 " renders a disk on the "
3187 (var "z")
3188 " = 0 plane. The disk has a radius of "
3189 (var "outer")
3190 " and contains a concentric circular hole with a radius
3191 of "
3192 (var "inner")
3193 ". If "
3194 (var "inner")
3195 " is 0, then no hole is generated. The disk is
3196 subdivided around the "
3197 (var "z")
3198 " axis into slices (like pizza slices) and also
3199 about the "
3200 (var "z")
3201 " axis into rings
3202 (as specified by "
3203 (var "slices")
3204 " and "
3205 (var "loops")
3206 ", respectively). ")
3207 (para "
3208 With respect to orientation, the +"
3209 (var "z")
3210 " side of the disk is considered to be
3211 ``outside'' (see "
3212 (code "gluQuadricOrientation")
3213 ").
3214 This means that if the
3215 orientation is set to "
3216 (code "GLU_OUTSIDE")
3217 ", then any normals generated
3218 point along the +"
3219 (var "z")
3220 " axis. Otherwise, they point along the \\-"
3221 (var "z")
3222 " axis. ")
3223 (para "
3224 If texturing has been turned on (with "
3225 (code "gluQuadricTexture")
3226 "),
3227 texture coordinates are generated
3228 linearly such that where "
3229 (math (var "r") "=" (var "outer"))
3230 ",
3231 the value at ("
3232 (var "r")
3233 ", 0, 0) is
3234 (1, 0.5), at (0, "
3235 (var "r")
3236 ", 0) it is (0.5, 1), at (\\-"
3237 (var "r")
3238 ", 0, 0)
3239 it is (0, 0.5), and
3240 at (0, \\-"
3241 (var "r")
3242 ", 0) it is (0.5, 0). ")))
3243
3244 (define-gl-procedure
3245 gluErrorString
3246 "gluErrorString"
3247 (funcsynopsis
3248 (funcprototype
3249 (funcdef
3250 "const GLubyte * "
3251 (function "gluErrorString"))
3252 (paramdef "GLenum " (parameter "error"))))
3253 '(*fragment*
3254 (heading
3255 "produce an error string from a GL or GLU error code")
3256 (heading "Parameters")
3257 (table (% (formatter (asis)))
3258 (entry (% (heading (var "error")))
3259 (para "
3260 Specifies a GL or GLU error code. ")))
3261 (heading "Description")
3262 (para (code "gluErrorString")
3263 " produces an error string from a GL or GLU error code. The string
3264 is in ISO Latin 1 format. For example, "
3265 (code "gluErrorString")
3266 "("
3267 (code "GLU_OUT_OF_MEMORY")
3268 ") returns the string "
3269 (var "out of memory")
3270 ". ")
3271 (para "
3272 The standard GLU error codes are "
3273 (code "GLU_INVALID_ENUM")
3274 ", "
3275 (code "GLU_INVALID_VALUE")
3276 ",
3277 and "
3278 (code "GLU_OUT_OF_MEMORY")
3279 ".
3280 Certain other GLU functions can return specialized error codes
3281 through callbacks.
3282 See the "
3283 (code "glGetError")
3284 " reference page for the list of
3285 GL error codes. ")
3286 (heading "Errors")
3287 (para (code "NULL")
3288 " is returned if "
3289 (var "error")
3290 " is not a valid GL or GLU error code. ")))
3291
3292 (define-gl-procedure
3293 gluGetNurbsProperty
3294 "gluGetNurbsProperty"
3295 (funcsynopsis
3296 (funcprototype
3297 (funcdef
3298 "void "
3299 (function "gluGetNurbsProperty"))
3300 (paramdef "GLUnurbs* " (parameter "nurb"))
3301 (paramdef "GLenum " (parameter "property"))
3302 (paramdef "GLfloat* " (parameter "data"))))
3303 '(*fragment*
3304 (heading "get a NURBS property")
3305 (heading "Parameters")
3306 (table (% (formatter (asis)))
3307 (entry (% (heading (var "nurb")))
3308 (para "
3309 Specifies the NURBS object (created with "
3310 (code "gluNewNurbsRenderer")
3311 "). "))
3312 (entry (% (heading (var "property")))
3313 (para "
3314 Specifies the property whose value is to be fetched. Valid values are "
3315 (code "GLU_CULLING")
3316 ", "
3317 (code "GLU_SAMPLING_TOLERANCE")
3318 ", "
3319 (code "GLU_DISPLAY_MODE")
3320 ", "
3321 (code "GLU_AUTO_LOAD_MATRIX")
3322 ", "
3323 (code "GLU_PARAMETRIC_TOLERANCE")
3324 ", "
3325 (code "GLU_SAMPLING_METHOD")
3326 ", "
3327 (code "GLU_U_STEP")
3328 ", "
3329 (code "GLU_V_STEP")
3330 ", and "
3331 (code "GLU_NURBS_MODE")
3332 ". "))
3333 (entry (% (heading (var "data")))
3334 (para "
3335 Specifies a pointer to the location into which the value of the
3336 named property is written. ")))
3337 (heading "Description")
3338 (para (code "gluGetNurbsProperty")
3339 " retrieves properties stored in a NURBS object. These
3340 properties affect the way that NURBS curves and surfaces
3341 are rendered. See the "
3342 (code "gluNurbsProperty")
3343 " reference page for information about what the
3344 properties are and what they do. ")))
3345
3346 (define-gl-procedure
3347 gluGetString
3348 "gluGetString"
3349 (funcsynopsis
3350 (funcprototype
3351 (funcdef
3352 "const GLubyte * "
3353 (function "gluGetString"))
3354 (paramdef "GLenum " (parameter "name"))))
3355 '(*fragment*
3356 (heading
3357 "return a string describing the GLU version or GLU extensions ")
3358 (heading "Parameters")
3359 (table (% (formatter (asis)))
3360 (entry (% (heading (var "name")))
3361 (para "
3362 Specifies a symbolic constant, one of "
3363 (code "GLU_VERSION")
3364 ", or "
3365 (code "GLU_EXTENSIONS")
3366 ". ")))
3367 (heading "Description")
3368 (para (code "gluGetString")
3369 " returns a pointer to a static string describing the
3370 GLU version or the GLU extensions that are supported. ")
3371 (para "
3372 The version number is one of the following
3373 forms: ")
3374 (para (var "major_number.minor_number")
3375 (var "major_number.minor_number.release_number")
3376 ". ")
3377 (para "
3378 The version string is of the following form: ")
3379 (para (var "version number<space>vendor-specific information"))
3380 (para "
3381 Vendor-specific information is optional.
3382 Its format and contents depend on the implementation. ")
3383 (para "
3384 The standard GLU contains a basic set of features and capabilities.
3385 If a company or group of companies wish to support other features,
3386 these may be included as extensions to the GLU.
3387 If "
3388 (var "name")
3389 " is "
3390 (code "GLU_EXTENSIONS")
3391 ", then "
3392 (code "gluGetString")
3393 "
3394 returns a space-separated list of names of supported GLU extensions.
3395 (Extension names never contain spaces.) ")
3396 (para "
3397 All strings are null-terminated. ")
3398 (heading "Errors")
3399 (para "
3400 NULL is returned if "
3401 (var "name")
3402 " is not "
3403 (code "GLU_VERSION")
3404 " or "
3405 (code "GLU_EXTENSIONS")
3406 ". ")
3407 (para)))
3408
3409 (define-gl-procedure
3410 gluGetTessProperty
3411 "gluGetTessProperty"
3412 (funcsynopsis
3413 (funcprototype
3414 (funcdef "void " (function "gluGetTessProperty"))
3415 (paramdef "GLUtesselator* " (parameter "tess"))
3416 (paramdef "GLenum " (parameter "which"))
3417 (paramdef "GLdouble* " (parameter "data"))))
3418 '(*fragment*
3419 (heading "get a tessellation object property")
3420 (heading "Parameters")
3421 (table (% (formatter (asis)))
3422 (entry (% (heading (var "tess")))
3423 (para "
3424 Specifies the tessellation object (created with "
3425 (code "gluNewTess")
3426 "). "))
3427 (entry (% (heading (var "which")))
3428 (para "
3429 Specifies the property whose value is to be fetched. Valid values are "
3430 (code "GLU_TESS_WINDING_RULE")
3431 ", "
3432 (code "GLU_TESS_BOUNDARY_ONLY")
3433 ", and "
3434 (code "GLU_TESS_TOLERANCE")
3435 ". "))
3436 (entry (% (heading (var "data")))
3437 (para "
3438 Specifies a pointer to the location into which the value of the
3439 named property is written. ")))
3440 (heading "Description")
3441 (para (code "gluGetTessProperty")
3442 " retrieves properties stored in a tessellation object. These
3443 properties affect the way that tessellation objects
3444 are interpreted and rendered. See the "
3445 (code "gluTessProperty")
3446 " reference page for information about the
3447 properties and what they do. ")))
3448
3449 (define-gl-procedure
3450 gluLoadSamplingMatrices
3451 "gluLoadSamplingMatrices"
3452 (funcsynopsis
3453 (funcprototype
3454 (funcdef
3455 "void "
3456 (function "gluLoadSamplingMatrices"))
3457 (paramdef "GLUnurbs* " (parameter "nurb"))
3458 (paramdef "const GLfloat * " (parameter "model"))
3459 (paramdef
3460 "const GLfloat * "
3461 (parameter "perspective"))
3462 (paramdef "const GLint * " (parameter "view"))))
3463 '(*fragment*
3464 (heading
3465 "load NURBS sampling and culling matrices")
3466 (heading "Parameters")
3467 (table (% (formatter (asis)))
3468 (entry (% (heading (var "nurb")))
3469 (para "
3470 Specifies the NURBS object (created with "
3471 (code "gluNewNurbsRenderer")
3472 "). "))
3473 (entry (% (heading (var "model")))
3474 (para "
3475 Specifies a modelview matrix (as from a "
3476 (code "glGetFloatv")
3477 " call). "))
3478 (entry (% (heading (var "perspective")))
3479 (para "
3480 Specifies a projection matrix (as from a "
3481 (code "glGetFloatv")
3482 " call). "))
3483 (entry (% (heading (var "view")))
3484 (para "
3485 Specifies a viewport (as from a "
3486 (code "glGetIntegerv")
3487 " call). ")))
3488 (heading "Description")
3489 (para (code "gluLoadSamplingMatrices")
3490 " uses "
3491 (var "model")
3492 ", "
3493 (var "perspective")
3494 ", and "
3495 (var "view")
3496 " to recompute the sampling and culling
3497 matrices stored in "
3498 (var "nurb")
3499 ".
3500 The sampling matrix determines how finely a NURBS curve or surface
3501 must be tessellated to satisfy the sampling tolerance (as determined by the "
3502 (code "GLU_SAMPLING_TOLERANCE")
3503 " property).
3504 The culling matrix is used in deciding if a NURBS curve or surface
3505 should be culled before
3506 rendering (when the "
3507 (code "GLU_CULLING")
3508 " property is turned on). ")
3509 (para (code "gluLoadSamplingMatrices")
3510 " is necessary only if the "
3511 (code "GLU_AUTO_LOAD_MATRIX")
3512 " property is turned
3513 off (see "
3514 (code "gluNurbsProperty")
3515 ").
3516 Although it can be convenient to leave the "
3517 (code "GLU_AUTO_LOAD_MATRIX")
3518 "
3519 property turned on, there can be a performance penalty for doing so.
3520 (A round trip to the GL server is needed to fetch the current values
3521 of the modelview matrix, projection matrix, and viewport.) ")))
3522
3523 (define-gl-procedure
3524 gluLookAt
3525 "gluLookAt"
3526 (funcsynopsis
3527 (funcprototype
3528 (funcdef "void " (function "gluLookAt"))
3529 (paramdef "GLdouble " (parameter "eyeX"))
3530 (paramdef "GLdouble " (parameter "eyeY"))
3531 (paramdef "GLdouble " (parameter "eyeZ"))
3532 (paramdef "GLdouble " (parameter "centerX"))
3533 (paramdef "GLdouble " (parameter "centerY"))
3534 (paramdef "GLdouble " (parameter "centerZ"))
3535 (paramdef "GLdouble " (parameter "upX"))
3536 (paramdef "GLdouble " (parameter "upY"))
3537 (paramdef "GLdouble " (parameter "upZ"))))
3538 '(*fragment*
3539 (heading "define a viewing transformation")
3540 (heading "Parameters")
3541 (table (% (formatter (asis)))
3542 (entry (% (heading (var "eyeX")))
3543 (itemx (var "eyeY"))
3544 (itemx (var "eyeZ"))
3545 (para "
3546 Specifies the position of the eye point. "))
3547 (entry (% (heading (var "centerX")))
3548 (itemx (var "centerY"))
3549 (itemx (var "centerZ"))
3550 (para "
3551 Specifies the position of the reference point. "))
3552 (entry (% (heading (var "upX")))
3553 (itemx (var "upY"))
3554 (itemx (var "upZ"))
3555 (para "
3556 Specifies the direction of the "
3557 (var "up")
3558 " vector. ")))
3559 (heading "Description")
3560 (para (code "gluLookAt")
3561 " creates a viewing matrix derived from an eye point, a reference
3562 point indicating the center of the scene, and an "
3563 (var "UP")
3564 " vector. ")
3565 (para "
3566 The matrix
3567 maps the reference point to the negative "
3568 (var "z")
3569 " axis and the
3570 eye point to the origin.
3571 When a typical projection matrix is used,
3572 the center of the scene therefore maps to the center of the viewport.
3573 Similarly, the direction described by the "
3574 (var "UP")
3575 "
3576 vector projected onto the viewing plane is mapped to the positive "
3577 (var "y")
3578 " axis so that it points upward in the viewport.
3579 The "
3580 (var "UP")
3581 " vector must not be parallel to the line of sight from the
3582 eye point to the reference point. ")
3583 (para "
3584 Let ")
3585 (para (math (var "F")
3586 "="
3587 "("
3588 "("
3589 (var "centerX")
3590 "-"
3591 (var "eyeX")
3592 ")"
3593 ", "
3594 "("
3595 (var "centerY")
3596 "-"
3597 (var "eyeY")
3598 ")"
3599 ", "
3600 "("
3601 (var "centerZ")
3602 "-"
3603 (var "eyeZ")
3604 ")"
3605 ","
3606 ")"))
3607 (para)
3608 (para "
3609 Let "
3610 (var "UP")
3611 " be the vector "
3612 (math "("
3613 (var "upX")
3614 ","
3615 (var "upY")
3616 (var "upZ")
3617 ")")
3618 ". ")
3619 (para "
3620 Then normalize as follows: "
3621 (math (var "f")
3622 "="
3623 (var "F")
3624 "/"
3625 "∥"
3626 (var "F")
3627 ","
3628 "∥"
3629 ","))
3630 (para (math (var "UP")
3631 "^"
3632 "″"
3633 "="
3634 (var "UP")
3635 "/"
3636 "∥"
3637 (var "UP")
3638 ","
3639 "∥"
3640 ","))
3641 (para)
3642 (para "
3643 Finally, let "
3644 (math (var "s")
3645 "="
3646 (var "f")
3647 "×"
3648 (var "UP")
3649 "^"
3650 "″")
3651 ",
3652 and "
3653 (math (var "u") "=" (var "s") "×" (var "f"))
3654 ". ")
3655 (para)
3656 (para "
3657 M is then constructed as follows: "
3658 (math (var "M")
3659 "="
3660 "("
3661 "("
3662 (var "s")
3663 "\u2061"
3664 "["
3665 "0"
3666 ","
3667 "]"
3668 " "
3669 (var "s")
3670 "\u2061"
3671 "["
3672 "1"
3673 ","
3674 "]"
3675 " "
3676 (var "s")
3677 "\u2061"
3678 "["
3679 "2"
3680 ","
3681 "]"
3682 " "
3683 "0"
3684 ")"
3685 ", "
3686 "("
3687 (var "u")
3688 "\u2061"
3689 "["
3690 "0"
3691 ","
3692 "]"
3693 " "
3694 (var "u")
3695 "\u2061"
3696 "["
3697 "1"
3698 ","
3699 "]"
3700 " "
3701 (var "u")
3702 "\u2061"
3703 "["
3704 "2"
3705 ","
3706 "]"
3707 " "
3708 "0"
3709 ")"
3710 ", "
3711 "("
3712 "-"
3713 (var "f")
3714 "\u2061"
3715 "["
3716 "0"
3717 ","
3718 "]"
3719 " "
3720 "-"
3721 (var "f")
3722 "\u2061"
3723 "["
3724 "1"
3725 ","
3726 "]"
3727 " "
3728 "-"
3729 (var "f")
3730 "\u2061"
3731 "["
3732 "2"
3733 ","
3734 "]"
3735 " "
3736 "0"
3737 ")"
3738 ", "
3739 "("
3740 "0"
3741 " "
3742 "0"
3743 " "
3744 "0"
3745 " "
3746 "1"
3747 ")"
3748 ","
3749 ")"))
3750 (para "
3751 and "
3752 (code "gluLookAt")
3753 " is equivalent to ")
3754 (example
3755 "
3756 glMultMatrixf(M);
3757 glTranslated(-eyex, -eyey, -eyez); ")))
3758
3759 (define-gl-procedure
3760 gluNewNurbsRenderer
3761 "gluNewNurbsRenderer"
3762 (funcsynopsis
3763 (funcprototype
3764 (funcdef
3765 "GLUnurbs* "
3766 (function "gluNewNurbsRenderer"))))
3767 '(*fragment*
3768 (heading "create a NURBS object")
3769 (heading "Description")
3770 (para (code "gluNewNurbsRenderer")
3771 " creates and returns a pointer to
3772 a new NURBS object.
3773 This object must be referred to when calling
3774 NURBS rendering and control functions. A return value of
3775 0 means that there is not enough memory to allocate the object. ")))
3776
3777 (define-gl-procedure
3778 gluNewQuadric
3779 "gluNewQuadric"
3780 (funcsynopsis
3781 (funcprototype
3782 (funcdef
3783 "GLUquadric* "
3784 (function "gluNewQuadric"))))
3785 '(*fragment*
3786 (heading "create a quadrics object")
3787 (heading "Description")
3788 (para (code "gluNewQuadric")
3789 " creates and returns a pointer to
3790 a new quadrics object. This object must be referred to when
3791 calling quadrics rendering and control functions. A return value of
3792 0 means that there is not enough memory to allocate the object. ")))
3793
3794 (define-gl-procedure
3795 gluNewTess
3796 "gluNewTess"
3797 (funcsynopsis
3798 (funcprototype
3799 (funcdef
3800 "GLUtesselator* "
3801 (function "gluNewTess"))))
3802 '(*fragment*
3803 (heading "create a tessellation object")
3804 (heading "Description")
3805 (para (code "gluNewTess")
3806 " creates and returns a pointer to a new tessellation object.
3807 This object must be referred to when calling
3808 tessellation functions. A return value of
3809 0 means that there is not enough memory to allocate the object. ")))
3810
3811 (define-gl-procedure
3812 gluNextContour
3813 "gluNextContour"
3814 (funcsynopsis
3815 (funcprototype
3816 (funcdef "void " (function "gluNextContour"))
3817 (paramdef "GLUtesselator* " (parameter "tess"))
3818 (paramdef "GLenum " (parameter "type"))))
3819 '(*fragment*
3820 (heading "mark the beginning of another contour")
3821 (heading "Parameters")
3822 (table (% (formatter (asis)))
3823 (entry (% (heading (var "tess")))
3824 (para "
3825 Specifies the tessellation object (created with "
3826 (code "gluNewTess")
3827 "). "))
3828 (entry (% (heading (var "type")))
3829 (para "
3830 Specifies the type of the contour being defined. Valid values are "
3831 (code "GLU_EXTERIOR")
3832 ", "
3833 (code "GLU_INTERIOR")
3834 ", "
3835 (code "GLU_UNKNOWN")
3836 ", "
3837 (code "GLU_CCW")
3838 ", and "
3839 (code "GLU_CW")
3840 ". ")))
3841 (heading "Description")
3842 (para (code "gluNextContour")
3843 " is used in describing polygons with multiple contours. After the first
3844 contour has been described through a series of "
3845 (code "gluTessVertex")
3846 " calls,
3847 a "
3848 (code "gluNextContour")
3849 " call indicates that the previous contour is complete and that the
3850 next contour is about to begin.
3851 Another series of "
3852 (code "gluTessVertex")
3853 " calls is then used to describe the new
3854 contour. This process can be repeated until all contours have been described. ")
3855 (para (var "type")
3856 " defines what type of contour follows.
3857 The legal contour types are as follows: ")
3858 (table (% (formatter (asis)))
3859 (entry (% (heading (code "GLU_EXTERIOR")))
3860 (para "
3861 An exterior contour defines an exterior boundary of the polygon. "))
3862 (entry (% (heading (code "GLU_INTERIOR")))
3863 (para "
3864 An interior contour defines an interior boundary of the polygon (such as
3865 a hole). "))
3866 (entry (% (heading (code "GLU_UNKNOWN")))
3867 (para "
3868 An unknown contour is analyzed by the library to determine if it is interior
3869 or exterior. "))
3870 (entry (% (heading (code "GLU_CCW") ", ")))
3871 (entry (% (heading (code "GLU_CW")))
3872 (para "
3873 The first "
3874 (code "GLU_CCW")
3875 " or "
3876 (code "GLU_CW")
3877 " contour defined is considered to
3878 be exterior. All other contours are considered to be exterior if they
3879 are oriented in the same direction (clockwise or counterclockwise) as
3880 the first contour, and interior if they are not. ")))
3881 (para "
3882 If one contour is of type "
3883 (code "GLU_CCW")
3884 " or "
3885 (code "GLU_CW")
3886 ", then all
3887 contours must be of the same type (if they are not, then all "
3888 (code "GLU_CCW")
3889 "
3890 and "
3891 (code "GLU_CW")
3892 " contours will be changed to "
3893 (code "GLU_UNKNOWN")
3894 "). ")
3895 (para "
3896 Note that there is no real difference between the "
3897 (code "GLU_CCW")
3898 " and "
3899 (code "GLU_CW")
3900 " contour types. ")
3901 (para "
3902 Before the first contour is described, "
3903 (code "gluNextContour")
3904 " can be called to
3905 define the type of the first contour.
3906 If "
3907 (code "gluNextContour")
3908 " is not called before the first contour, then the first contour is
3909 marked "
3910 (code "GLU_EXTERIOR")
3911 ". ")
3912 (para "
3913 This command is obsolete and is provided for backward compatibility
3914 only. Calls to "
3915 (code "gluNextContour")
3916 " are mapped to "
3917 (code "gluTessEndContour")
3918 "
3919 followed by "
3920 (code "gluTessBeginContour")
3921 ". ")))
3922
3923 (define-gl-procedure
3924 gluNurbsCallbackDataEXT
3925 "gluNurbsCallbackDataEXT"
3926 (funcsynopsis
3927 (funcprototype
3928 (funcdef
3929 "void "
3930 (function "gluNurbsCallbackDataEXT"))
3931 (paramdef "GLUnurbs* " (parameter "nurb"))
3932 (paramdef "GLvoid* " (parameter "userData"))))
3933 '(*fragment*
3934 (heading "set a user data pointer")
3935 (heading "Parameters")
3936 (table (% (formatter (asis)))
3937 (entry (% (heading (var "nurb")))
3938 (para "
3939 Specifies the NURBS object (created with "
3940 (code "gluNewNurbsRenderer")
3941 "). "))
3942 (entry (% (heading (var "userData")))
3943 (para "
3944 Specifies a pointer to the user's data. ")))
3945 (heading "Description")
3946 (para (code "gluNurbsCallbackDataEXT")
3947 " is used to pass a pointer to the application's data to NURBS
3948 tessellator. A copy of this pointer will be passed by the tessellator
3949 in the NURBS callback functions (set by "
3950 (code "gluNurbsCallback")
3951 "). ")))
3952
3953 (define-gl-procedure
3954 gluNurbsCallbackData
3955 "gluNurbsCallbackData"
3956 (funcsynopsis
3957 (funcprototype
3958 (funcdef
3959 "void "
3960 (function "gluNurbsCallbackData"))
3961 (paramdef "GLUnurbs* " (parameter "nurb"))
3962 (paramdef "GLvoid* " (parameter "userData"))))
3963 '(*fragment*
3964 (heading "set a user data pointer")
3965 (heading "Parameters")
3966 (table (% (formatter (asis)))
3967 (entry (% (heading (var "nurb")))
3968 (para "
3969 Specifies the NURBS object (created with "
3970 (code "gluNewNurbsRenderer")
3971 "). "))
3972 (entry (% (heading (var "userData")))
3973 (para "
3974 Specifies a pointer to the user's data. ")))
3975 (heading "Description")
3976 (para (code "gluNurbsCallbackData")
3977 " is used to pass a pointer to the application's data to NURBS
3978 tessellator. A copy of this pointer will be passed by the tessellator
3979 in the NURBS callback functions (set by "
3980 (code "gluNurbsCallback")
3981 "). ")))
3982
3983 (define-gl-procedure
3984 gluNurbsCallback
3985 "gluNurbsCallback"
3986 (funcsynopsis
3987 (funcprototype
3988 (funcdef "void " (function "gluNurbsCallback"))
3989 (paramdef "GLUnurbs* " (parameter "nurb"))
3990 (paramdef "GLenum " (parameter "which"))
3991 (paramdef
3992 "_GLUfuncptr "
3993 (parameter "CallBackFunc"))))
3994 '(*fragment*
3995 (heading "define a callback for a NURBS object")
3996 (heading "Parameters")
3997 (table (% (formatter (asis)))
3998 (entry (% (heading (var "nurb")))
3999 (para "
4000 Specifies the NURBS object (created with "
4001 (code "gluNewNurbsRenderer")
4002 "). "))
4003 (entry (% (heading (var "which")))
4004 (para "
4005 Specifies the callback being defined.
4006 Valid values are "
4007 (code "GLU_NURBS_BEGIN")
4008 ", "
4009 (code "GLU_NURBS_VERTEX")
4010 ", "
4011 (code "GLU_NURBS_NORMAL")
4012 ", "
4013 (code "GLU_NURBS_COLOR")
4014 ", "
4015 (code "GLU_NURBS_TEXTURE_COORD")
4016 ", "
4017 (code "GLU_NURBS_END")
4018 ", "
4019 (code "GLU_NURBS_BEGIN_DATA")
4020 ", "
4021 (code "GLU_NURBS_VERTEX_DATA")
4022 ", "
4023 (code "GLU_NURBS_NORMAL_DATA")
4024 ", "
4025 (code "GLU_NURBS_COLOR_DATA")
4026 ", "
4027 (code "GLU_NURBS_TEXTURE_COORD_DATA")
4028 ", "
4029 (code "GLU_NURBS_END_DATA")
4030 ", and "
4031 (code "GLU_NURBS_ERROR")
4032 ". "))
4033 (entry (% (heading (var "CallBackFunc")))
4034 (para "
4035 Specifies the function that the callback calls. ")))
4036 (heading "Description")
4037 (para (code "gluNurbsCallback")
4038 " is used to define a callback to be used by a NURBS
4039 object.
4040 If the specified callback is already defined, then it is replaced. If "
4041 (var "CallBackFunc")
4042 " is NULL, then this callback will not get
4043 invoked and the related data, if any, will be lost. ")
4044 (para "
4045 Except the error callback, these callbacks are used by NURBS tessellator (when "
4046 (code "GLU_NURBS_MODE")
4047 " is set to be "
4048 (code "GLU_NURBS_TESSELLATOR")
4049 ") to return back the OpenGL
4050 polygon primitives resulting from the tessellation. Note that there are two
4051 versions of each callback: one with a user data pointer and one without. If both versions for a particular callback are specified then the callback with
4052 the user data pointer will be used. Note that ``userData'' is a copy of the pointer that was specified at the last call to "
4053 (code "gluNurbsCallbackData")
4054 ". ")
4055 (para "
4056 The error callback function is effective no matter which value that "
4057 (code "GLU_NURBS_MODE")
4058 " is set to.
4059 All other callback functions are effective only when "
4060 (code "GLU_NURBS_MODE")
4061 "
4062 is set to "
4063 (code "GLU_NURBS_TESSELLATOR")
4064 ". ")
4065 (para "
4066 The legal callbacks are as follows: ")
4067 (table (% (formatter (asis)))
4068 (entry (% (heading (code "GLU_NURBS_BEGIN")))
4069 (para)
4070 (para "
4071 The begin callback indicates the start of a primitive. The function
4072 takes a single argument of type GLenum, which can be one of "
4073 (code "GLU_LINES")
4074 ", "
4075 (code "GLU_LINE_STRIP")
4076 ", "
4077 (code "GLU_TRIANGLE_FAN")
4078 ", "
4079 (code "GLU_TRIANGLE_STRIP")
4080 ", "
4081 (code "GLU_TRIANGLES")
4082 ", or "
4083 (code "GLU_QUAD_STRIP")
4084 ". The
4085 default begin callback function is NULL. The function prototype
4086 for this callback looks like: "))
4087 (entry (% (heading (code "GLU_NURBS_BEGIN_DATA")))
4088 (para)
4089 (para "
4090 The same as the "
4091 (code "GLU_NURBS_BEGIN")
4092 " callback except that it takes an
4093 additional pointer argument. This pointer is a copy of the pointer that
4094 was specified at the last call to "
4095 (code "gluNurbsCallbackData")
4096 ". The
4097 default callback function is NULL. The function prototype for this
4098 callback function looks like: "))
4099 (entry (% (heading (code "GLU_NURBS_VERTEX")))
4100 (para)
4101 (para "
4102 The vertex callback indicates a vertex of the primitive. The
4103 coordinates of the vertex are stored in the parameter ``vertex''. All
4104 the generated vertices have dimension 3; that is, homogeneous
4105 coordinates have been transformed into affine coordinates. The default
4106 vertex callback function is NULL. The function prototype for this
4107 callback function looks like: "))
4108 (entry (% (heading (code "GLU_NURBS_VERTEX_DATA")))
4109 (para)
4110 (para "
4111 This is the same as the "
4112 (code "GLU_NURBS_VERTEX")
4113 " callback, except that
4114 it takes an additional pointer argument. This pointer is a copy of the
4115 pointer that was specified at the last call to "
4116 (code "gluNurbsCallbackData")
4117 ". The default callback function is NULL. The
4118 function prototype for this callback function looks like: "))
4119 (entry (% (heading (code "GLU_NURBS_NORMAL")))
4120 (para)
4121 (para "
4122 The normal callback is invoked as the vertex normal is generated.
4123 The components of the normal are stored in the parameter ``normal.''
4124 In the case of a NURBS curve, the callback function is effective only when
4125 the user provides a normal map ("
4126 (code "GLU_MAP1_NORMAL")
4127 ").
4128 In the case of a NURBS surface, if a normal map ("
4129 (code "GLU_MAP2_NORMAL")
4130 ")
4131 is provided, then the generated normal is computed from the normal map.
4132 If a normal map is not provided, then a surface normal is computed in
4133 a manner similar to that described for evaluators when "
4134 (code "GLU_AUTO_NORMAL")
4135 "
4136 is enabled.
4137 The default normal callback function is NULL. The function
4138 prototype for this callback function looks like: "))
4139 (entry (% (heading (code "GLU_NURBS_NORMAL_DATA")))
4140 (para)
4141 (para "
4142 The same as the "
4143 (code "GLU_NURBS_NORMAL")
4144 " callback except that it
4145 takes an additional pointer argument. This pointer is a copy of the pointer
4146 that was specified at the last call to "
4147 (code "gluNurbsCallbackData")
4148 ". The default callback function is NULL. The function prototype for this callback function looks like: "))
4149 (entry (% (heading (code "GLU_NURBS_COLOR")))
4150 (para)
4151 (para "
4152 The color callback is invoked as the color of a vertex is generated.
4153 The components of the color are stored in the parameter ``color.''
4154 This callback is effective only when the user provides a color map
4155 ("
4156 (code "GLU_MAP1_COLOR_4")
4157 " or "
4158 (code "GLU_MAP2_COLOR_4")
4159 "). ``color'' contains four
4160 components: R, G, B, A. The default color callback function is NULL.
4161 The prototype for this callback function looks like: "))
4162 (entry (% (heading (code "GLU_NURBS_COLOR_DATA")))
4163 (para)
4164 (para "
4165 The same as the "
4166 (code "GLU_NURBS_COLOR")
4167 " callback except that it
4168 takes an additional pointer argument. This pointer is a copy of the pointer
4169 that was specified at the last call to "
4170 (code "gluNurbsCallbackData")
4171 ". The default callback function is NULL. The function prototype for this callback function looks like: "))
4172 (entry (% (heading (code "GLU_NURBS_TEXTURE_COORD")))
4173 (para)
4174 (para "
4175 The texture callback is invoked as the texture coordinates
4176 of a vertex are generated. These coordinates are stored in the parameter
4177 ``texCoord.'' The number of texture coordinates can be 1, 2, 3, or 4 depending
4178 on which type of texture map is specified
4179 ("
4180 (code "GLU_MAP1_TEXTURE_COORD_1")
4181 ", "
4182 (code "GLU_MAP1_TEXTURE_COORD_2")
4183 ", "
4184 (code "GLU_MAP1_TEXTURE_COORD_3")
4185 ", "
4186 (code "GLU_MAP1_TEXTURE_COORD_4")
4187 ", "
4188 (code "GLU_MAP2_TEXTURE_COORD_1")
4189 ", "
4190 (code "GLU_MAP2_TEXTURE_COORD_2")
4191 ", "
4192 (code "GLU_MAP2_TEXTURE_COORD_3")
4193 ", "
4194 (code "GLU_MAP2_TEXTURE_COORD_4")
4195 ").
4196 If no texture map is specified, this callback function will not be called.
4197 The default texture callback function is NULL. The function prototype
4198 for this callback function looks like: "))
4199 (entry (% (heading (code "GLU_NURBS_TEXTURE_COORD_DATA")))
4200 (para)
4201 (para "
4202 This is the same as the "
4203 (code "GLU_NURBS_TEXTURE_COORD")
4204 " callback, except that it
4205 takes an additional pointer argument. This pointer is a copy of the pointer
4206 that was specified at the last call to "
4207 (code "gluNurbsCallbackData")
4208 ". The default callback function is NULL. The function prototype for this callback function looks like: "))
4209 (entry (% (heading (code "GLU_NURBS_END")))
4210 (para)
4211 (para "
4212 The end callback is invoked at the end of a primitive. The default end callback function is NULL. The function prototype for this callback function looks like: "))
4213 (entry (% (heading (code "GLU_NURBS_END_DATA")))
4214 (para)
4215 (para "
4216 This is the same as the "
4217 (code "GLU_NURBS_END")
4218 " callback, except that it
4219 takes an additional pointer argument. This pointer is a copy of the pointer
4220 that was specified at the last call to "
4221 (code "gluNurbsCallbackData")
4222 ". The default callback function is NULL. The function prototype for this callback function looks like: "))
4223 (entry (% (heading (code "GLU_NURBS_ERROR")))
4224 (para)
4225 (para "
4226 The error function is called when an error is encountered.
4227 Its single argument
4228 is of type GLenum, and it indicates the specific error that occurred.
4229 There are 37 errors unique to NURBS, named "
4230 (code "GLU_NURBS_ERROR1")
4231 " through "
4232 (code "GLU_NURBS_ERROR37")
4233 ".
4234 Character strings describing these errors can be retrieved with "
4235 (code "gluErrorString")
4236 ". ")))
4237 (example "
4238 void begin( GLenum type ); ")
4239 (example
4240 "
4241 void beginData(GLenum type, void *userData); ")
4242 (example "
4243 void vertex( GLfloat *vertex ); ")
4244 (example
4245 "
4246 void vertexData( GLfloat *vertex, void *userData ); ")
4247 (example "
4248 void normal( GLfloat *normal ); ")
4249 (example
4250 "
4251 void normalData( GLfloat *normal, void *userData ); ")
4252 (example "
4253 void color( GLfloat *color ); ")
4254 (example
4255 "
4256 void colorData( GLfloat *color, void *userData ); ")
4257 (example "
4258 void texCoord( GLfloat *texCoord ); ")
4259 (example
4260 "
4261 void texCoordData( GLfloat *texCoord, void *userData ); ")
4262 (example "
4263 void end( void ); ")
4264 (example "
4265 void endData( void *userData ); ")))
4266
4267 (define-gl-procedure
4268 gluNurbsCurve
4269 "gluNurbsCurve"
4270 (funcsynopsis
4271 (funcprototype
4272 (funcdef "void " (function "gluNurbsCurve"))
4273 (paramdef "GLUnurbs* " (parameter "nurb"))
4274 (paramdef "GLint " (parameter "knotCount"))
4275 (paramdef "GLfloat * " (parameter "knots"))
4276 (paramdef "GLint " (parameter "stride"))
4277 (paramdef "GLfloat * " (parameter "control"))
4278 (paramdef "GLint " (parameter "order"))
4279 (paramdef "GLenum " (parameter "type"))))
4280 '(*fragment*
4281 (heading "define the shape of a NURBS curve")
4282 (heading "Parameters")
4283 (table (% (formatter (asis)))
4284 (entry (% (heading (var "nurb")))
4285 (para "
4286 Specifies the NURBS object (created with "
4287 (code "gluNewNurbsRenderer")
4288 "). "))
4289 (entry (% (heading (var "knotCount")))
4290 (para "
4291 Specifies the number of knots in "
4292 (var "knots")
4293 ". "
4294 (var "knotCount")
4295 " equals the number of control points plus the order. "))
4296 (entry (% (heading (var "knots")))
4297 (para "
4298 Specifies an array of "
4299 (var "knotCount")
4300 " nondecreasing knot values. "))
4301 (entry (% (heading (var "stride")))
4302 (para "
4303 Specifies the offset (as a number of single-precision floating-point values)
4304 between successive curve control points. "))
4305 (entry (% (heading (var "control")))
4306 (para "
4307 Specifies a pointer to an array of control points. The coordinates must
4308 agree with "
4309 (var "type")
4310 ", specified below. "))
4311 (entry (% (heading (var "order")))
4312 (para "
4313 Specifies the order of the NURBS curve. "
4314 (var "order")
4315 " equals degree + 1, hence
4316 a cubic curve has an order of 4. "))
4317 (entry (% (heading (var "type")))
4318 (para "
4319 Specifies the type of the curve. If this curve is defined within a "
4320 (code "gluBeginCurve")
4321 "/"
4322 (code "gluEndCurve")
4323 " pair, then
4324 the type can be any of the valid
4325 one-dimensional evaluator types (such as "
4326 (code "GLU_MAP1_VERTEX_3")
4327 " or "
4328 (code "GLU_MAP1_COLOR_4")
4329 "). Between a "
4330 (code "gluBeginTrim")
4331 "/"
4332 (code "gluEndTrim")
4333 " pair,
4334 the only valid types are "
4335 (code "GLU_MAP1_TRIM_2")
4336 " and "
4337 (code "GLU_MAP1_TRIM_3")
4338 ". ")))
4339 (heading "Description")
4340 (para "
4341 Use "
4342 (code "gluNurbsCurve")
4343 " to describe a NURBS curve. ")
4344 (para "
4345 When "
4346 (code "gluNurbsCurve")
4347 " appears between a "
4348 (code "gluBeginCurve")
4349 "/"
4350 (code "gluEndCurve")
4351 " pair, it is
4352 used to describe a curve to be rendered.
4353 Positional, texture, and color coordinates are associated
4354 by presenting each as a separate "
4355 (code "gluNurbsCurve")
4356 " between a "
4357 (code "gluBeginCurve")
4358 "/"
4359 (code "gluEndCurve")
4360 " pair. No more than
4361 one call to "
4362 (code "gluNurbsCurve")
4363 " for each of color, position, and texture
4364 data can be made within a single "
4365 (code "gluBeginCurve")
4366 "/"
4367 (code "gluEndCurve")
4368 "
4369 pair. Exactly one call must be made to describe the position of the
4370 curve (a "
4371 (var "type")
4372 " of "
4373 (code "GLU_MAP1_VERTEX_3")
4374 " or "
4375 (code "GLU_MAP1_VERTEX_4")
4376 "). ")
4377 (para "
4378 When "
4379 (code "gluNurbsCurve")
4380 " appears between a "
4381 (code "gluBeginTrim")
4382 "/"
4383 (code "gluEndTrim")
4384 " pair, it is
4385 used to describe a trimming curve on a NURBS surface. If "
4386 (var "type")
4387 " is "
4388 (code "GLU_MAP1_TRIM_2")
4389 ", then it describes a curve in two-dimensional ("
4390 (var "u")
4391 " and "
4392 (var "v")
4393 ")
4394 parameter space. If it is "
4395 (code "GLU_MAP1_TRIM_3")
4396 ", then it describes a
4397 curve in two-dimensional homogeneous ("
4398 (var "u")
4399 ", "
4400 (var "v")
4401 ", and "
4402 (var "w")
4403 ")
4404 parameter space.
4405 See the "
4406 (code "gluBeginTrim")
4407 " reference page for more discussion about trimming
4408 curves. ")))
4409
4410 (define-gl-procedure
4411 gluNurbsProperty
4412 "gluNurbsProperty"
4413 (funcsynopsis
4414 (funcprototype
4415 (funcdef "void " (function "gluNurbsProperty"))
4416 (paramdef "GLUnurbs* " (parameter "nurb"))
4417 (paramdef "GLenum " (parameter "property"))
4418 (paramdef "GLfloat " (parameter "value"))))
4419 '(*fragment*
4420 (heading "set a NURBS property")
4421 (heading "Parameters")
4422 (table (% (formatter (asis)))
4423 (entry (% (heading (var "nurb")))
4424 (para "
4425 Specifies the NURBS object (created with "
4426 (code "gluNewNurbsRenderer")
4427 "). "))
4428 (entry (% (heading (var "property")))
4429 (para "
4430 Specifies the property to be set. Valid values are "
4431 (code "GLU_SAMPLING_TOLERANCE")
4432 ", "
4433 (code "GLU_DISPLAY_MODE")
4434 ", "
4435 (code "GLU_CULLING")
4436 ", "
4437 (code "GLU_AUTO_LOAD_MATRIX")
4438 ", "
4439 (code "GLU_PARAMETRIC_TOLERANCE")
4440 ", "
4441 (code "GLU_SAMPLING_METHOD")
4442 ", "
4443 (code "GLU_U_STEP")
4444 ", "
4445 (code "GLU_V_STEP")
4446 ", or "
4447 (code "GLU_NURBS_MODE")
4448 ". "))
4449 (entry (% (heading (var "value")))
4450 (para "
4451 Specifies the value of the indicated property.
4452 It may be a numeric value or one of "
4453 (code "GLU_OUTLINE_POLYGON")
4454 ", "
4455 (code "GLU_FILL")
4456 ", "
4457 (code "GLU_OUTLINE_PATCH")
4458 ", "
4459 (code "GLU_TRUE")
4460 ", "
4461 (code "GLU_FALSE")
4462 ", "
4463 (code "GLU_PATH_LENGTH")
4464 ", "
4465 (code "GLU_PARAMETRIC_ERROR")
4466 ", "
4467 (code "GLU_DOMAIN_DISTANCE")
4468 ", "
4469 (code "GLU_NURBS_RENDERER")
4470 ", or "
4471 (code "GLU_NURBS_TESSELLATOR")
4472 ". ")))
4473 (heading "Description")
4474 (para (code "gluNurbsProperty")
4475 " is used to control properties stored in a NURBS object. These
4476 properties affect the way that a NURBS curve is rendered. The accepted
4477 values for "
4478 (var "property")
4479 " are as follows: ")
4480 (table (% (formatter (asis)))
4481 (entry (% (heading (code "GLU_NURBS_MODE")))
4482 (para (var "value")
4483 " should be set to be either "
4484 (code "GLU_NURBS_RENDERER")
4485 " or "
4486 (code "GLU_NURBS_TESSELLATOR")
4487 ". When set to "
4488 (code "GLU_NURBS_RENDERER")
4489 ", NURBS objects
4490 are tessellated into OpenGL primitives and sent to the pipeline for
4491 rendering. When set to "
4492 (code "GLU_NURBS_TESSELLATOR")
4493 ", NURBS objects are
4494 tessellated into OpenGL primitives but the vertices, normals, colors, and/or textures are
4495 retrieved back through a callback interface (see "
4496 (code "gluNurbsCallback")
4497 "). This allows the user to cache the
4498 tessellated results for further processing.
4499 The initial value is "
4500 (code "GLU_NURBS_RENDERER")
4501 ". "))
4502 (entry (% (heading (code "GLU_SAMPLING_METHOD")))
4503 (para "
4504 Specifies how a NURBS surface should be
4505 tessellated. "
4506 (var "value")
4507 " may be one of "
4508 (code "GLU_PATH_LENGTH")
4509 ", "
4510 (code "GLU_PARAMETRIC_ERROR")
4511 ", "
4512 (code "GLU_DOMAIN_DISTANCE")
4513 ", "
4514 (code "GLU_OBJECT_PATH_LENGTH")
4515 ", or "
4516 (code "GLU_OBJECT_PARAMETRIC_ERROR")
4517 ".
4518 When set to "
4519 (code "GLU_PATH_LENGTH")
4520 ", the surface is rendered so that
4521 the maximum length, in
4522 pixels, of the edges of the tessellation polygons is no greater than
4523 what is specified by "
4524 (code "GLU_SAMPLING_TOLERANCE")
4525 ". ")
4526 (para (code "GLU_PARAMETRIC_ERROR")
4527 " specifies that the surface is rendered in such a
4528 way that the value specified by "
4529 (code "GLU_PARAMETRIC_TOLERANCE")
4530 " describes the
4531 maximum distance, in pixels, between the tessellation polygons and the
4532 surfaces they approximate. ")
4533 (para (code "GLU_DOMAIN_DISTANCE")
4534 " allows users to specify, in parametric coordinates,
4535 how many sample points per unit length are taken in "
4536 (var "u")
4537 ", "
4538 (var "v")
4539 "
4540 direction. ")
4541 (para (code "GLU_OBJECT_PATH_LENGTH")
4542 " is similar to "
4543 (code "GLU_PATH_LENGTH")
4544 "
4545 except that it is view independent; that is, the surface is rendered so that the maximum length, in object space, of edges of the tessellation polygons is no greater than what is specified by "
4546 (code "GLU_SAMPLING_TOLERANCE")
4547 ". ")
4548 (para (code "GLU_OBJECT_PARAMETRIC_ERROR")
4549 " is similar to "
4550 (code "GLU_PARAMETRIC_ERROR")
4551 " except that it is view independent; that is, the surface is rendered in such a way that the value specified by "
4552 (code "GLU_PARAMETRIC_TOLERANCE")
4553 " describes the maximum distance, in object space, between the tessellation polygons and the surfaces they approximate. ")
4554 (para "
4555 The initial value of "
4556 (code "GLU_SAMPLING_METHOD")
4557 " is "
4558 (code "GLU_PATH_LENGTH")
4559 ". "))
4560 (entry (% (heading (code "GLU_SAMPLING_TOLERANCE")))
4561 (para "
4562 Specifies the maximum length, in pixels or in object space length unit,
4563 to use when the sampling method is set to "
4564 (code "GLU_PATH_LENGTH")
4565 " or "
4566 (code "GLU_OBJECT_PATH_LENGTH")
4567 ".
4568 The NURBS code is conservative when rendering a curve
4569 or surface, so the actual length can be somewhat shorter. The initial
4570 value is 50.0 pixels. "))
4571 (entry (% (heading (code "GLU_PARAMETRIC_TOLERANCE")))
4572 (para "
4573 Specifies the maximum distance, in pixels or in object space length unit,
4574 to use when the sampling method is "
4575 (code "GLU_PARAMETRIC_ERROR")
4576 " or "
4577 (code "GLU_OBJECT_PARAMETRIC_ERROR")
4578 ".
4579 The initial value is 0.5. "))
4580 (entry (% (heading (code "GLU_U_STEP")))
4581 (para "
4582 Specifies the number of sample points per unit length taken
4583 along the "
4584 (var "u")
4585 " axis in parametric coordinates. It is needed when "
4586 (code "GLU_SAMPLING_METHOD")
4587 " is set to "
4588 (code "GLU_DOMAIN_DISTANCE")
4589 ".
4590 The initial value is 100. "))
4591 (entry (% (heading (code "GLU_V_STEP")))
4592 (para "
4593 Specifies the number of sample points per unit length taken
4594 along the "
4595 (var "v")
4596 " axis in parametric coordinate. It is needed when "
4597 (code "GLU_SAMPLING_METHOD")
4598 " is set to "
4599 (code "GLU_DOMAIN_DISTANCE")
4600 ". The initial
4601 value is 100. "))
4602 (entry (% (heading (code "GLU_DISPLAY_MODE")))
4603 (para (var "value")
4604 " can be set to "
4605 (code "GLU_OUTLINE_POLYGON")
4606 ", "
4607 (code "GLU_FILL")
4608 ", or "
4609 (code "GLU_OUTLINE_PATCH")
4610 ".
4611 When "
4612 (code "GLU_NURBS_MODE")
4613 " is set to be "
4614 (code "GLU_NURBS_RENDERER")
4615 ", "
4616 (var "value")
4617 " defines how a NURBS surface should be rendered.
4618 When "
4619 (var "value")
4620 " is set to "
4621 (code "GLU_FILL")
4622 ", the surface is rendered as a
4623 set of polygons. When "
4624 (var "value")
4625 " is set to "
4626 (code "GLU_OUTLINE_POLYGON")
4627 ", the NURBS library draws only the outlines
4628 of the polygons created by tessellation. When "
4629 (var "value")
4630 " is set to "
4631 (code "GLU_OUTLINE_PATCH")
4632 " just the outlines of patches and trim
4633 curves defined by the user are drawn. ")
4634 (para "
4635 When "
4636 (code "GLU_NURBS_MODE")
4637 " is set to be "
4638 (code "GLU_NURBS_TESSELLATOR")
4639 ", "
4640 (var "value")
4641 " defines how a NURBS surface should be tessellated.
4642 When "
4643 (code "GLU_DISPLAY_MODE")
4644 " is set to "
4645 (code "GLU_FILL")
4646 " or "
4647 (code "GLU_OUTLINE_POLYGON")
4648 ",
4649 the NURBS surface is tessellated into OpenGL triangle primitives that can be
4650 retrieved back through callback functions. If "
4651 (code "GLU_DISPLAY_MODE")
4652 " is set to "
4653 (code "GLU_OUTLINE_PATCH")
4654 ", only the outlines of the patches and trim curves are generated as a sequence of line strips that can be retrieved back through callback functions. ")
4655 (para "
4656 The initial value is "
4657 (code "GLU_FILL")
4658 ". "))
4659 (entry (% (heading (code "GLU_CULLING")))
4660 (para (var "value")
4661 " is a boolean value that, when set to "
4662 (code "GLU_TRUE")
4663 ", indicates that
4664 a NURBS curve should be discarded prior to tessellation if its control points
4665 lie outside the current viewport. The initial value is "
4666 (code "GLU_FALSE")
4667 ". "))
4668 (entry (% (heading (code "GLU_AUTO_LOAD_MATRIX")))
4669 (para (var "value")
4670 " is a boolean value. When set to "
4671 (code "GLU_TRUE")
4672 ", the NURBS code
4673 downloads the projection matrix, the modelview matrix, and the
4674 viewport from the GL server to compute sampling and
4675 culling
4676 matrices for each NURBS curve that is rendered. Sampling and culling matrices
4677 are required to determine the tessellation of a NURBS surface into line segments
4678 or polygons and to cull a NURBS surface if it lies outside the viewport. ")
4679 (para "
4680 If this mode is set to "
4681 (code "GLU_FALSE")
4682 ", then the program needs
4683 to provide a projection matrix, a modelview matrix, and a viewport
4684 for the NURBS renderer to use to construct sampling and culling matrices.
4685 This can be done with the "
4686 (code "gluLoadSamplingMatrices")
4687 " function.
4688 This mode is initially set to "
4689 (code "GLU_TRUE")
4690 ".
4691 Changing it from "
4692 (code "GLU_TRUE")
4693 " to "
4694 (code "GLU_FALSE")
4695 " does not affect
4696 the sampling and culling matrices until "
4697 (code "gluLoadSamplingMatrices")
4698 "
4699 is called. ")))))
4700
4701 (define-gl-procedure
4702 gluNurbsSurface
4703 "gluNurbsSurface"
4704 (funcsynopsis
4705 (funcprototype
4706 (funcdef "void " (function "gluNurbsSurface"))
4707 (paramdef "GLUnurbs* " (parameter "nurb"))
4708 (paramdef "GLint " (parameter "sKnotCount"))
4709 (paramdef "GLfloat* " (parameter "sKnots"))
4710 (paramdef "GLint " (parameter "tKnotCount"))
4711 (paramdef "GLfloat* " (parameter "tKnots"))
4712 (paramdef "GLint " (parameter "sStride"))
4713 (paramdef "GLint " (parameter "tStride"))
4714 (paramdef "GLfloat* " (parameter "control"))
4715 (paramdef "GLint " (parameter "sOrder"))
4716 (paramdef "GLint " (parameter "tOrder"))
4717 (paramdef "GLenum " (parameter "type"))))
4718 '(*fragment*
4719 (heading "define the shape of a NURBS surface")
4720 (heading "Parameters")
4721 (table (% (formatter (asis)))
4722 (entry (% (heading (var "nurb")))
4723 (para "
4724 Specifies the NURBS object (created with "
4725 (code "gluNewNurbsRenderer")
4726 "). "))
4727 (entry (% (heading (var "sKnotCount")))
4728 (para "
4729 Specifies the number of knots in the parametric "
4730 (var "u")
4731 " direction. "))
4732 (entry (% (heading (var "sKnots")))
4733 (para "
4734 Specifies an array of "
4735 (var "sKnotCount")
4736 " nondecreasing knot values in the parametric "
4737 (var "u")
4738 " direction. "))
4739 (entry (% (heading (var "tKnotCount")))
4740 (para "
4741 Specifies the number of knots in the parametric "
4742 (var "v")
4743 " direction. "))
4744 (entry (% (heading (var "tKnots")))
4745 (para "
4746 Specifies an array of "
4747 (var "tKnotCount")
4748 " nondecreasing knot values in the parametric "
4749 (var "v")
4750 " direction. "))
4751 (entry (% (heading (var "sStride")))
4752 (para "
4753 Specifies the offset (as a number of single-precision floating-point values)
4754 between successive control points in the parametric "
4755 (var "u")
4756 " direction
4757 in "
4758 (var "control")
4759 ". "))
4760 (entry (% (heading (var "tStride")))
4761 (para "
4762 Specifies the offset (in single-precision floating-point values)
4763 between successive control points in the parametric "
4764 (var "v")
4765 " direction
4766 in "
4767 (var "control")
4768 ". "))
4769 (entry (% (heading (var "control")))
4770 (para "
4771 Specifies an array containing control points for the NURBS surface.
4772 The offsets between successive control points in the parametric "
4773 (var "u")
4774 "
4775 and "
4776 (var "v")
4777 " directions are given by "
4778 (var "sStride")
4779 " and "
4780 (var "tStride")
4781 ". "))
4782 (entry (% (heading (var "sOrder")))
4783 (para "
4784 Specifies the order of the NURBS surface in the parametric "
4785 (var "u")
4786 " direction. The order is one more than the degree, hence
4787 a surface that is cubic in "
4788 (var "u")
4789 " has a "
4790 (var "u")
4791 " order of 4. "))
4792 (entry (% (heading (var "tOrder")))
4793 (para "
4794 Specifies the order of the NURBS surface in the parametric "
4795 (var "v")
4796 " direction. The order is one more than the degree, hence
4797 a surface that is cubic in "
4798 (var "v")
4799 " has a "
4800 (var "v")
4801 " order of 4. "))
4802 (entry (% (heading (var "type")))
4803 (para "
4804 Specifies type of the surface. "
4805 (var "type")
4806 " can be any of the valid
4807 two-dimensional evaluator types (such as "
4808 (code "GLU_MAP2_VERTEX_3")
4809 " or "
4810 (code "GLU_MAP2_COLOR_4")
4811 "). ")))
4812 (heading "Description")
4813 (para "
4814 Use "
4815 (code "gluNurbsSurface")
4816 " within a NURBS (Non-Uniform Rational B-Spline) surface
4817 definition to describe the shape of a NURBS surface (before
4818 any trimming). To mark the beginning of
4819 a NURBS surface definition, use the "
4820 (code "gluBeginSurface")
4821 " command.
4822 To mark the end of a NURBS surface definition, use the "
4823 (code "gluEndSurface")
4824 " command. Call "
4825 (code "gluNurbsSurface")
4826 " within a NURBS
4827 surface definition only. ")
4828 (para "
4829 Positional, texture, and color coordinates are associated
4830 with a surface by presenting each as a separate "
4831 (code "gluNurbsSurface")
4832 " between a "
4833 (code "gluBeginSurface")
4834 "/"
4835 (code "gluEndSurface")
4836 " pair. No more than
4837 one call to "
4838 (code "gluNurbsSurface")
4839 " for each of color, position, and texture
4840 data can be made within a single "
4841 (code "gluBeginSurface")
4842 "/"
4843 (code "gluEndSurface")
4844 "
4845 pair. Exactly one call must be made to describe the position of the
4846 surface (a "
4847 (var "type")
4848 " of "
4849 (code "GLU_MAP2_VERTEX_3")
4850 " or "
4851 (code "GLU_MAP2_VERTEX_4")
4852 "). ")
4853 (para "
4854 A NURBS surface can be trimmed by using the commands "
4855 (code "gluNurbsCurve")
4856 " and "
4857 (code "gluPwlCurve")
4858 " between calls to "
4859 (code "gluBeginTrim")
4860 " and "
4861 (code "gluEndTrim")
4862 ". ")
4863 (para "
4864 Note that a "
4865 (code "gluNurbsSurface")
4866 " with "
4867 (var "sKnotCount")
4868 " knots in the "
4869 (var "u")
4870 " direction
4871 and "
4872 (var "tKnotCount")
4873 " knots in the "
4874 (var "v")
4875 " direction with orders "
4876 (var "sOrder")
4877 " and "
4878 (var "tOrder")
4879 " must have
4880 ("
4881 (var "sKnotCount")
4882 " - "
4883 (var "sOrder")
4884 ") "
4885 (math (var "times"))
4886 "
4887 ("
4888 (var "tKnotCount")
4889 " - "
4890 (var "tOrder")
4891 ") control points. ")))
4892
4893 (define-gl-procedure
4894 gluOrtho2D
4895 "gluOrtho2D"
4896 (funcsynopsis
4897 (funcprototype
4898 (funcdef "void " (function "gluOrtho2D"))
4899 (paramdef "GLdouble " (parameter "left"))
4900 (paramdef "GLdouble " (parameter "right"))
4901 (paramdef "GLdouble " (parameter "bottom"))
4902 (paramdef "GLdouble " (parameter "top"))))
4903 '(*fragment*
4904 (heading
4905 "define a 2D orthographic projection matrix")
4906 (heading "Parameters")
4907 (table (% (formatter (asis)))
4908 (entry (% (heading (var "left")))
4909 (itemx (var "right"))
4910 (para "
4911 Specify the coordinates for the left and right vertical clipping planes. "))
4912 (entry (% (heading (var "bottom")))
4913 (itemx (var "top"))
4914 (para "
4915 Specify the coordinates for the bottom and top horizontal clipping planes. ")))
4916 (heading "Description")
4917 (para (code "gluOrtho2D")
4918 " sets up a two-dimensional orthographic viewing region.
4919 This is equivalent to calling "
4920 (code "glOrtho")
4921 " with "
4922 (math (var "near") "=" "-1")
4923 "
4924 and "
4925 (math (var "far") "=" "1")
4926 ". ")))
4927
4928 (define-gl-procedure
4929 gluPartialDisk
4930 "gluPartialDisk"
4931 (funcsynopsis
4932 (funcprototype
4933 (funcdef "void " (function "gluPartialDisk"))
4934 (paramdef "GLUquadric* " (parameter "quad"))
4935 (paramdef "GLdouble " (parameter "inner"))
4936 (paramdef "GLdouble " (parameter "outer"))
4937 (paramdef "GLint " (parameter "slices"))
4938 (paramdef "GLint " (parameter "loops"))
4939 (paramdef "GLdouble " (parameter "start"))
4940 (paramdef "GLdouble " (parameter "sweep"))))
4941 '(*fragment*
4942 (heading "draw an arc of a disk")
4943 (heading "Parameters")
4944 (table (% (formatter (asis)))
4945 (entry (% (heading (var "quad")))
4946 (para "
4947 Specifies a quadrics object (created with "
4948 (code "gluNewQuadric")
4949 "). "))
4950 (entry (% (heading (var "inner")))
4951 (para "
4952 Specifies the inner radius of the partial disk (can be 0). "))
4953 (entry (% (heading (var "outer")))
4954 (para "
4955 Specifies the outer radius of the partial disk. "))
4956 (entry (% (heading (var "slices")))
4957 (para "
4958 Specifies the number of subdivisions around the "
4959 (var "z")
4960 " axis. "))
4961 (entry (% (heading (var "loops")))
4962 (para "
4963 Specifies the number of concentric rings about the origin into which
4964 the partial disk is subdivided. "))
4965 (entry (% (heading (var "start")))
4966 (para "
4967 Specifies the starting angle, in degrees, of the disk portion. "))
4968 (entry (% (heading (var "sweep")))
4969 (para "
4970 Specifies the sweep angle, in degrees, of the disk portion. ")))
4971 (heading "Description")
4972 (para (code "gluPartialDisk")
4973 " renders a partial disk on the "
4974 (math (var "z") "=" "0")
4975 "
4976 plane. A partial disk is
4977 similar to a full disk, except that only the subset of the disk from "
4978 (var "start")
4979 " through "
4980 (var "start")
4981 " + "
4982 (var "sweep")
4983 " is included (where 0 degrees is along the
4984 +\\f2y\\f axis,
4985 90 degrees along the +"
4986 (var "x")
4987 " axis, 180 degrees along the \\-"
4988 (var "y")
4989 " axis, and
4990 270 degrees along the \\-"
4991 (var "x")
4992 " axis). ")
4993 (para "
4994 The partial disk has a radius of "
4995 (var "outer")
4996 " and contains a concentric circular hole with a radius
4997 of "
4998 (var "inner")
4999 ". If "
5000 (var "inner")
5001 " is 0, then no hole is generated. The partial disk is
5002 subdivided around the "
5003 (var "z")
5004 " axis into slices (like pizza slices) and also
5005 about the "
5006 (var "z")
5007 " axis into rings
5008 (as specified by "
5009 (var "slices")
5010 " and "
5011 (var "loops")
5012 ", respectively). ")
5013 (para "
5014 With respect to orientation, the +"
5015 (var "z")
5016 " side of the partial disk is considered to
5017 be outside (see "
5018 (code "gluQuadricOrientation")
5019 ").
5020 This means that if the
5021 orientation is set to "
5022 (code "GLU_OUTSIDE")
5023 ", then any normals generated
5024 point along the +"
5025 (var "z")
5026 " axis. Otherwise, they point along the \\-"
5027 (var "z")
5028 " axis. ")
5029 (para "
5030 If texturing is turned on (with "
5031 (code "gluQuadricTexture")
5032 "), texture
5033 coordinates are generated
5034 linearly such that where "
5035 (math (var "r") "=" (var "outer"))
5036 ",
5037 the value at ("
5038 (var "r")
5039 ", 0, 0) is
5040 (1.0, 0.5), at (0, "
5041 (var "r")
5042 ", 0) it is (0.5, 1.0), at (\\-"
5043 (var "r")
5044 ", 0, 0)
5045 it is (0.0, 0.5), and
5046 at (0, \\-"
5047 (var "r")
5048 ", 0) it is (0.5, 0.0). ")))
5049
5050 (define-gl-procedure
5051 gluPerspective
5052 "gluPerspective"
5053 (funcsynopsis
5054 (funcprototype
5055 (funcdef "void " (function "gluPerspective"))
5056 (paramdef "GLdouble " (parameter "fovy"))
5057 (paramdef "GLdouble " (parameter "aspect"))
5058 (paramdef "GLdouble " (parameter "zNear"))
5059 (paramdef "GLdouble " (parameter "zFar"))))
5060 '(*fragment*
5061 (heading
5062 "set up a perspective projection matrix")
5063 (heading "Parameters")
5064 (table (% (formatter (asis)))
5065 (entry (% (heading (var "fovy")))
5066 (para "
5067 Specifies the field of view angle, in degrees, in the "
5068 (var "y")
5069 " direction. "))
5070 (entry (% (heading (var "aspect")))
5071 (para "
5072 Specifies the aspect ratio that determines
5073 the field of view in the "
5074 (var "x")
5075 " direction.
5076 The aspect ratio is the ratio of "
5077 (var "x")
5078 " (width) to "
5079 (var "y")
5080 " (height). "))
5081 (entry (% (heading (var "zNear")))
5082 (para "
5083 Specifies the distance from the viewer to the near clipping plane
5084 (always positive). "))
5085 (entry (% (heading (var "zFar")))
5086 (para "
5087 Specifies the distance from the viewer to the far clipping plane
5088 (always positive). ")))
5089 (heading "Description")
5090 (para (code "gluPerspective")
5091 " specifies a viewing frustum into the world coordinate system.
5092 In general, the aspect ratio in "
5093 (code "gluPerspective")
5094 " should match the aspect ratio
5095 of the associated viewport. For example, "
5096 (math (var "aspect") "=" "2.0")
5097 "
5098 means
5099 the viewer's
5100 angle of view is twice as wide in "
5101 (var "x")
5102 " as it is in "
5103 (var "y")
5104 ".
5105 If the viewport is
5106 twice as wide as it is tall, it displays the image without distortion. ")
5107 (para "
5108 The matrix generated by "
5109 (code "gluPerspective")
5110 " is multipled by the current matrix,
5111 just as if "
5112 (code "glMultMatrix")
5113 " were called with the generated matrix.
5114 To load the perspective matrix onto the current matrix stack instead,
5115 precede the call to "
5116 (code "gluPerspective")
5117 " with a call to "
5118 (code "glLoadIdentity")
5119 ". ")
5120 (para "
5121 Given "
5122 (var "f")
5123 " defined as follows: ")
5124 (para (math (var "f")
5125 "="
5126 (var "cotangent")
5127 "\u2061"
5128 "("
5129 (var "fovy")
5130 "/"
5131 "2"
5132 ","
5133 ")")
5134 "
5135 The generated matrix is ")
5136 (para (math "("
5137 "("
5138 (var "f")
5139 "/"
5140 (var "aspect")
5141 " "
5142 "0"
5143 " "
5144 "0"
5145 " "
5146 "0"
5147 ")"
5148 ", "
5149 "("
5150 "0"
5151 " "
5152 (var "f")
5153 " "
5154 "0"
5155 " "
5156 "0"
5157 ")"
5158 ", "
5159 "("
5160 "0"
5161 " "
5162 "0"
5163 " "
5164 (var "zFar")
5165 "+"
5166 (var "zNear")
5167 ","
5168 "/"
5169 (var "zNear")
5170 "-"
5171 (var "zFar")
5172 ","
5173 " "
5174 "2"
5175 "×"
5176 (var "zFar")
5177 "×"
5178 (var "zNear")
5179 ","
5180 "/"
5181 (var "zNear")
5182 "-"
5183 (var "zFar")
5184 ","
5185 ")"
5186 ", "
5187 "("
5188 "0"
5189 " "
5190 "0"
5191 " "
5192 "-1"
5193 " "
5194 "0"
5195 ")"
5196 ","
5197 ")"))))
5198
5199 (define-gl-procedure
5200 gluPickMatrix
5201 "gluPickMatrix"
5202 (funcsynopsis
5203 (funcprototype
5204 (funcdef "void " (function "gluPickMatrix"))
5205 (paramdef "GLdouble " (parameter "x"))
5206 (paramdef "GLdouble " (parameter "y"))
5207 (paramdef "GLdouble " (parameter "delX"))
5208 (paramdef "GLdouble " (parameter "delY"))
5209 (paramdef "GLint * " (parameter "viewport"))))
5210 '(*fragment*
5211 (heading "define a picking region")
5212 (heading "Parameters")
5213 (table (% (formatter (asis)))
5214 (entry (% (heading (var "x")))
5215 (itemx (var "y"))
5216 (para "
5217 Specify the center of a picking region in window coordinates. "))
5218 (entry (% (heading (var "delX")))
5219 (itemx (var "delY"))
5220 (para "
5221 Specify the width and height, respectively, of the picking region in window
5222 coordinates. "))
5223 (entry (% (heading (var "viewport")))
5224 (para "
5225 Specifies the current viewport (as from a "
5226 (code "glGetIntegerv")
5227 " call). ")))
5228 (heading "Description")
5229 (para (code "gluPickMatrix")
5230 " creates a projection matrix that can be used to restrict drawing
5231 to a small region of the viewport.
5232 This is typically useful to
5233 determine what objects are being drawn near the cursor.
5234 Use "
5235 (code "gluPickMatrix")
5236 " to
5237 restrict drawing to a small region around the cursor.
5238 Then,
5239 enter selection mode (with "
5240 (code "glRenderMode")
5241 ") and rerender the scene.
5242 All primitives that would have been drawn near
5243 the cursor are identified and stored in the selection buffer. ")
5244 (para "
5245 The matrix created by "
5246 (code "gluPickMatrix")
5247 " is multiplied by the current matrix just
5248 as if "
5249 (code "glMultMatrix")
5250 " is called with the generated matrix.
5251 To effectively use the generated pick matrix for picking,
5252 first call "
5253 (code "glLoadIdentity")
5254 " to load an identity matrix onto the
5255 perspective matrix stack.
5256 Then call "
5257 (code "gluPickMatrix")
5258 ",
5259 and, finally, call a command (such as "
5260 (code "gluPerspective")
5261 ")
5262 to multiply the perspective matrix by the pick matrix. ")
5263 (para "
5264 When using "
5265 (code "gluPickMatrix")
5266 " to pick NURBS, be careful to turn off the NURBS
5267 property "
5268 (code "GLU_AUTO_LOAD_MATRIX")
5269 ". If "
5270 (code "GLU_AUTO_LOAD_MATRIX")
5271 " is not
5272 turned off, then any NURBS surface rendered is subdivided differently with
5273 the pick matrix than the way it was subdivided without the pick matrix. ")))
5274
5275 (define-gl-procedure
5276 gluProject
5277 "gluProject"
5278 (funcsynopsis
5279 (funcprototype
5280 (funcdef "GLint " (function "gluProject"))
5281 (paramdef "GLdouble " (parameter "objX"))
5282 (paramdef "GLdouble " (parameter "objY"))
5283 (paramdef "GLdouble " (parameter "objZ"))
5284 (paramdef
5285 "const GLdouble * "
5286 (parameter "model"))
5287 (paramdef "const GLdouble * " (parameter "proj"))
5288 (paramdef "const GLint * " (parameter "view"))
5289 (paramdef "GLdouble* " (parameter "winX"))
5290 (paramdef "GLdouble* " (parameter "winY"))
5291 (paramdef "GLdouble* " (parameter "winZ"))))
5292 '(*fragment*
5293 (heading
5294 "map object coordinates to window coordinates")
5295 (heading "Parameters")
5296 (table (% (formatter (asis)))
5297 (entry (% (heading (var "objX")))
5298 (itemx (var "objY"))
5299 (itemx (var "objZ"))
5300 (para "
5301 Specify the object coordinates. "))
5302 (entry (% (heading (var "model")))
5303 (para "
5304 Specifies the current modelview matrix (as from a "
5305 (code "glGetDoublev")
5306 " call). "))
5307 (entry (% (heading (var "proj")))
5308 (para "
5309 Specifies the current projection matrix (as from a "
5310 (code "glGetDoublev")
5311 " call). "))
5312 (entry (% (heading (var "view")))
5313 (para "
5314 Specifies the current viewport (as from a "
5315 (code "glGetIntegerv")
5316 " call). "))
5317 (entry (% (heading (var "winX")))
5318 (itemx (var "winY"))
5319 (itemx (var "winZ"))
5320 (para "
5321 Return the computed window coordinates. ")))
5322 (heading "Description")
5323 (para (code "gluProject")
5324 " transforms the specified object coordinates into window coordinates
5325 using "
5326 (var "model")
5327 ", "
5328 (var "proj")
5329 ", and "
5330 (var "view")
5331 ". The result is stored
5332 in "
5333 (var "winX")
5334 ", "
5335 (var "winY")
5336 ", and "
5337 (var "winZ")
5338 ". A return value of "
5339 (code "GLU_TRUE")
5340 " indicates success, a return value of "
5341 (code "GLU_FALSE")
5342 "
5343 indicates failure. ")
5344 (para "
5345 To compute the coordinates,
5346 let "
5347 (math (var "v")
5348 "="
5349 "("
5350 (var "objX")
5351 ","
5352 (var "objY")
5353 (var "objZ")
5354 "1.0"
5355 ")")
5356 "
5357 represented as a matrix with 4 rows and 1 column.
5358 Then "
5359 (code "gluProject")
5360 " computes "
5361 (math (var "v") "^" "″")
5362 "
5363 as follows: ")
5364 (para (math (var "v")
5365 "^"
5366 "″"
5367 "="
5368 (var "P")
5369 "×"
5370 (var "M")
5371 "×"
5372 (var "v")))
5373 (para "
5374 where "
5375 (math (var "P"))
5376 "
5377 is the current projection matrix "
5378 (var "proj")
5379 " and "
5380 (math (var "M"))
5381 "
5382 is the current
5383 modelview matrix "
5384 (var "model")
5385 " (both represented as "
5386 (math "4" "×" "4")
5387 "
5388 matrices in column-major order). ")
5389 (para "
5390 The window coordinates are then computed as follows: ")
5391 (para (math (var "winX")
5392 "="
5393 (var "view")
5394 "\u2061"
5395 "("
5396 "0"
5397 ","
5398 ")"
5399 "+"
5400 (var "view")
5401 "\u2061"
5402 "("
5403 "2"
5404 ","
5405 ")"
5406 "×"
5407 "("
5408 (var "v")
5409 "^"
5410 "″"
5411 "\u2061"
5412 "("
5413 "0"
5414 ","
5415 ")"
5416 "+"
5417 "1"
5418 ","
5419 ")"
5420 "/"
5421 "2")
5422 (para (math (var "winY")
5423 "="
5424 (var "view")
5425 "\u2061"
5426 "("
5427 "1"
5428 ","
5429 ")"
5430 "+"
5431 (var "view")
5432 "\u2061"
5433 "("
5434 "3"
5435 ","
5436 ")"
5437 "×"
5438 "("
5439 (var "v")
5440 "^"
5441 "″"
5442 "\u2061"
5443 "("
5444 "1"
5445 ","
5446 ")"
5447 "+"
5448 "1"
5449 ","
5450 ")"
5451 "/"
5452 "2"))
5453 (para (math (var "winZ")
5454 "="
5455 "("
5456 (var "v")
5457 "^"
5458 "″"
5459 "\u2061"
5460 "("
5461 "2"
5462 ","
5463 ")"
5464 "+"
5465 "1"
5466 ","
5467 ")"
5468 "/"
5469 "2")))
5470 (para)))
5471
5472 (define-gl-procedure
5473 gluPwlCurve
5474 "gluPwlCurve"
5475 (funcsynopsis
5476 (funcprototype
5477 (funcdef "void " (function "gluPwlCurve"))
5478 (paramdef "GLUnurbs* " (parameter "nurb"))
5479 (paramdef "GLint " (parameter "count"))
5480 (paramdef "GLfloat* " (parameter "data"))
5481 (paramdef "GLint " (parameter "stride"))
5482 (paramdef "GLenum " (parameter "type"))))
5483 '(*fragment*
5484 (heading
5485 "describe a piecewise linear NURBS trimming curve")
5486 (heading "Parameters")
5487 (table (% (formatter (asis)))
5488 (entry (% (heading (var "nurb")))
5489 (para "
5490 Specifies the NURBS object (created with "
5491 (code "gluNewNurbsRenderer")
5492 "). "))
5493 (entry (% (heading (var "count")))
5494 (para "
5495 Specifies the number of points on the curve. "))
5496 (entry (% (heading (var "data")))
5497 (para "
5498 Specifies an array containing the curve points. "))
5499 (entry (% (heading (var "stride")))
5500 (para "
5501 Specifies the offset (a number of single-precision floating-point values)
5502 between points on the curve. "))
5503 (entry (% (heading (var "type")))
5504 (para "
5505 Specifies the type of curve.
5506 Must be either "
5507 (code "GLU_MAP1_TRIM_2")
5508 " or "
5509 (code "GLU_MAP1_TRIM_3")
5510 ". ")))
5511 (heading "Description")
5512 (para (code "gluPwlCurve")
5513 " describes a piecewise linear trimming curve for a NURBS surface.
5514 A piecewise linear curve consists of a list of
5515 coordinates of points in the parameter space for the
5516 NURBS surface to be trimmed. These points are connected
5517 with line segments to form a curve. If the curve is
5518 an approximation to a curve that is not piecewise linear,
5519 the points should be close enough in parameter space that the
5520 resulting path appears curved at the resolution used in the application. ")
5521 (para "
5522 If "
5523 (var "type")
5524 " is "
5525 (code "GLU_MAP1_TRIM_2")
5526 ", then it describes a curve in two-dimensional ("
5527 (var "u")
5528 " and "
5529 (var "v")
5530 ") parameter space. If it is "
5531 (code "GLU_MAP1_TRIM_3")
5532 ", then it
5533 describes a curve in two-dimensional homogeneous ("
5534 (var "u")
5535 ", "
5536 (var "v")
5537 ",
5538 and "
5539 (var "w")
5540 ") parameter space.
5541 See the "
5542 (code "gluBeginTrim")
5543 " reference page for more information
5544 about trimming curves. ")))
5545
5546 (define-gl-procedure
5547 gluQuadricCallback
5548 "gluQuadricCallback"
5549 (funcsynopsis
5550 (funcprototype
5551 (funcdef "void " (function "gluQuadricCallback"))
5552 (paramdef "GLUquadric* " (parameter "quad"))
5553 (paramdef "GLenum " (parameter "which"))
5554 (paramdef
5555 "_GLUfuncptr "
5556 (parameter "CallBackFunc"))))
5557 '(*fragment*
5558 (heading
5559 "define a callback for a quadrics object")
5560 (heading "Parameters")
5561 (table (% (formatter (asis)))
5562 (entry (% (heading (var "quad")))
5563 (para "
5564 Specifies the quadrics object (created with "
5565 (code "gluNewQuadric")
5566 "). "))
5567 (entry (% (heading (var "which")))
5568 (para "
5569 Specifies the callback being defined.
5570 The only valid value is "
5571 (code "GLU_ERROR")
5572 ". "))
5573 (entry (% (heading (var "CallBackFunc")))
5574 (para "
5575 Specifies the function to be called. ")))
5576 (heading "Description")
5577 (para (code "gluQuadricCallback")
5578 " is used to define a new callback to be used by a quadrics object.
5579 If the specified callback is already defined, then it is replaced. If "
5580 (var "CallBackFunc")
5581 " is NULL, then any existing callback is erased. ")
5582 (para "
5583 The one legal callback is "
5584 (code "GLU_ERROR")
5585 ": ")
5586 (table (% (formatter (asis)))
5587 (entry (% (heading (code "GLU_ERROR")))
5588 (para "
5589 The function is called when an error is encountered. Its single argument
5590 is of type GLenum, and it indicates the specific error that occurred.
5591 Character strings describing these errors can be retrieved with the "
5592 (code "gluErrorString")
5593 " call. ")))))
5594
5595 (define-gl-procedure
5596 gluQuadricDrawStyle
5597 "gluQuadricDrawStyle"
5598 (funcsynopsis
5599 (funcprototype
5600 (funcdef
5601 "void "
5602 (function "gluQuadricDrawStyle"))
5603 (paramdef "GLUquadric* " (parameter "quad"))
5604 (paramdef "GLenum " (parameter "draw"))))
5605 '(*fragment*
5606 (heading
5607 "specify the draw style desired for quadrics")
5608 (heading "Parameters")
5609 (table (% (formatter (asis)))
5610 (entry (% (heading (var "quad")))
5611 (para "
5612 Specifies the quadrics object (created with "
5613 (code "gluNewQuadric")
5614 "). "))
5615 (entry (% (heading (var "draw")))
5616 (para "
5617 Specifies the desired draw style. Valid values are "
5618 (code "GLU_FILL")
5619 ", "
5620 (code "GLU_LINE")
5621 ", "
5622 (code "GLU_SILHOUETTE")
5623 ", and "
5624 (code "GLU_POINT")
5625 ". ")))
5626 (heading "Description")
5627 (para (code "gluQuadricDrawStyle")
5628 " specifies the draw style for quadrics rendered with "
5629 (var "quad")
5630 ". The legal values are as follows: ")
5631 (table (% (formatter (asis)))
5632 (entry (% (heading (code "GLU_FILL")))
5633 (para "
5634 Quadrics are rendered with polygon primitives. The polygons
5635 are drawn in a counterclockwise fashion with respect to their
5636 normals (as defined with "
5637 (code "gluQuadricOrientation")
5638 "). "))
5639 (entry (% (heading (code "GLU_LINE")))
5640 (para "
5641 Quadrics are rendered as a set of lines. "))
5642 (entry (% (heading (code "GLU_SILHOUETTE")))
5643 (para "
5644 Quadrics are rendered as a set of lines, except that edges separating
5645 coplanar faces will not be drawn. "))
5646 (entry (% (heading (code "GLU_POINT")))
5647 (para "
5648 Quadrics are rendered as a set of points. ")))))
5649
5650 (define-gl-procedure
5651 gluQuadricNormals
5652 "gluQuadricNormals"
5653 (funcsynopsis
5654 (funcprototype
5655 (funcdef "void " (function "gluQuadricNormals"))
5656 (paramdef "GLUquadric* " (parameter "quad"))
5657 (paramdef "GLenum " (parameter "normal"))))
5658 '(*fragment*
5659 (heading
5660 "specify what kind of normals are desired for quadrics")
5661 (heading "Parameters")
5662 (table (% (formatter (asis)))
5663 (entry (% (heading (var "quad")))
5664 (para "
5665 Specifies the quadrics object (created with "
5666 (code "gluNewQuadric")
5667 "). "))
5668 (entry (% (heading (var "normal")))
5669 (para "
5670 Specifies the desired type of normals. Valid values are "
5671 (code "GLU_NONE")
5672 ", "
5673 (code "GLU_FLAT")
5674 ", and "
5675 (code "GLU_SMOOTH")
5676 ". ")))
5677 (heading "Description")
5678 (para (code "gluQuadricNormals")
5679 " specifies what kind of normals are desired for quadrics rendered with "
5680 (var "quad")
5681 ". The legal values are as follows: ")
5682 (table (% (formatter (asis)))
5683 (entry (% (heading (code "GLU_NONE")))
5684 (para "
5685 No normals are generated. "))
5686 (entry (% (heading (code "GLU_FLAT")))
5687 (para "
5688 One normal is generated for every facet of a quadric. "))
5689 (entry (% (heading (code "GLU_SMOOTH")))
5690 (para "
5691 One normal is generated for every vertex of a quadric. This is the
5692 initial value. ")))))
5693
5694 (define-gl-procedure
5695 gluQuadricOrientation
5696 "gluQuadricOrientation"
5697 (funcsynopsis
5698 (funcprototype
5699 (funcdef
5700 "void "
5701 (function "gluQuadricOrientation"))
5702 (paramdef "GLUquadric* " (parameter "quad"))
5703 (paramdef "GLenum " (parameter "orientation"))))
5704 '(*fragment*
5705 (heading
5706 "specify inside/outside orientation for quadrics")
5707 (heading "Parameters")
5708 (table (% (formatter (asis)))
5709 (entry (% (heading (var "quad")))
5710 (para "
5711 Specifies the quadrics object (created with "
5712 (code "gluNewQuadric")
5713 "). "))
5714 (entry (% (heading (var "orientation")))
5715 (para "
5716 Specifies the desired orientation. Valid values are "
5717 (code "GLU_OUTSIDE")
5718 " and "
5719 (code "GLU_INSIDE")
5720 ". ")))
5721 (heading "Description")
5722 (para (code "gluQuadricOrientation")
5723 " specifies what kind of orientation is desired for quadrics rendered
5724 with "
5725 (var "quad")
5726 ". The "
5727 (var "orientation")
5728 " values are as follows: ")
5729 (table (% (formatter (asis)))
5730 (entry (% (heading (code "GLU_OUTSIDE")))
5731 (para "
5732 Quadrics are drawn with normals pointing outward (the initial value). "))
5733 (entry (% (heading (code "GLU_INSIDE")))
5734 (para "
5735 Quadrics are drawn with normals pointing inward. ")))
5736 (para "
5737 Note that the interpretation of "
5738 (var "outward")
5739 " and "
5740 (var "inward")
5741 " depends on the
5742 quadric being drawn. ")))
5743
5744 (define-gl-procedure
5745 gluQuadricTexture
5746 "gluQuadricTexture"
5747 (funcsynopsis
5748 (funcprototype
5749 (funcdef "void " (function "gluQuadricTexture"))
5750 (paramdef "GLUquadric* " (parameter "quad"))
5751 (paramdef "GLboolean " (parameter "texture"))))
5752 '(*fragment*
5753 (heading
5754 "specify if texturing is desired for quadrics")
5755 (heading "Parameters")
5756 (table (% (formatter (asis)))
5757 (entry (% (heading (var "quad")))
5758 (para "
5759 Specifies the quadrics object (created with "
5760 (code "gluNewQuadric")
5761 "). "))
5762 (entry (% (heading (var "texture")))
5763 (para "
5764 Specifies a flag indicating if texture coordinates should be generated. ")))
5765 (heading "Description")
5766 (para (code "gluQuadricTexture")
5767 " specifies if texture coordinates should be generated
5768 for quadrics rendered with "
5769 (var "quad")
5770 ".
5771 If the value of "
5772 (var "texture")
5773 " is "
5774 (code "GLU_TRUE")
5775 ", then texture coordinates
5776 are generated, and if "
5777 (var "texture")
5778 " is "
5779 (code "GLU_FALSE")
5780 ", they are not. The
5781 initial value is "
5782 (code "GLU_FALSE")
5783 ". ")
5784 (para "
5785 The manner in which texture coordinates are generated depends
5786 upon the specific quadric rendered. ")))
5787
5788 (define-gl-procedure
5789 gluScaleImage
5790 "gluScaleImage"
5791 (funcsynopsis
5792 (funcprototype
5793 (funcdef "GLint " (function "gluScaleImage"))
5794 (paramdef "GLenum " (parameter "format"))
5795 (paramdef "GLsizei " (parameter "wIn"))
5796 (paramdef "GLsizei " (parameter "hIn"))
5797 (paramdef "GLenum " (parameter "typeIn"))
5798 (paramdef "const void * " (parameter "dataIn"))
5799 (paramdef "GLsizei " (parameter "wOut"))
5800 (paramdef "GLsizei " (parameter "hOut"))
5801 (paramdef "GLenum " (parameter "typeOut"))
5802 (paramdef "GLvoid* " (parameter "dataOut"))))
5803 '(*fragment*
5804 (heading "scale an image to an arbitrary size")
5805 (heading "Parameters")
5806 (table (% (formatter (asis)))
5807 (entry (% (heading (var "format")))
5808 (para "
5809 Specifies the format of the pixel data.
5810 The following symbolic values are valid: "
5811 (code "GLU_COLOR_INDEX")
5812 ", "
5813 (code "GLU_STENCIL_INDEX")
5814 ", "
5815 (code "GLU_DEPTH_COMPONENT")
5816 ", "
5817 (code "GLU_RED")
5818 ", "
5819 (code "GLU_GREEN")
5820 ", "
5821 (code "GLU_BLUE")
5822 ", "
5823 (code "GLU_ALPHA")
5824 ", "
5825 (code "GLU_RGB")
5826 ", "
5827 (code "GLU_RGBA")
5828 ", "
5829 (code "GLU_BGR")
5830 ", "
5831 (code "GLU_BGRA")
5832 ", "
5833 (code "GLU_LUMINANCE")
5834 ", and "
5835 (code "GLU_LUMINANCE_ALPHA")
5836 ". "))
5837 (entry (% (heading (var "wIn")))
5838 (itemx (var "hIn"))
5839 (para "
5840 Specify in pixels the width and height, respectively, of the source image. "))
5841 (entry (% (heading (var "typeIn")))
5842 (para "
5843 Specifies the data type for "
5844 (var "dataIn")
5845 ". Must be one of "
5846 (code "GLU_UNSIGNED_BYTE")
5847 ", "
5848 (code "GLU_BYTE")
5849 ", "
5850 (code "GLU_BITMAP")
5851 ", "
5852 (code "GLU_UNSIGNED_SHORT")
5853 ", "
5854 (code "GLU_SHORT")
5855 ", "
5856 (code "GLU_UNSIGNED_INT")
5857 ", "
5858 (code "GLU_INT")
5859 ", "
5860 (code "GLU_FLOAT")
5861 ", "
5862 (code "GLU_UNSIGNED_BYTE_3_3_2")
5863 ", "
5864 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
5865 ", "
5866 (code "GLU_UNSIGNED_SHORT_5_6_5")
5867 ", "
5868 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
5869 ", "
5870 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
5871 ", "
5872 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
5873 ", "
5874 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
5875 ", "
5876 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
5877 ", "
5878 (code "GLU_UNSIGNED_INT_8_8_8_8")
5879 ", "
5880 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
5881 ", "
5882 (code "GLU_UNSIGNED_INT_10_10_10_2")
5883 ", or "
5884 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
5885 ". "))
5886 (entry (% (heading (var "dataIn")))
5887 (para "
5888 Specifies a pointer to the source image. "))
5889 (entry (% (heading (var "wOut")))
5890 (itemx (var "hOut"))
5891 (para "
5892 Specify the width and height, respectively, in pixels of the destination image. "))
5893 (entry (% (heading (var "typeOut")))
5894 (para "
5895 Specifies the data type for "
5896 (var "dataOut")
5897 ". Must be one of "
5898 (code "GLU_UNSIGNED_BYTE")
5899 ", "
5900 (code "GLU_BYTE")
5901 ", "
5902 (code "GLU_BITMAP")
5903 ", "
5904 (code "GLU_UNSIGNED_SHORT")
5905 ", "
5906 (code "GLU_SHORT")
5907 ", "
5908 (code "GLU_UNSIGNED_INT")
5909 ", "
5910 (code "GLU_INT")
5911 ", "
5912 (code "GLU_FLOAT")
5913 ", "
5914 (code "GLU_UNSIGNED_BYTE_3_3_2")
5915 ", "
5916 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
5917 ", "
5918 (code "GLU_UNSIGNED_SHORT_5_6_5")
5919 ", "
5920 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
5921 ", "
5922 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
5923 ", "
5924 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
5925 ", "
5926 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
5927 ", "
5928 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
5929 ", "
5930 (code "GLU_UNSIGNED_INT_8_8_8_8")
5931 ", "
5932 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
5933 ", "
5934 (code "GLU_UNSIGNED_INT_10_10_10_2")
5935 ", or "
5936 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
5937 ". "))
5938 (entry (% (heading (var "dataOut")))
5939 (para "
5940 Specifies a pointer to the destination image. ")))
5941 (heading "Description")
5942 (para (code "gluScaleImage")
5943 " scales a pixel image using the appropriate pixel store modes to
5944 unpack data from the source image and pack data into the destination image. ")
5945 (para "
5946 When shrinking an image, "
5947 (code "gluScaleImage")
5948 " uses a box filter to sample the source image
5949 and create pixels for the destination image. When magnifying an image,
5950 the pixels from the source image are linearly interpolated to create the
5951 destination image. ")
5952 (para "
5953 A return value of zero indicates success, otherwise a GLU error code is returned (see "
5954 (code "gluErrorString")
5955 "). ")
5956 (para "
5957 See the "
5958 (code "glReadPixels")
5959 " reference page for a description of
5960 the acceptable values for the "
5961 (var "format")
5962 ", "
5963 (var "typeIn")
5964 ", and "
5965 (var "typeOut")
5966 " parameters. ")
5967 (heading "Errors")
5968 (para (code "GLU_INVALID_VALUE")
5969 " is returned if "
5970 (var "wIn")
5971 ", "
5972 (var "hIn")
5973 ", "
5974 (var "wOut")
5975 ", or "
5976 (var "hOut")
5977 "
5978 is negative. ")
5979 (para (code "GLU_INVALID_ENUM")
5980 " is returned if "
5981 (var "format")
5982 ", "
5983 (var "typeIn")
5984 ", or "
5985 (var "typeOut")
5986 " is not
5987 legal. ")
5988 (para (code "GLU_INVALID_OPERATION")
5989 " is returned if "
5990 (var "typeIn")
5991 " or "
5992 (var "typeOut")
5993 " is "
5994 (code "GLU_UNSIGNED_BYTE_3_3_2")
5995 " or "
5996 (code "GLU_UNSIGNED_BYTE_2_3_3_REV")
5997 " and "
5998 (var "format")
5999 " is not "
6000 (code "GLU_RGB")
6001 ". ")
6002 (para (code "GLU_INVALID_OPERATION")
6003 " is returned if "
6004 (var "typeIn")
6005 " or "
6006 (var "typeOut")
6007 " is "
6008 (code "GLU_UNSIGNED_SHORT_5_6_5")
6009 " or "
6010 (code "GLU_UNSIGNED_SHORT_5_6_5_REV")
6011 " and "
6012 (var "format")
6013 " is not "
6014 (code "GLU_RGB")
6015 ". ")
6016 (para (code "GLU_INVALID_OPERATION")
6017 " is returned if "
6018 (var "typeIn")
6019 " or "
6020 (var "typeOut")
6021 " is "
6022 (code "GLU_UNSIGNED_SHORT_4_4_4_4")
6023 " or "
6024 (code "GLU_UNSIGNED_SHORT_4_4_4_4_REV")
6025 " and "
6026 (var "format")
6027 " is neither "
6028 (code "GLU_RGBA")
6029 " nor "
6030 (code "GLU_BGRA")
6031 ". ")
6032 (para (code "GLU_INVALID_OPERATION")
6033 " is returned if "
6034 (var "typeIn")
6035 " or "
6036 (var "typeOut")
6037 " is "
6038 (code "GLU_UNSIGNED_SHORT_5_5_5_1")
6039 " or "
6040 (code "GLU_UNSIGNED_SHORT_1_5_5_5_REV")
6041 "
6042 and "
6043 (var "format")
6044 " is neither "
6045 (code "GLU_RGBA")
6046 " nor "
6047 (code "GLU_BGRA")
6048 ". ")
6049 (para (code "GLU_INVALID_OPERATION")
6050 " is returned if "
6051 (var "typeIn")
6052 " or "
6053 (var "typeOut")
6054 " is "
6055 (code "GLU_UNSIGNED_INT_8_8_8_8")
6056 " or "
6057 (code "GLU_UNSIGNED_INT_8_8_8_8_REV")
6058 " and "
6059 (var "format")
6060 " is neither "
6061 (code "GLU_RGBA")
6062 " nor "
6063 (code "GLU_BGRA")
6064 ". ")
6065 (para (code "GLU_INVALID_OPERATION")
6066 " is returned if "
6067 (var "typeIn")
6068 " or "
6069 (var "typeOut")
6070 " is "
6071 (code "GLU_UNSIGNED_INT_10_10_10_2")
6072 " or "
6073 (code "GLU_UNSIGNED_INT_2_10_10_10_REV")
6074 "
6075 and "
6076 (var "format")
6077 " is neither "
6078 (code "GLU_RGBA")
6079 " nor "
6080 (code "GLU_BGRA")
6081 ". ")))
6082
6083 (define-gl-procedure
6084 gluSphere
6085 "gluSphere"
6086 (funcsynopsis
6087 (funcprototype
6088 (funcdef "void " (function "gluSphere"))
6089 (paramdef "GLUquadric* " (parameter "quad"))
6090 (paramdef "GLdouble " (parameter "radius"))
6091 (paramdef "GLint " (parameter "slices"))
6092 (paramdef "GLint " (parameter "stacks"))))
6093 '(*fragment*
6094 (heading "draw a sphere")
6095 (heading "Parameters")
6096 (table (% (formatter (asis)))
6097 (entry (% (heading (var "quad")))
6098 (para "
6099 Specifies the quadrics object (created with "
6100 (code "gluNewQuadric")
6101 "). "))
6102 (entry (% (heading (var "radius")))
6103 (para "
6104 Specifies the radius of the sphere. "))
6105 (entry (% (heading (var "slices")))
6106 (para "
6107 Specifies the number of subdivisions around the "
6108 (var "z")
6109 " axis
6110 (similar to lines of longitude). "))
6111 (entry (% (heading (var "stacks")))
6112 (para "
6113 Specifies the number of subdivisions along the "
6114 (var "z")
6115 " axis
6116 (similar to lines of
6117 latitude). ")))
6118 (heading "Description")
6119 (para (code "gluSphere")
6120 " draws a sphere of the given radius centered around the origin. The
6121 sphere is subdivided around the "
6122 (var "z")
6123 " axis into slices and along the "
6124 (var "z")
6125 " axis
6126 into stacks (similar to lines of longitude and latitude). ")
6127 (para "
6128 If the orientation is set to "
6129 (code "GLU_OUTSIDE")
6130 " (with "
6131 (code "gluQuadricOrientation")
6132 "), then any normals generated
6133 point away from the center of the sphere.
6134 Otherwise, they point toward the center of the sphere. ")
6135 (para "
6136 If texturing is turned on (with "
6137 (code "gluQuadricTexture")
6138 "), then texture
6139 coordinates are
6140 generated so that "
6141 (var "t")
6142 " ranges from 0.0 at "
6143 (math (var "z") "=" "-" (var "radius"))
6144 "
6145 to 1.0 at "
6146 (math (var "z") "=" (var "radius"))
6147 "
6148 ("
6149 (var "t")
6150 " increases linearly along longitudinal
6151 lines),
6152 and "
6153 (var "s")
6154 " ranges from 0.0 at the +"
6155 (var "y")
6156 " axis, to 0.25 at the
6157 +"
6158 (var "x")
6159 " axis,
6160 to 0.5 at the \\-"
6161 (var "y")
6162 " axis, to 0.75 at the \\-"
6163 (var "x")
6164 " axis, and back to 1.0
6165 at the +"
6166 (var "y")
6167 " axis. ")))
6168
6169 (define-gl-procedure
6170 gluTessBeginContour
6171 "gluTessBeginContour"
6172 (funcsynopsis
6173 (funcprototype
6174 (funcdef
6175 "void "
6176 (function "gluTessBeginContour"))
6177 (paramdef "GLUtesselator* " (parameter "tess"))))
6178 '(*fragment*
6179 (heading "delimit a contour description")
6180 (heading "Parameters")
6181 (table (% (formatter (asis)))
6182 (entry (% (heading (var "tess")))
6183 (para "
6184 Specifies the tessellation object (created with "
6185 (code "gluNewTess")
6186 "). ")))
6187 (heading "Description")
6188 (para (code "gluTessBeginContour")
6189 " and "
6190 (code "gluTessEndContour")
6191 " delimit the definition of a
6192 polygon contour. Within each "
6193 (code "gluTessBeginContour")
6194 "/"
6195 (code "gluTessEndContour")
6196 "
6197 pair, there can be zero or more calls to "
6198 (code "gluTessVertex")
6199 ". The vertices
6200 specify a closed contour (the last vertex of each contour is automatically linked
6201 to the first). See the "
6202 (code "gluTessVertex")
6203 " reference page for more details. "
6204 (code "gluTessBeginContour")
6205 " can only be called between "
6206 (code "gluTessBeginPolygon")
6207 " and "
6208 (code "gluTessEndPolygon")
6209 ". ")))
6210
6211 (define-gl-procedure
6212 gluTessBeginPolygon
6213 "gluTessBeginPolygon"
6214 (funcsynopsis
6215 (funcprototype
6216 (funcdef
6217 "void "
6218 (function "gluTessBeginPolygon"))
6219 (paramdef "GLUtesselator* " (parameter "tess"))
6220 (paramdef "GLvoid* " (parameter "data"))))
6221 '(*fragment*
6222 (heading "delimit a polygon description")
6223 (heading "Parameters")
6224 (table (% (formatter (asis)))
6225 (entry (% (heading (var "tess")))
6226 (para "
6227 Specifies the tessellation object (created with "
6228 (code "gluNewTess")
6229 "). "))
6230 (entry (% (heading (var "data")))
6231 (para "
6232 Specifies a pointer to user polygon data. ")))
6233 (heading "Description")
6234 (para (code "gluTessBeginPolygon")
6235 " and "
6236 (code "gluTessEndPolygon")
6237 " delimit the definition of a
6238 convex, concave or self-intersecting polygon. Within each "
6239 (code "gluTessBeginPolygon")
6240 "/"
6241 (code "gluTessEndPolygon")
6242 "
6243 pair, there must be one or more calls to "
6244 (code "gluTessBeginContour")
6245 "/"
6246 (code "gluTessEndContour")
6247 ".
6248 Within each contour, there are zero or more calls to "
6249 (code "gluTessVertex")
6250 ". The vertices
6251 specify a closed contour (the last vertex of each contour is automatically linked
6252 to the first). See the "
6253 (code "gluTessVertex")
6254 ", "
6255 (code "gluTessBeginContour")
6256 ", and "
6257 (code "gluTessEndContour")
6258 " reference pages for more details. ")
6259 (para (var "data")
6260 " is a pointer to a user-defined data structure. If the appropriate callback(s)
6261 are specified (see "
6262 (code "gluTessCallback")
6263 "), then this pointer is returned to the
6264 callback function(s). Thus, it is a convenient way to store per-polygon information. ")
6265 (para "
6266 Once "
6267 (code "gluTessEndPolygon")
6268 " is called, the polygon is tessellated, and the
6269 resulting triangles are described through callbacks.
6270 See "
6271 (code "gluTessCallback")
6272 " for descriptions of the callback functions. ")))
6273
6274 (define-gl-procedure
6275 gluTessCallback
6276 "gluTessCallback"
6277 (funcsynopsis
6278 (funcprototype
6279 (funcdef "void " (function "gluTessCallback"))
6280 (paramdef "GLUtesselator* " (parameter "tess"))
6281 (paramdef "GLenum " (parameter "which"))
6282 (paramdef
6283 "_GLUfuncptr "
6284 (parameter "CallBackFunc"))))
6285 '(*fragment*
6286 (heading
6287 "define a callback for a tessellation object")
6288 (heading "Parameters")
6289 (table (% (formatter (asis)))
6290 (entry (% (heading (var "tess")))
6291 (para "
6292 Specifies the tessellation object (created with "
6293 (code "gluNewTess")
6294 "). "))
6295 (entry (% (heading (var "which")))
6296 (para "
6297 Specifies the callback being defined. The following values are valid: "
6298 (code "GLU_TESS_BEGIN")
6299 ", "
6300 (code "GLU_TESS_BEGIN_DATA")
6301 ", "
6302 (code "GLU_TESS_EDGE_FLAG")
6303 ", "
6304 (code "GLU_TESS_EDGE_FLAG_DATA")
6305 ", "
6306 (code "GLU_TESS_VERTEX")
6307 ", "
6308 (code "GLU_TESS_VERTEX_DATA")
6309 ", "
6310 (code "GLU_TESS_END")
6311 ", "
6312 (code "GLU_TESS_END_DATA")
6313 ", "
6314 (code "GLU_TESS_COMBINE")
6315 ", "
6316 (code "GLU_TESS_COMBINE_DATA")
6317 ", "
6318 (code "GLU_TESS_ERROR")
6319 ", and "
6320 (code "GLU_TESS_ERROR_DATA")
6321 ". "))
6322 (entry (% (heading (var "CallBackFunc")))
6323 (para "
6324 Specifies the function to be called. ")))
6325 (heading "Description")
6326 (para (code "gluTessCallback")
6327 " is used to indicate a callback to be used by a tessellation object.
6328 If the specified callback is already defined, then it is replaced. If "
6329 (var "CallBackFunc")
6330 " is NULL, then the existing callback becomes undefined. ")
6331 (para "
6332 These callbacks are used by the tessellation object to describe how a
6333 polygon specified by the user is broken into triangles. Note that there
6334 are two versions of each callback: one with user-specified polygon data
6335 and one without. If both versions of a particular callback are specified,
6336 then the callback with user-specified polygon data will be used. Note
6337 that the "
6338 (var "polygon_data")
6339 " parameter used by some of the functions is
6340 a copy of the pointer that was specified when "
6341 (code "gluTessBeginPolygon")
6342 " was called. The legal callbacks are as follows: ")
6343 (table (% (formatter (asis)))
6344 (entry (% (heading (code "GLU_TESS_BEGIN")))
6345 (para "
6346 The begin callback is invoked like "
6347 (code "glBegin")
6348 " to indicate the start of
6349 a (triangle) primitive. The function takes a single argument of type
6350 GLenum. If the "
6351 (code "GLU_TESS_BOUNDARY_ONLY")
6352 " property is set to "
6353 (code "GLU_FALSE")
6354 ", then the argument is set to either "
6355 (code "GLU_TRIANGLE_FAN")
6356 ", "
6357 (code "GLU_TRIANGLE_STRIP")
6358 ", or "
6359 (code "GLU_TRIANGLES")
6360 ".
6361 If the "
6362 (code "GLU_TESS_BOUNDARY_ONLY")
6363 " property is set to "
6364 (code "GLU_TRUE")
6365 ",
6366 then the argument will be set to "
6367 (code "GLU_LINE_LOOP")
6368 ". The function
6369 prototype for this callback is: "))
6370 (entry (% (heading (code "GLU_TESS_BEGIN_DATA")))
6371 (para "
6372 The same as the "
6373 (code "GLU_TESS_BEGIN")
6374 " callback except that it
6375 takes an additional pointer argument. This pointer is identical to the
6376 opaque pointer provided when "
6377 (code "gluTessBeginPolygon")
6378 " was called. The function prototype for this callback
6379 is: "))
6380 (entry (% (heading (code "GLU_TESS_EDGE_FLAG")))
6381 (para "
6382 The edge flag callback is similar to "
6383 (code "glEdgeFlag")
6384 ". The function
6385 takes a single boolean flag that indicates which edges lie on the
6386 polygon boundary. If the flag is "
6387 (code "GLU_TRUE")
6388 ", then each vertex
6389 that follows begins an edge that lies on the polygon boundary, that is,
6390 an edge that separates an interior region from an exterior one.
6391 If the flag is "
6392 (code "GLU_FALSE")
6393 ", then each vertex that follows begins an edge
6394 that lies in the polygon interior. The edge flag callback (if defined) is
6395 invoked before the first vertex callback. ")
6396 (para "
6397 Since triangle fans and triangle strips do not support edge flags, the begin
6398 callback is not called with "
6399 (code "GLU_TRIANGLE_FAN")
6400 " or "
6401 (code "GLU_TRIANGLE_STRIP")
6402 "
6403 if a non-NULL edge flag callback is provided. (If the callback is
6404 initialized to NULL, there is no impact on performance). Instead, the fans and
6405 strips are converted to independent triangles. The function prototype
6406 for this callback is: "))
6407 (entry (% (heading (code "GLU_TESS_EDGE_FLAG_DATA")))
6408 (para "
6409 The same as the "
6410 (code "GLU_TESS_EDGE_FLAG")
6411 " callback except that it takes an additional pointer
6412 argument. This pointer is identical to the opaque pointer provided when "
6413 (code "gluTessBeginPolygon")
6414 " was called. The function prototype for this callback
6415 is: "))
6416 (entry (% (heading (code "GLU_TESS_VERTEX")))
6417 (para "
6418 The vertex callback is invoked between the begin and end callbacks.
6419 It is similar to "
6420 (code "glVertex")
6421 ", and it defines the vertices of the triangles
6422 created by the tessellation process. The function
6423 takes a pointer as its only argument. This pointer is identical to
6424 the opaque pointer provided by the user when the vertex was described
6425 (see "
6426 (code "gluTessVertex")
6427 "). The function prototype for this callback is: "))
6428 (entry (% (heading (code "GLU_TESS_VERTEX_DATA")))
6429 (para "
6430 The same as the "
6431 (code "GLU_TESS_VERTEX")
6432 " callback except that it takes an additional pointer
6433 argument. This pointer is identical to the opaque pointer provided when "
6434 (code "gluTessBeginPolygon")
6435 " was called. The function prototype for this callback
6436 is: "))
6437 (entry (% (heading (code "GLU_TESS_END")))
6438 (para "
6439 The end callback serves the same purpose as "
6440 (code "glEnd")
6441 ". It indicates the
6442 end of a primitive and it takes no arguments. The function prototype for this
6443 callback is: "))
6444 (entry (% (heading (code "GLU_TESS_END_DATA")))
6445 (para "
6446 The same as the "
6447 (code "GLU_TESS_END")
6448 " callback except that it takes an additional pointer
6449 argument. This pointer is identical to the opaque pointer provided when "
6450 (code "gluTessBeginPolygon")
6451 " was called. The function prototype for this callback
6452 is: "))
6453 (entry (% (heading (code "GLU_TESS_COMBINE")))
6454 (para "
6455 The combine callback is called to create a new vertex when the tessellation
6456 detects an intersection or wishes to merge features. The function takes
6457 four arguments: an array of three elements each of type GLdouble, an array
6458 of four pointers, an array of four elements each of type GLfloat, and a
6459 pointer to a pointer. The prototype is: ")
6460 (para "
6461 The vertex is defined as a linear combination of up to four existing vertices,
6462 stored in "
6463 (var "vertex_data")
6464 ". The coefficients of the linear
6465 combination are given by "
6466 (var "weight")
6467 "; these weights always add up to 1.
6468 All vertex pointers are valid even when some of the weights are 0. "
6469 (var "coords")
6470 " gives the location of the new vertex. ")
6471 (para "
6472 The user must allocate another vertex, interpolate parameters using "
6473 (var "vertex_data")
6474 " and "
6475 (var "weight")
6476 ", and return the new vertex pointer in "
6477 (var "outData")
6478 ". This handle is supplied during rendering callbacks.
6479 The user is responsible for freeing the memory some time after "
6480 (code "gluTessEndPolygon")
6481 " is called. ")
6482 (para "
6483 For example, if the polygon lies in an arbitrary plane in 3-space,
6484 and a color is associated with each vertex, the "
6485 (code "GLU_TESS_COMBINE")
6486 " callback might look like this: ")
6487 (para "
6488 If the tessellation detects an intersection, then the "
6489 (code "GLU_TESS_COMBINE")
6490 " or "
6491 (code "GLU_TESS_COMBINE_DATA")
6492 " callback (see below) must be defined, and it must
6493 write a non-NULL pointer into "
6494 (var "dataOut")
6495 ". Otherwise the "
6496 (code "GLU_TESS_NEED_COMBINE_CALLBACK")
6497 " error occurs, and no
6498 output is generated. "))
6499 (entry (% (heading (code "GLU_TESS_COMBINE_DATA")))
6500 (para "
6501 The same as the "
6502 (code "GLU_TESS_COMBINE")
6503 " callback except that it takes an additional pointer
6504 argument. This pointer is identical to the opaque pointer provided when "
6505 (code "gluTessBeginPolygon")
6506 " was called. The function prototype for this callback
6507 is: "))
6508 (entry (% (heading (code "GLU_TESS_ERROR")))
6509 (para "
6510 The error callback is called when an error is encountered. The one argument
6511 is of type GLenum; it indicates the specific error that occurred and will be
6512 set to one of "
6513 (code "GLU_TESS_MISSING_BEGIN_POLYGON")
6514 ", "
6515 (code "GLU_TESS_MISSING_END_POLYGON")
6516 ", "
6517 (code "GLU_TESS_MISSING_BEGIN_CONTOUR")
6518 ", "
6519 (code "GLU_TESS_MISSING_END_CONTOUR")
6520 ", "
6521 (code "GLU_TESS_COORD_TOO_LARGE")
6522 ", "
6523 (code "GLU_TESS_NEED_COMBINE_CALLBACK")
6524 ", or "
6525 (code "GLU_OUT_OF_MEMORY")
6526 ". Character
6527 strings describing these errors can be retrieved with the "
6528 (code "gluErrorString")
6529 " call. The function prototype for this callback is: ")
6530 (para "
6531 The GLU library will recover from the first four
6532 errors by inserting the missing call(s). "
6533 (code "GLU_TESS_COORD_TOO_LARGE")
6534 " indicates that some vertex coordinate exceeded
6535 the predefined constant "
6536 (code "GLU_TESS_MAX_COORD")
6537 " in absolute value, and
6538 that the value has been clamped. (Coordinate values must be small
6539 enough so that two can be multiplied together without overflow.) "
6540 (code "GLU_TESS_NEED_COMBINE_CALLBACK")
6541 " indicates that the tessellation
6542 detected an intersection between two edges in the input data, and the "
6543 (code "GLU_TESS_COMBINE")
6544 " or "
6545 (code "GLU_TESS_COMBINE_DATA")
6546 " callback was
6547 not provided. No output is generated. "
6548 (code "GLU_OUT_OF_MEMORY")
6549 " indicates
6550 that there is not enough memory so no output is generated. "))
6551 (entry (% (heading (code "GLU_TESS_ERROR_DATA")))
6552 (para "
6553 The same as the "
6554 (code "GLU_TESS_ERROR")
6555 " callback except that it takes an additional pointer
6556 argument. This pointer is identical to the opaque pointer provided when "
6557 (code "gluTessBeginPolygon")
6558 " was called. The function prototype for this callback
6559 is: ")))
6560 (example "
6561 void begin( GLenum type ); ")
6562 (example
6563 "
6564 void beginData( GLenum type, void *polygon_data ); ")
6565 (example "
6566 void edgeFlag( GLboolean flag ); ")
6567 (example
6568 "
6569 void edgeFlagData( GLboolean flag, void *polygon_data ); ")
6570 (example "
6571 void vertex( void *vertex_data ); ")
6572 (example
6573 "
6574 void vertexData( void *vertex_data, void *polygon_data ); ")
6575 (example "
6576 void end( void ); ")
6577 (example "
6578 void endData( void *polygon_data ); ")
6579 (example
6580 "
6581 void combine( GLdouble coords[3], void *vertex_data[4],
6582 GLfloat weight[4], void **outData ); ")
6583 (example
6584 "
6585 void myCombine( GLdouble coords[3], VERTEX *d[4],
6586 GLfloat w[4], VERTEX **dataOut )
6587 {
6588 VERTEX *new = new_vertex();
6589
6590 new->x = coords[0];
6591 new->y = coords[1];
6592 new->z = coords[2];
6593 new->r = w[0]*d[0]->r + w[1]*d[1]->r + w[2]*d[2]->r + w[3]*d[3]->r;
6594 new->g = w[0]*d[0]->g + w[1]*d[1]->g + w[2]*d[2]->g + w[3]*d[3]->g;
6595 new->b = w[0]*d[0]->b + w[1]*d[1]->b + w[2]*d[2]->b + w[3]*d[3]->b;
6596 new->a = w[0]*d[0]->a + w[1]*d[1]->a + w[2]*d[2]->a + w[3]*d[3]->a;
6597 *dataOut = new;
6598 } ")
6599 (example
6600 "
6601 void combineData( GLdouble coords[3], void *vertex_data[4],
6602 GLfloat weight[4], void **outData,
6603 void *polygon_data ); ")
6604 (example "
6605 void error( GLenum errno ); ")
6606 (example
6607 "
6608 void errorData( GLenum errno, void *polygon_data ); ")))
6609
6610 (define-gl-procedure
6611 gluTessEndPolygon
6612 "gluTessEndPolygon"
6613 (funcsynopsis
6614 (funcprototype
6615 (funcdef "void " (function "gluTessEndPolygon"))
6616 (paramdef "GLUtesselator* " (parameter "tess"))))
6617 '(*fragment*
6618 (heading "delimit a polygon description")
6619 (heading "Parameters")
6620 (table (% (formatter (asis)))
6621 (entry (% (heading (var "tess")))
6622 (para "
6623 Specifies the tessellation object (created with "
6624 (code "gluNewTess")
6625 "). ")))
6626 (heading "Description")
6627 (para (code "gluTessBeginPolygon")
6628 " and "
6629 (code "gluTessEndPolygon")
6630 " delimit the
6631 definition of a convex, concave, or self-intersecting polygon. Within
6632 each "
6633 (code "gluTessBeginPolygon")
6634 "/"
6635 (code "gluTessEndPolygon")
6636 " pair, there must be
6637 one or more calls to "
6638 (code "gluTessBeginContour")
6639 "/"
6640 (code "gluTessEndContour")
6641 ".
6642 Within each contour, there are zero or more calls to "
6643 (code "gluTessVertex")
6644 ".
6645 The vertices specify a closed contour (the last vertex of each contour
6646 is automatically linked to the first). See the "
6647 (code "gluTessVertex")
6648 ", "
6649 (code "gluTessBeginContour")
6650 ", and "
6651 (code "gluTessEndContour")
6652 " reference pages for
6653 more details. ")
6654 (para "
6655 Once "
6656 (code "gluTessEndPolygon")
6657 " is called, the polygon is tessellated, and the
6658 resulting triangles are described through callbacks.
6659 See "
6660 (code "gluTessCallback")
6661 " for descriptions of the callback functions. ")))
6662
6663 (define-gl-procedure
6664 gluTessNormal
6665 "gluTessNormal"
6666 (funcsynopsis
6667 (funcprototype
6668 (funcdef "void " (function "gluTessNormal"))
6669 (paramdef "GLUtesselator* " (parameter "tess"))
6670 (paramdef "GLdouble " (parameter "valueX"))
6671 (paramdef "GLdouble " (parameter "valueY"))
6672 (paramdef "GLdouble " (parameter "valueZ"))))
6673 '(*fragment*
6674 (heading "specify a normal for a polygon")
6675 (heading "Parameters")
6676 (table (% (formatter (asis)))
6677 (entry (% (heading (var "tess")))
6678 (para "
6679 Specifies the tessellation object (created with "
6680 (code "gluNewTess")
6681 "). "))
6682 (entry (% (heading (var "valueX")))
6683 (para "
6684 Specifies the first component of the normal. "))
6685 (entry (% (heading (var "valueY")))
6686 (para "
6687 Specifies the second component of the normal. "))
6688 (entry (% (heading (var "valueZ")))
6689 (para "
6690 Specifies the third component of the normal. ")))
6691 (heading "Description")
6692 (para (code "gluTessNormal")
6693 " describes a normal for a polygon that the program is defining.
6694 All input data will be projected onto a plane perpendicular to one of
6695 the three coordinate axes before tessellation and all output triangles
6696 will be oriented CCW with
6697 respect to the normal (CW orientation can be obtained by reversing the
6698 sign of the supplied normal). For example, if you know that all polygons
6699 lie in the x-y plane, call "
6700 (code "gluTessNormal")
6701 "(tess, 0.0, 0.0, 1.0)
6702 before rendering any polygons. ")
6703 (para "
6704 If the supplied normal is (0.0, 0.0, 0.0) (the initial value), the normal is
6705 determined as follows. The direction of the normal, up to its sign, is
6706 found by fitting a plane to the vertices, without regard to how the
6707 vertices are connected. It is expected that the input data lies approximately
6708 in the plane; otherwise, projection perpendicular to one of the three
6709 coordinate axes may substantially change the geometry. The sign of the
6710 normal is chosen so that the sum of the signed areas of all input
6711 contours is nonnegative (where a CCW contour has positive area). ")
6712 (para "
6713 The supplied normal persists until it is changed by another call to "
6714 (code "gluTessNormal")
6715 ". ")))
6716
6717 (define-gl-procedure
6718 gluTessProperty
6719 "gluTessProperty"
6720 (funcsynopsis
6721 (funcprototype
6722 (funcdef "void " (function "gluTessProperty"))
6723 (paramdef "GLUtesselator* " (parameter "tess"))
6724 (paramdef "GLenum " (parameter "which"))
6725 (paramdef "GLdouble " (parameter "data"))))
6726 '(*fragment*
6727 (heading "set a tessellation object property")
6728 (heading "Parameters")
6729 (table (% (formatter (asis)))
6730 (entry (% (heading (var "tess")))
6731 (para "
6732 Specifies the tessellation object (created with "
6733 (code "gluNewTess")
6734 "). "))
6735 (entry (% (heading (var "which")))
6736 (para "
6737 Specifies the property to be set. Valid values are "
6738 (code "GLU_TESS_WINDING_RULE")
6739 ", "
6740 (code "GLU_TESS_BOUNDARY_ONLY")
6741 ", and "
6742 (code "GLU_TESS_TOLERANCE")
6743 ". "))
6744 (entry (% (heading (var "data")))
6745 (para "
6746 Specifies the value of the indicated property. ")))
6747 (heading "Description")
6748 (para (code "gluTessProperty")
6749 " is used to control properties stored in a tessellation object. These
6750 properties affect the way that the polygons are interpreted and rendered.
6751 The legal values for "
6752 (var "which")
6753 " are as follows: ")
6754 (table (% (formatter (asis)))
6755 (entry (% (heading (code "GLU_TESS_WINDING_RULE")))
6756 (para "
6757 Determines which parts of the polygon are on the ``interior''. "
6758 (var "data")
6759 " may be set to one of "
6760 (code "GLU_TESS_WINDING_ODD")
6761 ", "
6762 (code "GLU_TESS_WINDING_NONZERO")
6763 ", "
6764 (code "GLU_TESS_WINDING_POSITIVE")
6765 ", "
6766 (code "GLU_TESS_WINDING_NEGATIVE")
6767 ", or "
6768 (code "GLU_TESS_WINDING_ABS_GEQ_TWO")
6769 ". ")
6770 (para "
6771 To understand how the winding rule works, consider that the input
6772 contours partition the plane into regions. The winding rule determines which
6773 of these regions are inside the polygon. ")
6774 (para "
6775 For a single contour C, the winding number of a point x is simply the signed
6776 number of revolutions we make around x as we travel once around C
6777 (where CCW is positive). When there are several contours, the individual
6778 winding numbers are summed. This procedure associates a signed integer
6779 value with each point x in the plane. Note that the winding number is the
6780 same for all points in a single region. ")
6781 (para "
6782 The winding rule classifies a region as ``inside'' if its winding number
6783 belongs to the chosen category (odd, nonzero, positive, negative, or
6784 absolute value of at least two). The previous GLU tessellator (prior to
6785 GLU 1.2) used the ``odd'' rule. The ``nonzero'' rule is another common way to
6786 define the interior. The other three rules are useful for polygon CSG
6787 operations. "))
6788 (entry (% (heading (code "GLU_TESS_BOUNDARY_ONLY")))
6789 (para "
6790 Is a boolean value (``value'' should be set
6791 to GL_TRUE or GL_FALSE). When set to GL_TRUE, a set of closed contours
6792 separating the polygon interior and exterior are returned instead of a
6793 tessellation. Exterior contours are oriented CCW with respect to the
6794 normal; interior contours are oriented CW. The "
6795 (code "GLU_TESS_BEGIN")
6796 "
6797 and "
6798 (code "GLU_TESS_BEGIN_DATA")
6799 " callbacks use the type GL_LINE_LOOP for
6800 each contour. "))
6801 (entry (% (heading (code "GLU_TESS_TOLERANCE")))
6802 (para "
6803 Specifies a tolerance for merging features to reduce the size of the output.
6804 For example, two vertices that are very close to each other might be
6805 replaced by a single vertex. The tolerance is multiplied by the largest
6806 coordinate magnitude of any input vertex; this specifies the maximum
6807 distance that any feature can move as the result of a single merge
6808 operation. If a single feature takes part in several merge operations, the
6809 total distance moved could be larger. ")
6810 (para "
6811 Feature merging is completely optional; the tolerance is only a hint.
6812 The implementation is free to merge in some cases and not in others, or to
6813 never merge features at all. The initial tolerance is 0. ")
6814 (para "
6815 The current implementation merges vertices only if they are exactly
6816 coincident, regardless of the current tolerance. A vertex is spliced into
6817 an edge only if the implementation is unable to distinguish which side of
6818 the edge the vertex lies on. Two edges are merged only when both endpoints
6819 are identical. ")))))
6820
6821 (define-gl-procedure
6822 gluTessVertex
6823 "gluTessVertex"
6824 (funcsynopsis
6825 (funcprototype
6826 (funcdef "void " (function "gluTessVertex"))
6827 (paramdef "GLUtesselator* " (parameter "tess"))
6828 (paramdef "GLdouble * " (parameter "location"))
6829 (paramdef "GLvoid* " (parameter "data"))))
6830 '(*fragment*
6831 (heading "specify a vertex on a polygon")
6832 (heading "Parameters")
6833 (table (% (formatter (asis)))
6834 (entry (% (heading (var "tess")))
6835 (para "
6836 Specifies the tessellation object (created with "
6837 (code "gluNewTess")
6838 "). "))
6839 (entry (% (heading (var "location")))
6840 (para "
6841 Specifies the location of the vertex. "))
6842 (entry (% (heading (var "data")))
6843 (para "
6844 Specifies an opaque pointer passed back to the program with the vertex callback
6845 (as specified by "
6846 (code "gluTessCallback")
6847 "). ")))
6848 (heading "Description")
6849 (para (code "gluTessVertex")
6850 " describes a vertex on a polygon that the program defines. Successive "
6851 (code "gluTessVertex")
6852 " calls describe a closed contour. For example,
6853 to describe a quadrilateral, "
6854 (code "gluTessVertex")
6855 " should be called four times. "
6856 (code "gluTessVertex")
6857 " can only be called between "
6858 (code "gluTessBeginContour")
6859 " and "
6860 (code "gluTessEndContour")
6861 ". ")
6862 (para (var "data")
6863 " normally points to a structure containing the vertex
6864 location, as well as other per-vertex attributes such as color and normal.
6865 This pointer is passed back to the user through the "
6866 (code "GLU_TESS_VERTEX")
6867 "
6868 or "
6869 (code "GLU_TESS_VERTEX_DATA")
6870 " callback after tessellation
6871 (see the "
6872 (code "gluTessCallback")
6873 " reference page). ")))
6874
6875 (define-gl-procedure
6876 gluUnProject4
6877 "gluUnProject4"
6878 (funcsynopsis
6879 (funcprototype
6880 (funcdef "GLint " (function "gluUnProject4"))
6881 (paramdef "GLdouble " (parameter "winX"))
6882 (paramdef "GLdouble " (parameter "winY"))
6883 (paramdef "GLdouble " (parameter "winZ"))
6884 (paramdef "GLdouble " (parameter "clipW"))
6885 (paramdef
6886 "const GLdouble * "
6887 (parameter "model"))
6888 (paramdef "const GLdouble * " (parameter "proj"))
6889 (paramdef "const GLint * " (parameter "view"))
6890 (paramdef "GLdouble " (parameter "nearVal"))
6891 (paramdef "GLdouble " (parameter "farVal"))
6892 (paramdef "GLdouble* " (parameter "objX"))
6893 (paramdef "GLdouble* " (parameter "objY"))
6894 (paramdef "GLdouble* " (parameter "objZ"))
6895 (paramdef "GLdouble* " (parameter "objW"))))
6896 '(*fragment*
6897 (heading
6898 "map window and clip coordinates to object coordinates")
6899 (heading "Parameters")
6900 (table (% (formatter (asis)))
6901 (entry (% (heading (var "winX")))
6902 (itemx (var "winY"))
6903 (itemx (var "winZ"))
6904 (para "
6905 Specify the window coordinates to be mapped. "))
6906 (entry (% (heading (var "clipW")))
6907 (para "
6908 Specify the clip w coordinate to be mapped. "))
6909 (entry (% (heading (var "model")))
6910 (para "
6911 Specifies the modelview matrix (as from a "
6912 (code "glGetDoublev")
6913 " call). "))
6914 (entry (% (heading (var "proj")))
6915 (para "
6916 Specifies the projection matrix (as from a "
6917 (code "glGetDoublev")
6918 " call). "))
6919 (entry (% (heading (var "view")))
6920 (para "
6921 Specifies the viewport (as from a "
6922 (code "glGetIntegerv")
6923 " call). "))
6924 (entry (% (heading (var "nearVal")))
6925 (itemx (var "farVal"))
6926 (para "
6927 Specifies the near and far planes (as from a "
6928 (code "glGetDoublev")
6929 " call). "))
6930 (entry (% (heading (var "objX")))
6931 (itemx (var "objY"))
6932 (itemx (var "objZ"))
6933 (itemx (var "objW"))
6934 (para "
6935 Returns the computed object coordinates. ")))
6936 (heading "Description")
6937 (para (code "gluUnProject4")
6938 " maps the specified window coordinatesi: "
6939 (var "winX")
6940 ", "
6941 (var "winY")
6942 ", and "
6943 (var "winZ")
6944 "
6945 and its clip w coordinate "
6946 (var "clipW")
6947 "
6948 into object
6949 coordinates "
6950 (math "("
6951 (var "objX")
6952 ","
6953 (var "objY")
6954 (var "objZ")
6955 (var "objW")
6956 ")")
6957 "
6958 using "
6959 (var "model")
6960 ", "
6961 (var "proj")
6962 ", and "
6963 (var "view")
6964 ". "
6965 (var "clipW")
6966 " can be other than
6967 1 as for vertices in "
6968 (code "glFeedbackBuffer")
6969 " when data type "
6970 (code "GLU_4D_COLOR_TEXTURE")
6971 " is returned.
6972 This also handles the case
6973 where the "
6974 (var "nearVal")
6975 " and "
6976 (var "farVal")
6977 " planes are different from the default,
6978 0 and 1, respectively.
6979 A return
6980 value of "
6981 (code "GLU_TRUE")
6982 " indicates success; a return value of "
6983 (code "GLU_FALSE")
6984 "
6985 indicates failure. ")
6986 (para "
6987 To compute the coordinates "
6988 (math "("
6989 (var "objX")
6990 ","
6991 (var "objY")
6992 (var "objZ")
6993 (var "objW")
6994 ")")
6995 ", "
6996 (code "gluUnProject4")
6997 " multiplies the normalized device coordinates by the inverse of "
6998 (var "model")
6999 " * "
7000 (var "proj")
7001 " as follows: ")
7002 (para (math "("
7003 "("
7004 (var "objX")
7005 ")"
7006 ", "
7007 "("
7008 (var "objY")
7009 ")"
7010 ", "
7011 "("
7012 (var "objZ")
7013 ")"
7014 ", "
7015 "("
7016 (var "objW")
7017 ")"
7018 ","
7019 ")"
7020 "="
7021 (var "INV")
7022 "\u2061"
7023 "("
7024 (var "P")
7025 "\u2062"
7026 (var "M")
7027 ","
7028 ")"
7029 "\u2062"
7030 "("
7031 "("
7032 "2"
7033 "\u2061"
7034 "("
7035 (var "winX")
7036 "-"
7037 (var "view")
7038 "\u2061"
7039 "["
7040 "0"
7041 ","
7042 "]"
7043 ","
7044 ")"
7045 ","
7046 "/"
7047 (var "view")
7048 "\u2061"
7049 "["
7050 "2"
7051 ","
7052 "]"
7053 ","
7054 "-"
7055 "1"
7056 ")"
7057 ", "
7058 "("
7059 "2"
7060 "\u2061"
7061 "("
7062 (var "winY")
7063 "-"
7064 (var "view")
7065 "\u2061"
7066 "["
7067 "1"
7068 ","
7069 "]"
7070 ","
7071 ")"
7072 ","
7073 "/"
7074 (var "view")
7075 "\u2061"
7076 "["
7077 "3"
7078 ","
7079 "]"
7080 ","
7081 "-"
7082 "1"
7083 ")"
7084 ", "
7085 "("
7086 "2"
7087 "\u2061"
7088 "("
7089 (var "winZ")
7090 "-"
7091 (var "nearVal")
7092 ","
7093 ")"
7094 ","
7095 "/"
7096 "("
7097 (var "farVal")
7098 "-"
7099 (var "nearVal")
7100 ","
7101 ")"
7102 ","
7103 "-"
7104 "1"
7105 ")"
7106 ", "
7107 "("
7108 (var "clipW")
7109 ")"
7110 ","
7111 ")"))
7112 (para (math (var "INV"))
7113 "
7114 denotes matrix inversion. ")
7115 (para (code "gluUnProject4")
7116 " is equivalent to "
7117 (code "gluUnProject")
7118 " when "
7119 (var "clipW")
7120 " is 1, "
7121 (var "nearVal")
7122 " is 0, and "
7123 (var "farVal")
7124 " is 1. ")))
7125
7126 (define-gl-procedure
7127 gluUnProject
7128 "gluUnProject"
7129 (funcsynopsis
7130 (funcprototype
7131 (funcdef "GLint " (function "gluUnProject"))
7132 (paramdef "GLdouble " (parameter "winX"))
7133 (paramdef "GLdouble " (parameter "winY"))
7134 (paramdef "GLdouble " (parameter "winZ"))
7135 (paramdef
7136 "const GLdouble * "
7137 (parameter "model"))
7138 (paramdef "const GLdouble * " (parameter "proj"))
7139 (paramdef "const GLint * " (parameter "view"))
7140 (paramdef "GLdouble* " (parameter "objX"))
7141 (paramdef "GLdouble* " (parameter "objY"))
7142 (paramdef "GLdouble* " (parameter "objZ"))))
7143 '(*fragment*
7144 (heading
7145 "map window coordinates to object coordinates")
7146 (heading "Parameters")
7147 (table (% (formatter (asis)))
7148 (entry (% (heading (var "winX")))
7149 (itemx (var "winY"))
7150 (itemx (var "winZ"))
7151 (para "
7152 Specify the window coordinates to be mapped. "))
7153 (entry (% (heading (var "model")))
7154 (para "
7155 Specifies the modelview matrix (as from a "
7156 (code "glGetDoublev")
7157 " call). "))
7158 (entry (% (heading (var "proj")))
7159 (para "
7160 Specifies the projection matrix (as from a "
7161 (code "glGetDoublev")
7162 " call). "))
7163 (entry (% (heading (var "view")))
7164 (para "
7165 Specifies the viewport (as from a "
7166 (code "glGetIntegerv")
7167 " call). "))
7168 (entry (% (heading (var "objX")))
7169 (itemx (var "objY"))
7170 (itemx (var "objZ"))
7171 (para "
7172 Returns the computed object coordinates. ")))
7173 (heading "Description")
7174 (para (code "gluUnProject")
7175 " maps the specified window coordinates into object
7176 coordinates using "
7177 (var "model")
7178 ", "
7179 (var "proj")
7180 ", and "
7181 (var "view")
7182 ".
7183 The result is stored in "
7184 (var "objX")
7185 ", "
7186 (var "objY")
7187 ", and "
7188 (var "objZ")
7189 ". A return value of "
7190 (code "GLU_TRUE")
7191 " indicates success; a return value of "
7192 (code "GLU_FALSE")
7193 "
7194 indicates failure. ")
7195 (para "
7196 To compute the coordinates "
7197 (math "("
7198 (var "objX")
7199 ","
7200 (var "objY")
7201 (var "objZ")
7202 ")")
7203 ", "
7204 (code "gluUnProject")
7205 " multiplies the normalized device coordinates by the inverse of "
7206 (var "model")
7207 " * "
7208 (var "proj")
7209 " as follows: ")
7210 (para (math "("
7211 "("
7212 (var "objX")
7213 ")"
7214 ", "
7215 "("
7216 (var "objY")
7217 ")"
7218 ", "
7219 "("
7220 (var "objZ")
7221 ")"
7222 ", "
7223 "("
7224 (var "W")
7225 ")"
7226 ","
7227 ")"
7228 "="
7229 (var "INV")
7230 "\u2061"
7231 "("
7232 (var "P")
7233 "\u2062"
7234 (var "M")
7235 ","
7236 ")"
7237 "\u2062"
7238 "("
7239 "("
7240 "2"
7241 "\u2061"
7242 "("
7243 (var "winX")
7244 "-"
7245 (var "view")
7246 "\u2061"
7247 "["
7248 "0"
7249 ","
7250 "]"
7251 ","
7252 ")"
7253 ","
7254 "/"
7255 (var "view")
7256 "\u2061"
7257 "["
7258 "2"
7259 ","
7260 "]"
7261 ","
7262 "-"
7263 "1"
7264 ")"
7265 ", "
7266 "("
7267 "2"
7268 "\u2061"
7269 "("
7270 (var "winY")
7271 "-"
7272 (var "view")
7273 "\u2061"
7274 "["
7275 "1"
7276 ","
7277 "]"
7278 ","
7279 ")"
7280 ","
7281 "/"
7282 (var "view")
7283 "\u2061"
7284 "["
7285 "3"
7286 ","
7287 "]"
7288 ","
7289 "-"
7290 "1"
7291 ")"
7292 ", "
7293 "("
7294 "2"
7295 "\u2061"
7296 "("
7297 (var "winZ")
7298 ","
7299 ")"
7300 "-"
7301 "1"
7302 ")"
7303 ", "
7304 "("
7305 "1"
7306 ")"
7307 ","
7308 ")")
7309 (math (var "INV"))
7310 "
7311 denotes matrix inversion.
7312 W is an unused variable, included for consistent matrix notation. ")))
7313
Unnamed repository; edit this file 'description' to name the repository.