4 The functions from this section may be had by loading the module:
7 (use-modules (figl glu low-level)
11 This section of the manual was derived from the upstream OpenGL
12 documentation. Each function's documentation has its own copyright
13 statement; for full details, see the upstream documentation. The
14 copyright notices and licenses present in this section are as follows.
16 Copyright @copyright{} 1991-2006 Silicon Graphics, Inc. This document is
17 licensed under the SGI Free Software B License. For details, see
18 @uref{http://oss.sgi.com/projects/FreeB/,http://oss.sgi.com/projects/FreeB/}.
22 @deftypefun void gluBeginCurve nurb
23 @deftypefunx void gluEndCurve nurb
24 Delimit a NURBS curve definition.
28 Specifies the NURBS object (created with @code{gluNewNurbsRenderer}).
32 Use @code{gluBeginCurve} to mark the beginning of a NURBS curve
33 definition. After calling @code{gluBeginCurve}, make one or more calls
34 to @code{gluNurbsCurve} to define the attributes of the curve. Exactly
35 one of the calls to @code{gluNurbsCurve} must have a curve type of
36 @code{GLU_MAP1_VERTEX_3} or @code{GLU_MAP1_VERTEX_4}. To mark the end of
37 the NURBS curve definition, call @code{gluEndCurve}.
39 GL evaluators are used to render the NURBS curve as a series of line
40 segments. Evaluator state is preserved during rendering with
41 @code{glPushAttrib}(@code{GLU_EVAL_BIT}) and @code{glPopAttrib}(). See
42 the @code{glPushAttrib} reference page for details on exactly what state
47 @deftypefun void gluBeginPolygon tess
48 @deftypefunx void gluEndPolygon tess
49 Delimit a polygon description.
53 Specifies the tessellation object (created with @code{gluNewTess}).
57 @code{gluBeginPolygon} and @code{gluEndPolygon} delimit the definition
58 of a nonconvex polygon. To define such a polygon, first call
59 @code{gluBeginPolygon}. Then define the contours of the polygon by
60 calling @code{gluTessVertex} for each vertex and @code{gluNextContour}
61 to start each new contour. Finally, call @code{gluEndPolygon} to signal
62 the end of the definition. See the @code{gluTessVertex} and
63 @code{gluNextContour} reference pages for more details.
65 Once @code{gluEndPolygon} is called, the polygon is tessellated, and the
66 resulting triangles are described through callbacks. See
67 @code{gluTessCallback} for descriptions of the callback functions.
71 @deftypefun void gluBeginSurface nurb
72 @deftypefunx void gluEndSurface nurb
73 Delimit a NURBS surface definition.
77 Specifies the NURBS object (created with @code{gluNewNurbsRenderer}).
81 Use @code{gluBeginSurface} to mark the beginning of a NURBS surface
82 definition. After calling @code{gluBeginSurface}, make one or more calls
83 to @code{gluNurbsSurface} to define the attributes of the surface.
84 Exactly one of these calls to @code{gluNurbsSurface} must have a surface
85 type of @code{GLU_MAP2_VERTEX_3} or @code{GLU_MAP2_VERTEX_4}. To mark
86 the end of the NURBS surface definition, call @code{gluEndSurface}.
88 Trimming of NURBS surfaces is supported with @code{gluBeginTrim},
89 @code{gluPwlCurve}, @code{gluNurbsCurve}, and @code{gluEndTrim}. See the
90 @code{gluBeginTrim} reference page for details.
92 GL evaluators are used to render the NURBS surface as a set of polygons.
93 Evaluator state is preserved during rendering with
94 @code{glPushAttrib}(@code{GLU_EVAL_BIT}) and @code{glPopAttrib}. See the
95 @code{glPushAttrib} reference page for details on exactly what state
100 @deftypefun void gluBeginTrim nurb
101 @deftypefunx void gluEndTrim nurb
102 Delimit a NURBS trimming loop definition.
106 Specifies the NURBS object (created with @code{gluNewNurbsRenderer}).
110 Use @code{gluBeginTrim} to mark the beginning of a trimming loop and
111 @code{gluEndTrim} to mark the end of a trimming loop. A trimming loop is
112 a set of oriented curve segments (forming a closed curve) that define
113 boundaries of a NURBS surface. You include these trimming loops in the
114 definition of a NURBS surface, between calls to @code{gluBeginSurface}
115 and @code{gluEndSurface}.
117 The definition for a NURBS surface can contain many trimming loops. For
118 example, if you wrote a definition for a NURBS surface that resembled a
119 rectangle with a hole punched out, the definition would contain two
120 trimming loops. One loop would define the outer edge of the rectangle;
121 the other would define the hole punched out of the rectangle. The
122 definitions of each of these trimming loops would be bracketed by a
123 @code{gluBeginTrim}/@code{gluEndTrim} pair.
125 The definition of a single closed trimming loop can consist of multiple
126 curve segments, each described as a piecewise linear curve (see
127 @code{gluPwlCurve}) or as a single NURBS curve (see
128 @code{gluNurbsCurve}), or as a combination of both in any order. The
129 only library calls that can appear in a trimming loop definition
130 (between the calls to @code{gluBeginTrim} and @code{gluEndTrim}) are
131 @code{gluPwlCurve} and @code{gluNurbsCurve}.
133 The area of the NURBS surface that is displayed is the region in the
134 domain to the left of the trimming curve as the curve parameter
135 increases. Thus, the retained region of the NURBS surface is inside a
136 counterclockwise trimming loop and outside a clockwise trimming loop.
137 For the rectangle mentioned earlier, the trimming loop for the outer
138 edge of the rectangle runs counterclockwise, while the trimming loop for
139 the punched-out hole runs clockwise.
141 If you use more than one curve to define a single trimming loop, the
142 curve segments must form a closed loop (that is, the endpoint of each
143 curve must be the starting point of the next curve, and the endpoint of
144 the final curve must be the starting point of the first curve). If the
145 endpoints of the curve are sufficiently close together but not exactly
146 coincident, they will be coerced to match. If the endpoints are not
147 sufficiently close, an error results (see @code{gluNurbsCallback}).
149 If a trimming loop definition contains multiple curves, the direction of
150 the curves must be consistent (that is, the inside must be to the left
151 of all of the curves). Nested trimming loops are legal as long as the
152 curve orientations alternate correctly. If trimming curves are
153 self-intersecting, or intersect one another, an error results.
155 If no trimming information is given for a NURBS surface, the entire
160 @deftypefun GLint gluBuild1DMipmapLevels target internalFormat width format type level base max data
161 Builds a subset of one-dimensional mipmap levels.
165 Specifies the target texture. Must be @code{GLU_TEXTURE_1D}.
167 @item @var{internalFormat}
168 Requests the internal storage format of the texture image. The most
169 current version of the SGI implementation of GLU does not check this
170 value for validity before passing it on to the underlying OpenGL
171 implementation. A value that is not accepted by the OpenGL
172 implementation will lead to an OpenGL error. The benefit of not checking
173 this value at the GLU level is that OpenGL extensions can add new
174 internal texture formats without requiring a revision of the GLU
175 implementation. Older implementations of GLU check this value and raise
176 a GLU error if it is not 1, 2, 3, or 4 or one of the following symbolic
177 constants: @code{GLU_ALPHA}, @code{GLU_ALPHA4}, @code{GLU_ALPHA8},
178 @code{GLU_ALPHA12}, @code{GLU_ALPHA16}, @code{GLU_LUMINANCE},
179 @code{GLU_LUMINANCE4}, @code{GLU_LUMINANCE8}, @code{GLU_LUMINANCE12},
180 @code{GLU_LUMINANCE16}, @code{GLU_LUMINANCE_ALPHA},
181 @code{GLU_LUMINANCE4_ALPHA4}, @code{GLU_LUMINANCE6_ALPHA2},
182 @code{GLU_LUMINANCE8_ALPHA8}, @code{GLU_LUMINANCE12_ALPHA4},
183 @code{GLU_LUMINANCE12_ALPHA12}, @code{GLU_LUMINANCE16_ALPHA16},
184 @code{GLU_INTENSITY}, @code{GLU_INTENSITY4}, @code{GLU_INTENSITY8},
185 @code{GLU_INTENSITY12}, @code{GLU_INTENSITY16}, @code{GLU_RGB},
186 @code{GLU_R3_G3_B2}, @code{GLU_RGB4}, @code{GLU_RGB5}, @code{GLU_RGB8},
187 @code{GLU_RGB10}, @code{GLU_RGB12}, @code{GLU_RGB16}, @code{GLU_RGBA},
188 @code{GLU_RGBA2}, @code{GLU_RGBA4}, @code{GLU_RGB5_A1},
189 @code{GLU_RGBA8}, @code{GLU_RGB10_A2}, @code{GLU_RGBA12}, or
193 Specifies the width in pixels of the texture image. This should be a
197 Specifies the format of the pixel data. Must be one of:
198 @code{GLU_COLOR_INDEX}, @code{GLU_DEPTH_COMPONENT}, @code{GLU_RED},
199 @code{GLU_GREEN}, @code{GLU_BLUE}, @code{GLU_ALPHA}, @code{GLU_RGB},
200 @code{GLU_RGBA}, @code{GLU_BGR}, @code{GLU_BGRA}, @code{GLU_LUMINANCE},
201 or @code{GLU_LUMINANCE_ALPHA}.
204 Specifies the data type for @var{data}. Must be one of:
205 @code{GLU_UNSIGNED_BYTE}, @code{GLU_BYTE}, @code{GLU_BITMAP},
206 @code{GLU_UNSIGNED_SHORT}, @code{GLU_SHORT}, @code{GLU_UNSIGNED_INT},
207 @code{GLU_INT}, @code{GLU_FLOAT}, @code{GLU_UNSIGNED_BYTE_3_3_2},
208 @code{GLU_UNSIGNED_BYTE_2_3_3_REV}, @code{GLU_UNSIGNED_SHORT_5_6_5},
209 @code{GLU_UNSIGNED_SHORT_5_6_5_REV}, @code{GLU_UNSIGNED_SHORT_4_4_4_4},
210 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV},
211 @code{GLU_UNSIGNED_SHORT_5_5_5_1},
212 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GLU_UNSIGNED_INT_8_8_8_8},
213 @code{GLU_UNSIGNED_INT_8_8_8_8_REV}, @code{GLU_UNSIGNED_INT_10_10_10_2},
214 or @code{GLU_UNSIGNED_INT_2_10_10_10_REV}.
217 Specifies the mipmap level of the image data.
220 Specifies the minimum mipmap level to pass to @code{glTexImage1D}.
223 Specifies the maximum mipmap level to pass to @code{glTexImage1D}.
226 Specifies a pointer to the image data in memory.
230 @code{gluBuild1DMipmapLevels} builds a subset of prefiltered
231 one-dimensional texture maps of decreasing resolutions called a mipmap.
232 This is used for the antialiasing of texture mapped primitives.
234 A return value of zero indicates success, otherwise a GLU error code is
235 returned (see @code{gluErrorString}).
237 A series of mipmap levels from @var{base} to @var{max} is built by
238 decimating @var{data} in half until size @r{1×1} is reached. At each
239 level, each texel in the halved mipmap level is an average of the
240 corresponding two texels in the larger mipmap level. @code{glTexImage1D}
241 is called to load these mipmap levels from @var{base} to @var{max}. If
242 @var{max} is larger than the highest mipmap level for the texture of the
243 specified size, then a GLU error code is returned (see
244 @code{gluErrorString}) and nothing is loaded.
246 For example, if @var{level} is 2 and @var{width} is 16, the following
247 levels are possible: @r{16×1}, @r{8×1}, @r{4×1}, @r{2×1}, @r{1×1}. These
248 correspond to levels 2 through 6 respectively. If @var{base} is 3 and
249 @var{max} is 5, then only mipmap levels @r{8×1}, @r{4×1} and @r{2×1} are
250 loaded. However, if @var{max} is 7, then an error is returned and
251 nothing is loaded since @var{max} is larger than the highest mipmap
252 level which is, in this case, 6.
254 The highest mipmap level can be derived from the formula
255 @r{@var{log}_2(@var{width}×2^@var{level},)}.
257 See the @code{glTexImage1D} reference page for a description of the
258 acceptable values for @var{type} parameter. See the @code{glDrawPixels}
259 reference page for a description of the acceptable values for
260 @var{level} parameter.
262 @code{GLU_INVALID_VALUE} is returned if @var{level} > @var{base},
263 @var{base} < 0, @var{max} < @var{base} or @var{max} is > the highest
264 mipmap level for @var{data}.
266 @code{GLU_INVALID_VALUE} is returned if @var{width} is < 1.
268 @code{GLU_INVALID_ENUM} is returned if @var{internalFormat},
269 @var{format}, or @var{type} are not legal.
271 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
272 @code{GLU_UNSIGNED_BYTE_3_3_2} or @code{GLU_UNSIGNED_BYTE_2_3_3_REV} and
273 @var{format} is not @code{GLU_RGB}.
275 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
276 @code{GLU_UNSIGNED_SHORT_5_6_5} or @code{GLU_UNSIGNED_SHORT_5_6_5_REV}
277 and @var{format} is not @code{GLU_RGB}.
279 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
280 @code{GLU_UNSIGNED_SHORT_4_4_4_4} or
281 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV} and @var{format} is neither
282 @code{GLU_RGBA} nor @code{GLU_BGRA}.
284 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
285 @code{GLU_UNSIGNED_SHORT_5_5_5_1} or
286 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV} and @var{format} is neither
287 @code{GLU_RGBA} nor @code{GLU_BGRA}.
289 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
290 @code{GLU_UNSIGNED_INT_8_8_8_8} or @code{GLU_UNSIGNED_INT_8_8_8_8_REV}
291 and @var{format} is neither @code{GLU_RGBA} nor @code{GLU_BGRA}.
293 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
294 @code{GLU_UNSIGNED_INT_10_10_10_2} or
295 @code{GLU_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
296 @code{GLU_RGBA} nor @code{GLU_BGRA}.
300 @deftypefun GLint gluBuild1DMipmaps target internalFormat width format type data
301 Builds a one-dimensional mipmap.
305 Specifies the target texture. Must be @code{GLU_TEXTURE_1D}.
307 @item @var{internalFormat}
308 Requests the internal storage format of the texture image. The most
309 current version of the SGI implementation of GLU does not check this
310 value for validity before passing it on to the underlying OpenGL
311 implementation. A value that is not accepted by the OpenGL
312 implementation will lead to an OpenGL error. The benefit of not checking
313 this value at the GLU level is that OpenGL extensions can add new
314 internal texture formats without requiring a revision of the GLU
315 implementation. Older implementations of GLU check this value and raise
316 a GLU error if it is not 1, 2, 3, or 4 or one of the following symbolic
317 constants: @code{GLU_ALPHA}, @code{GLU_ALPHA4}, @code{GLU_ALPHA8},
318 @code{GLU_ALPHA12}, @code{GLU_ALPHA16}, @code{GLU_LUMINANCE},
319 @code{GLU_LUMINANCE4}, @code{GLU_LUMINANCE8}, @code{GLU_LUMINANCE12},
320 @code{GLU_LUMINANCE16}, @code{GLU_LUMINANCE_ALPHA},
321 @code{GLU_LUMINANCE4_ALPHA4}, @code{GLU_LUMINANCE6_ALPHA2},
322 @code{GLU_LUMINANCE8_ALPHA8}, @code{GLU_LUMINANCE12_ALPHA4},
323 @code{GLU_LUMINANCE12_ALPHA12}, @code{GLU_LUMINANCE16_ALPHA16},
324 @code{GLU_INTENSITY}, @code{GLU_INTENSITY4}, @code{GLU_INTENSITY8},
325 @code{GLU_INTENSITY12}, @code{GLU_INTENSITY16}, @code{GLU_RGB},
326 @code{GLU_R3_G3_B2}, @code{GLU_RGB4}, @code{GLU_RGB5}, @code{GLU_RGB8},
327 @code{GLU_RGB10}, @code{GLU_RGB12}, @code{GLU_RGB16}, @code{GLU_RGBA},
328 @code{GLU_RGBA2}, @code{GLU_RGBA4}, @code{GLU_RGB5_A1},
329 @code{GLU_RGBA8}, @code{GLU_RGB10_A2}, @code{GLU_RGBA12}, or
333 Specifies the width, in pixels, of the texture image.
336 Specifies the format of the pixel data. Must be one of
337 @code{GLU_COLOR_INDEX}, @code{GLU_DEPTH_COMPONENT}, @code{GLU_RED},
338 @code{GLU_GREEN}, @code{GLU_BLUE}, @code{GLU_ALPHA}, @code{GLU_RGB},
339 @code{GLU_RGBA}, @code{GLU_BGR}, @code{GLU_BGRA}, @code{GLU_LUMINANCE},
340 or @code{GLU_LUMINANCE_ALPHA}.
343 Specifies the data type for @var{data}. Must be one of
344 @code{GLU_UNSIGNED_BYTE}, @code{GLU_BYTE}, @code{GLU_BITMAP},
345 @code{GLU_UNSIGNED_SHORT}, @code{GLU_SHORT}, @code{GLU_UNSIGNED_INT},
346 @code{GLU_INT}, @code{GLU_FLOAT}, @code{GLU_UNSIGNED_BYTE_3_3_2},
347 @code{GLU_UNSIGNED_BYTE_2_3_3_REV}, @code{GLU_UNSIGNED_SHORT_5_6_5},
348 @code{GLU_UNSIGNED_SHORT_5_6_5_REV}, @code{GLU_UNSIGNED_SHORT_4_4_4_4},
349 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV},
350 @code{GLU_UNSIGNED_SHORT_5_5_5_1},
351 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GLU_UNSIGNED_INT_8_8_8_8},
352 @code{GLU_UNSIGNED_INT_8_8_8_8_REV}, @code{GLU_UNSIGNED_INT_10_10_10_2},
353 or @code{GLU_UNSIGNED_INT_2_10_10_10_REV}.
356 Specifies a pointer to the image data in memory.
360 @code{gluBuild1DMipmaps} builds a series of prefiltered one-dimensional
361 texture maps of decreasing resolutions called a mipmap. This is used for
362 the antialiasing of texture mapped primitives.
364 A return value of zero indicates success, otherwise a GLU error code is
365 returned (see @code{gluErrorString}).
367 Initially, the @var{width} of @var{data} is checked to see if it is a
368 power of 2. If not, a copy of @var{data} is scaled up or down to the
369 nearest power of 2. (If @var{width} is exactly between powers of 2, then
370 the copy of @var{data} will scale upwards.) This copy will be used for
371 subsequent mipmapping operations described below. For example, if
372 @var{width} is 57, then a copy of @var{data} will scale up to 64 before
373 mipmapping takes place.
375 Then, proxy textures (see @code{glTexImage1D}) are used to determine if
376 the implementation can fit the requested texture. If not, @var{width} is
377 continually halved until it fits.
379 Next, a series of mipmap levels is built by decimating a copy of
380 @var{data} in half until size @r{1×1} is reached. At each level, each
381 texel in the halved mipmap level is an average of the corresponding two
382 texels in the larger mipmap level.
384 @code{glTexImage1D} is called to load each of these mipmap levels. Level
385 0 is a copy of @var{data}. The highest level is
386 @r{@var{log}_2,(@var{width},)}. For example, if @var{width} is 64 and
387 the implementation can store a texture of this size, the following
388 mipmap levels are built: @r{64×1}, @r{32×1}, @r{16×1}, @r{8×1}, @r{4×1},
389 @r{2×1}, and @r{1×1}. These correspond to levels 0 through 6,
392 See the @code{glTexImage1D} reference page for a description of the
393 acceptable values for the @var{type} parameter. See the
394 @code{glDrawPixels} reference page for a description of the acceptable
395 values for the @var{data} parameter.
397 @code{GLU_INVALID_VALUE} is returned if @var{width} is < 1.
399 @code{GLU_INVALID_ENUM} is returned if @var{format} or @var{type} are
402 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
403 @code{GLU_UNSIGNED_BYTE_3_3_2} or @code{GLU_UNSIGNED_BYTE_2_3_3_REV} and
404 @var{format} is not @code{GLU_RGB}.
406 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
407 @code{GLU_UNSIGNED_SHORT_5_6_5} or @code{GLU_UNSIGNED_SHORT_5_6_5_REV}
408 and @var{format} is not @code{GLU_RGB}.
410 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
411 @code{GLU_UNSIGNED_SHORT_4_4_4_4} or
412 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV} and @var{format} is neither
413 @code{GLU_RGBA} nor @code{GLU_BGRA}.
415 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
416 @code{GLU_UNSIGNED_SHORT_5_5_5_1} or
417 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV} and @var{format} is neither
418 @code{GLU_RGBA} nor @code{GLU_BGRA}.
420 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
421 @code{GLU_UNSIGNED_INT_8_8_8_8} or @code{GLU_UNSIGNED_INT_8_8_8_8_REV}
422 and @var{format} is neither @code{GLU_RGBA} nor @code{GLU_BGRA}.
424 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
425 @code{GLU_UNSIGNED_INT_10_10_10_2} or
426 @code{GLU_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
427 @code{GLU_RGBA} nor @code{GLU_BGRA}.
431 @deftypefun GLint gluBuild2DMipmapLevels target internalFormat width height format type level base max data
432 Builds a subset of two-dimensional mipmap levels.
436 Specifies the target texture. Must be @code{GLU_TEXTURE_2D}.
438 @item @var{internalFormat}
439 Requests the internal storage format of the texture image. The most
440 current version of the SGI implementation of GLU does not check this
441 value for validity before passing it on to the underlying OpenGL
442 implementation. A value that is not accepted by the OpenGL
443 implementation will lead to an OpenGL error. The benefit of not checking
444 this value at the GLU level is that OpenGL extensions can add new
445 internal texture formats without requiring a revision of the GLU
446 implementation. Older implementations of GLU check this value and raise
447 a GLU error if it is not 1, 2, 3, or 4 or one of the following symbolic
448 constants: @code{GLU_ALPHA}, @code{GLU_ALPHA4}, @code{GLU_ALPHA8},
449 @code{GLU_ALPHA12}, @code{GLU_ALPHA16}, @code{GLU_LUMINANCE},
450 @code{GLU_LUMINANCE4}, @code{GLU_LUMINANCE8}, @code{GLU_LUMINANCE12},
451 @code{GLU_LUMINANCE16}, @code{GLU_LUMINANCE_ALPHA},
452 @code{GLU_LUMINANCE4_ALPHA4}, @code{GLU_LUMINANCE6_ALPHA2},
453 @code{GLU_LUMINANCE8_ALPHA8}, @code{GLU_LUMINANCE12_ALPHA4},
454 @code{GLU_LUMINANCE12_ALPHA12}, @code{GLU_LUMINANCE16_ALPHA16},
455 @code{GLU_INTENSITY}, @code{GLU_INTENSITY4}, @code{GLU_INTENSITY8},
456 @code{GLU_INTENSITY12}, @code{GLU_INTENSITY16}, @code{GLU_RGB},
457 @code{GLU_R3_G3_B2}, @code{GLU_RGB4}, @code{GLU_RGB5}, @code{GLU_RGB8},
458 @code{GLU_RGB10}, @code{GLU_RGB12}, @code{GLU_RGB16}, @code{GLU_RGBA},
459 @code{GLU_RGBA2}, @code{GLU_RGBA4}, @code{GLU_RGB5_A1},
460 @code{GLU_RGBA8}, @code{GLU_RGB10_A2}, @code{GLU_RGBA12}, or
465 Specifies the width and height, respectively, in pixels of the texture
466 image. These should be a power of 2.
469 Specifies the format of the pixel data. Must be one of
470 @code{GLU_COLOR_INDEX}, @code{GLU_DEPTH_COMPONENT}, @code{GLU_RED},
471 @code{GLU_GREEN}, @code{GLU_BLUE}, @code{GLU_ALPHA}, @code{GLU_RGB},
472 @code{GLU_RGBA}, @code{GLU_BGR}, @code{GLU_BGRA}, @code{GLU_LUMINANCE},
473 or @code{GLU_LUMINANCE_ALPHA}.
476 Specifies the data type for @var{data}. Must be one of
477 @code{GLU_UNSIGNED_BYTE}, @code{GLU_BYTE}, @code{GLU_BITMAP},
478 @code{GLU_UNSIGNED_SHORT}, @code{GLU_SHORT}, @code{GLU_UNSIGNED_INT},
479 @code{GLU_INT}, @code{GLU_FLOAT}, @code{GLU_UNSIGNED_BYTE_3_3_2},
480 @code{GLU_UNSIGNED_BYTE_2_3_3_REV}, @code{GLU_UNSIGNED_SHORT_5_6_5},
481 @code{GLU_UNSIGNED_SHORT_5_6_5_REV}, @code{GLU_UNSIGNED_SHORT_4_4_4_4},
482 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV},
483 @code{GLU_UNSIGNED_SHORT_5_5_5_1},
484 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GLU_UNSIGNED_INT_8_8_8_8},
485 @code{GLU_UNSIGNED_INT_8_8_8_8_REV}, @code{GLU_UNSIGNED_INT_10_10_10_2},
486 or @code{GLU_UNSIGNED_INT_2_10_10_10_REV}.
489 Specifies the mipmap level of the image data.
492 Specifies the minimum mipmap level to pass to @code{glTexImage2D}.
495 Specifies the maximum mipmap level to pass to @code{glTexImage2D}.
498 Specifies a pointer to the image data in memory.
502 @code{gluBuild2DMipmapLevels} builds a subset of prefiltered
503 two-dimensional texture maps of decreasing resolutions called a mipmap.
504 This is used for the antialiasing of texture mapped primitives.
506 A return value of zero indicates success, otherwise a GLU error code is
507 returned (see @code{gluErrorString}).
509 A series of mipmap levels from @var{base} to @var{max} is built by
510 decimating @var{data} in half along both dimensions until size @r{1×1}
511 is reached. At each level, each texel in the halved mipmap level is an
512 average of the corresponding four texels in the larger mipmap level. (In
513 the case of rectangular images, the decimation will ultimately reach an
514 @r{@var{N}×1} or @r{1×@var{N}} configuration. Here, two texels are
515 averaged instead.) @code{glTexImage2D} is called to load these mipmap
516 levels from @var{base} to @var{max}. If @var{max} is larger than the
517 highest mipmap level for the texture of the specified size, then a GLU
518 error code is returned (see @code{gluErrorString}) and nothing is
521 For example, if @var{level} is 2 and @var{width} is 16 and @var{height}
522 is 8, the following levels are possible: @r{16×8}, @r{8×4}, @r{4×2},
523 @r{2×1}, @r{1×1}. These correspond to levels 2 through 6 respectively.
524 If @var{base} is 3 and @var{max} is 5, then only mipmap levels @r{8×4},
525 @r{4×2}, and @r{2×1} are loaded. However, if @var{max} is 7, then an
526 error is returned and nothing is loaded since @var{max} is larger than
527 the highest mipmap level which is, in this case, 6.
529 The highest mipmap level can be derived from the formula
530 @r{@var{log}_2(@var{max}(@var{width},@var{height})×2^@var{level},)}.
532 See the @code{glTexImage1D} reference page for a description of the
533 acceptable values for @var{format} parameter. See the
534 @code{glDrawPixels} reference page for a description of the acceptable
535 values for @var{type} parameter.
537 @code{GLU_INVALID_VALUE} is returned if @var{level} > @var{base},
538 @var{base} < 0, @var{max} < @var{base}, or @var{max} is > the highest
539 mipmap level for @var{data}.
541 @code{GLU_INVALID_VALUE} is returned if @var{width} or @var{height} is <
544 @code{GLU_INVALID_ENUM} is returned if @var{internalFormat},
545 @var{format}, or @var{type} is not legal.
547 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
548 @code{GLU_UNSIGNED_BYTE_3_3_2} or @code{GLU_UNSIGNED_BYTE_2_3_3_REV} and
549 @var{format} is not @code{GLU_RGB}.
551 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
552 @code{GLU_UNSIGNED_SHORT_5_6_5} or @code{GLU_UNSIGNED_SHORT_5_6_5_REV}
553 and @var{format} is not @code{GLU_RGB}.
555 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
556 @code{GLU_UNSIGNED_SHORT_4_4_4_4} or
557 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV} and @var{format} is neither
558 @code{GLU_RGBA} nor @code{GLU_BGRA}.
560 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
561 @code{GLU_UNSIGNED_SHORT_5_5_5_1} or
562 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV} and @var{format} is neither
563 @code{GLU_RGBA} nor @code{GLU_BGRA}.
565 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
566 @code{GLU_UNSIGNED_INT_8_8_8_8} or @code{GLU_UNSIGNED_INT_8_8_8_8_REV}
567 and @var{format} is neither @code{GLU_RGBA} nor @code{GLU_BGRA}.
569 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
570 @code{GLU_UNSIGNED_INT_10_10_10_2} or
571 @code{GLU_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
572 @code{GLU_RGBA} nor @code{GLU_BGRA}.
576 @deftypefun GLint gluBuild2DMipmaps target internalFormat width height format type data
577 Builds a two-dimensional mipmap.
581 Specifies the target texture. Must be @code{GLU_TEXTURE_2D}.
583 @item @var{internalFormat}
584 Requests the internal storage format of the texture image. The most
585 current version of the SGI implementation of GLU does not check this
586 value for validity before passing it on to the underlying OpenGL
587 implementation. A value that is not accepted by the OpenGL
588 implementation will lead to an OpenGL error. The benefit of not checking
589 this value at the GLU level is that OpenGL extensions can add new
590 internal texture formats without requiring a revision of the GLU
591 implementation. Older implementations of GLU check this value and raise
592 a GLU error if it is not 1, 2, 3, or 4 or one of the following symbolic
593 constants: @code{GLU_ALPHA}, @code{GLU_ALPHA4}, @code{GLU_ALPHA8},
594 @code{GLU_ALPHA12}, @code{GLU_ALPHA16}, @code{GLU_LUMINANCE},
595 @code{GLU_LUMINANCE4}, @code{GLU_LUMINANCE8}, @code{GLU_LUMINANCE12},
596 @code{GLU_LUMINANCE16}, @code{GLU_LUMINANCE_ALPHA},
597 @code{GLU_LUMINANCE4_ALPHA4}, @code{GLU_LUMINANCE6_ALPHA2},
598 @code{GLU_LUMINANCE8_ALPHA8}, @code{GLU_LUMINANCE12_ALPHA4},
599 @code{GLU_LUMINANCE12_ALPHA12}, @code{GLU_LUMINANCE16_ALPHA16},
600 @code{GLU_INTENSITY}, @code{GLU_INTENSITY4}, @code{GLU_INTENSITY8},
601 @code{GLU_INTENSITY12}, @code{GLU_INTENSITY16}, @code{GLU_RGB},
602 @code{GLU_R3_G3_B2}, @code{GLU_RGB4}, @code{GLU_RGB5}, @code{GLU_RGB8},
603 @code{GLU_RGB10}, @code{GLU_RGB12}, @code{GLU_RGB16}, @code{GLU_RGBA},
604 @code{GLU_RGBA2}, @code{GLU_RGBA4}, @code{GLU_RGB5_A1},
605 @code{GLU_RGBA8}, @code{GLU_RGB10_A2}, @code{GLU_RGBA12}, or
610 Specifies in pixels the width and height, respectively, of the texture
614 Specifies the format of the pixel data. Must be one of
615 @code{GLU_COLOR_INDEX}, @code{GLU_DEPTH_COMPONENT}, @code{GLU_RED},
616 @code{GLU_GREEN}, @code{GLU_BLUE}, @code{GLU_ALPHA}, @code{GLU_RGB},
617 @code{GLU_RGBA}, @code{GLU_BGR}, @code{GLU_BGRA}, @code{GLU_LUMINANCE},
618 or @code{GLU_LUMINANCE_ALPHA}.
621 Specifies the data type for @var{data}. Must be one of
622 @code{GLU_UNSIGNED_BYTE}, @code{GLU_BYTE}, @code{GLU_BITMAP},
623 @code{GLU_UNSIGNED_SHORT}, @code{GLU_SHORT}, @code{GLU_UNSIGNED_INT},
624 @code{GLU_INT}, @code{GLU_FLOAT}, @code{GLU_UNSIGNED_BYTE_3_3_2},
625 @code{GLU_UNSIGNED_BYTE_2_3_3_REV}, @code{GLU_UNSIGNED_SHORT_5_6_5},
626 @code{GLU_UNSIGNED_SHORT_5_6_5_REV}, @code{GLU_UNSIGNED_SHORT_4_4_4_4},
627 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV},
628 @code{GLU_UNSIGNED_SHORT_5_5_5_1},
629 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GLU_UNSIGNED_INT_8_8_8_8},
630 @code{GLU_UNSIGNED_INT_8_8_8_8_REV}, @code{GLU_UNSIGNED_INT_10_10_10_2},
631 or @code{GLU_UNSIGNED_INT_2_10_10_10_REV}.
634 Specifies a pointer to the image data in memory.
638 @code{gluBuild2DMipmaps} builds a series of prefiltered two-dimensional
639 texture maps of decreasing resolutions called a mipmap. This is used for
640 the antialiasing of texture-mapped primitives.
642 A return value of zero indicates success, otherwise a GLU error code is
643 returned (see @code{gluErrorString}).
645 Initially, the @var{width} and @var{height} of @var{data} are checked to
646 see if they are a power of 2. If not, a copy of @var{data} (not
647 @var{data}), is scaled up or down to the nearest power of 2. This copy
648 will be used for subsequent mipmapping operations described below. (If
649 @var{width} or @var{height} is exactly between powers of 2, then the
650 copy of @var{data} will scale upwards.) For example, if @var{width} is
651 57 and @var{height} is 23, then a copy of @var{data} will scale up to 64
652 in @var{width} and down to 16 in depth, before mipmapping takes place.
654 Then, proxy textures (see @code{glTexImage2D}) are used to determine if
655 the implementation can fit the requested texture. If not, both
656 dimensions are continually halved until it fits. (If the OpenGL version
657 is \(<= 1.0, both maximum texture dimensions are clamped to the value
658 returned by @code{glGetIntegerv} with the argument
659 @code{GLU_MAX_TEXTURE_SIZE}.)
661 Next, a series of mipmap levels is built by decimating a copy of
662 @var{data} in half along both dimensions until size @r{1×1} is reached.
663 At each level, each texel in the halved mipmap level is an average of
664 the corresponding four texels in the larger mipmap level. (In the case
665 of rectangular images, the decimation will ultimately reach an
666 @r{@var{N}×1} or @r{1×@var{N}} configuration. Here, two texels are
669 @code{glTexImage2D} is called to load each of these mipmap levels. Level
670 0 is a copy of @var{data}. The highest level is
671 @r{@var{log}_2,(@var{max}(@var{width},@var{height}),)}. For example,
672 if @var{width} is 64 and @var{height} is 16 and the implementation can
673 store a texture of this size, the following mipmap levels are built:
674 @r{64×16}, @r{32×8}, @r{16×4}, @r{8×2}, @r{4×1}, @r{2×1}, and @r{1×1}
675 These correspond to levels 0 through 6, respectively.
677 See the @code{glTexImage1D} reference page for a description of the
678 acceptable values for @var{format} parameter. See the
679 @code{glDrawPixels} reference page for a description of the acceptable
680 values for @var{type} parameter.
682 @code{GLU_INVALID_VALUE} is returned if @var{width} or @var{height} is <
685 @code{GLU_INVALID_ENUM} is returned if @var{internalFormat},
686 @var{format}, or @var{type} is not legal.
688 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
689 @code{GLU_UNSIGNED_BYTE_3_3_2} or @code{GLU_UNSIGNED_BYTE_2_3_3_REV} and
690 @var{format} is not @code{GLU_RGB}.
692 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
693 @code{GLU_UNSIGNED_SHORT_5_6_5} or @code{GLU_UNSIGNED_SHORT_5_6_5_REV}
694 and @var{format} is not @code{GLU_RGB}.
696 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
697 @code{GLU_UNSIGNED_SHORT_4_4_4_4} or
698 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV} and @var{format} is neither
699 @code{GLU_RGBA} nor @code{GLU_BGRA}.
701 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
702 @code{GLU_UNSIGNED_SHORT_5_5_5_1} or
703 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV} and @var{format} is neither
704 @code{GLU_RGBA} nor @code{GLU_BGRA}.
706 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
707 @code{GLU_UNSIGNED_INT_8_8_8_8} or @code{GLU_UNSIGNED_INT_8_8_8_8_REV}
708 and @var{format} is neither @code{GLU_RGBA} nor @code{GLU_BGRA}.
710 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
711 @code{GLU_UNSIGNED_INT_10_10_10_2} or
712 @code{GLU_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
713 @code{GLU_RGBA} nor @code{GLU_BGRA}.
717 @deftypefun GLint gluBuild3DMipmapLevels target internalFormat width height depth format type level base max data
718 Builds a subset of three-dimensional mipmap levels.
722 Specifies the target texture. Must be @code{GLU_TEXTURE_3D}.
724 @item @var{internalFormat}
725 Requests the internal storage format of the texture image. The most
726 current version of the SGI implementation of GLU does not check this
727 value for validity before passing it on to the underlying OpenGL
728 implementation. A value that is not accepted by the OpenGL
729 implementation will lead to an OpenGL error. The benefit of not checking
730 this value at the GLU level is that OpenGL extensions can add new
731 internal texture formats without requiring a revision of the GLU
732 implementation. Older implementations of GLU check this value and raise
733 a GLU error if it is not 1, 2, 3, or 4 or one of the following symbolic
734 constants: @code{GLU_ALPHA}, @code{GLU_ALPHA4}, @code{GLU_ALPHA8},
735 @code{GLU_ALPHA12}, @code{GLU_ALPHA16}, @code{GLU_LUMINANCE},
736 @code{GLU_LUMINANCE4}, @code{GLU_LUMINANCE8}, @code{GLU_LUMINANCE12},
737 @code{GLU_LUMINANCE16}, @code{GLU_LUMINANCE_ALPHA},
738 @code{GLU_LUMINANCE4_ALPHA4}, @code{GLU_LUMINANCE6_ALPHA2},
739 @code{GLU_LUMINANCE8_ALPHA8}, @code{GLU_LUMINANCE12_ALPHA4},
740 @code{GLU_LUMINANCE12_ALPHA12}, @code{GLU_LUMINANCE16_ALPHA16},
741 @code{GLU_INTENSITY}, @code{GLU_INTENSITY4}, @code{GLU_INTENSITY8},
742 @code{GLU_INTENSITY12}, @code{GLU_INTENSITY16}, @code{GLU_RGB},
743 @code{GLU_R3_G3_B2}, @code{GLU_RGB4}, @code{GLU_RGB5}, @code{GLU_RGB8},
744 @code{GLU_RGB10}, @code{GLU_RGB12}, @code{GLU_RGB16}, @code{GLU_RGBA},
745 @code{GLU_RGBA2}, @code{GLU_RGBA4}, @code{GLU_RGB5_A1},
746 @code{GLU_RGBA8}, @code{GLU_RGB10_A2}, @code{GLU_RGBA12}, or
752 Specifies in pixels the width, height and depth respectively, of the
753 texture image. These should be a power of 2.
756 Specifies the format of the pixel data. Must be one of
757 @code{GLU_COLOR_INDEX}, @code{GLU_DEPTH_COMPONENT}, @code{GLU_RED},
758 @code{GLU_GREEN}, @code{GLU_BLUE}, @code{GLU_ALPHA}, @code{GLU_RGB},
759 @code{GLU_RGBA}, @code{GLU_BGR}, @code{GLU_BGRA}, @code{GLU_LUMINANCE},
760 or @code{GLU_LUMINANCE_ALPHA}.
763 Specifies the data type for @var{data}. Must be one of
764 @code{GLU_UNSIGNED_BYTE}, @code{GLU_BYTE}, @code{GLU_BITMAP},
765 @code{GLU_UNSIGNED_SHORT}, @code{GLU_SHORT}, @code{GLU_UNSIGNED_INT},
766 @code{GLU_INT}, @code{GLU_FLOAT}, @code{GLU_UNSIGNED_BYTE_3_3_2},
767 @code{GLU_UNSIGNED_BYTE_2_3_3_REV}, @code{GLU_UNSIGNED_SHORT_5_6_5},
768 @code{GLU_UNSIGNED_SHORT_5_6_5_REV}, @code{GLU_UNSIGNED_SHORT_4_4_4_4},
769 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV},
770 @code{GLU_UNSIGNED_SHORT_5_5_5_1},
771 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GLU_UNSIGNED_INT_8_8_8_8},
772 @code{GLU_UNSIGNED_INT_8_8_8_8_REV}, @code{GLU_UNSIGNED_INT_10_10_10_2},
773 or @code{GLU_UNSIGNED_INT_2_10_10_10_REV}.
776 Specifies the mipmap level of the image data.
779 Specifies the minimum mipmap level to pass to @code{glTexImage3D}.
782 Specifies the maximum mipmap level to pass to @code{glTexImage3D}.
785 Specifies a pointer to the image data in memory.
789 @code{gluBuild3DMipmapLevels} builds a subset of prefiltered
790 three-dimensional texture maps of decreasing resolutions called a
791 mipmap. This is used for the antialiasing of texture mapped primitives.
793 A return value of zero indicates success, otherwise a GLU error code is
794 returned (see @code{gluErrorString}).
796 A series of mipmap levels from @var{base} to @var{max} is built by
797 decimating @var{data} in half along both dimensions until size @r{1×1×1}
798 is reached. At each level, each texel in the halved mipmap level is an
799 average of the corresponding eight texels in the larger mipmap level.
800 (If exactly one of the dimensions is 1, four texels are averaged. If
801 exactly two of the dimensions are 1, two texels are averaged.)
802 @code{glTexImage3D} is called to load these mipmap levels from
803 @var{base} to @var{max}. If @var{max} is larger than the highest mipmap
804 level for the texture of the specified size, then a GLU error code is
805 returned (see @code{gluErrorString}) and nothing is loaded.
807 For example, if @var{level} is 2 and @var{width} is 16, @var{height} is
808 8 and @var{depth} is 4, the following levels are possible: @r{16×8×4},
809 @r{8×4×2}, @r{4×2×1}, @r{2×1×1}, @r{1×1×1}. These correspond to levels 2
810 through 6 respectively. If @var{base} is 3 and @var{max} is 5, then only
811 mipmap levels @r{8×4×2}, @r{4×2×1}, and @r{2×1×1} are loaded. However,
812 if @var{max} is 7, then an error is returned and nothing is loaded,
813 since @var{max} is larger than the highest mipmap level which is, in
816 The highest mipmap level can be derived from the formula
817 @r{@var{log}_2(@var{max}(@var{width},@var{height}@var{depth})×2^@var{level},)}.
819 See the @code{glTexImage1D} reference page for a description of the
820 acceptable values for @var{format} parameter. See the
821 @code{glDrawPixels} reference page for a description of the acceptable
822 values for @var{type} parameter.
824 @code{GLU_INVALID_VALUE} is returned if @var{level} > @var{base},
825 @var{base} < 0, @var{max} < @var{base}, or @var{max} is > the highest
826 mipmap level for @var{data}.
828 @code{GLU_INVALID_VALUE} is returned if @var{width}, @var{height}, or
831 @code{GLU_INVALID_ENUM} is returned if @var{internalFormat},
832 @var{format}, or @var{type} is not legal.
834 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
835 @code{GLU_UNSIGNED_BYTE_3_3_2} or @code{GLU_UNSIGNED_BYTE_2_3_3_REV} and
836 @var{format} is not @code{GLU_RGB}.
838 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
839 @code{GLU_UNSIGNED_SHORT_5_6_5} or @code{GLU_UNSIGNED_SHORT_5_6_5_REV}
840 and @var{format} is not @code{GLU_RGB}.
842 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
843 @code{GLU_UNSIGNED_SHORT_4_4_4_4} or
844 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV} and @var{format} is neither
845 @code{GLU_RGBA} nor @code{GLU_BGRA}.
847 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
848 @code{GLU_UNSIGNED_SHORT_5_5_5_1} or
849 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV} and @var{format} is neither
850 @code{GLU_RGBA} nor @code{GLU_BGRA}.
852 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
853 @code{GLU_UNSIGNED_INT_8_8_8_8} or @code{GLU_UNSIGNED_INT_8_8_8_8_REV}
854 and @var{format} is neither @code{GLU_RGBA} nor @code{GLU_BGRA}.
856 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
857 @code{GLU_UNSIGNED_INT_10_10_10_2} or
858 @code{GLU_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
859 @code{GLU_RGBA} nor @code{GLU_BGRA}.
863 @deftypefun GLint gluBuild3DMipmaps target internalFormat width height depth format type data
864 Builds a three-dimensional mipmap.
868 Specifies the target texture. Must be @code{GLU_TEXTURE_3D}.
870 @item @var{internalFormat}
871 Requests the internal storage format of the texture image. The most
872 current version of the SGI implementation of GLU does not check this
873 value for validity before passing it on to the underlying OpenGL
874 implementation. A value that is not accepted by the OpenGL
875 implementation will lead to an OpenGL error. The benefit of not checking
876 this value at the GLU level is that OpenGL extensions can add new
877 internal texture formats without requiring a revision of the GLU
878 implementation. Older implementations of GLU check this value and raise
879 a GLU error if it is not 1, 2, 3, or 4 or one of the following symbolic
880 constants: @code{GLU_ALPHA}, @code{GLU_ALPHA4}, @code{GLU_ALPHA8},
881 @code{GLU_ALPHA12}, @code{GLU_ALPHA16}, @code{GLU_LUMINANCE},
882 @code{GLU_LUMINANCE4}, @code{GLU_LUMINANCE8}, @code{GLU_LUMINANCE12},
883 @code{GLU_LUMINANCE16}, @code{GLU_LUMINANCE_ALPHA},
884 @code{GLU_LUMINANCE4_ALPHA4}, @code{GLU_LUMINANCE6_ALPHA2},
885 @code{GLU_LUMINANCE8_ALPHA8}, @code{GLU_LUMINANCE12_ALPHA4},
886 @code{GLU_LUMINANCE12_ALPHA12}, @code{GLU_LUMINANCE16_ALPHA16},
887 @code{GLU_INTENSITY}, @code{GLU_INTENSITY4}, @code{GLU_INTENSITY8},
888 @code{GLU_INTENSITY12}, @code{GLU_INTENSITY16}, @code{GLU_RGB},
889 @code{GLU_R3_G3_B2}, @code{GLU_RGB4}, @code{GLU_RGB5}, @code{GLU_RGB8},
890 @code{GLU_RGB10}, @code{GLU_RGB12}, @code{GLU_RGB16}, @code{GLU_RGBA},
891 @code{GLU_RGBA2}, @code{GLU_RGBA4}, @code{GLU_RGB5_A1},
892 @code{GLU_RGBA8}, @code{GLU_RGB10_A2}, @code{GLU_RGBA12}, or
898 Specifies in pixels the width, height and depth respectively, in pixels
899 of the texture image.
902 Specifies the format of the pixel data. Must be one of
903 @code{GLU_COLOR_INDEX}, @code{GLU_DEPTH_COMPONENT}, @code{GLU_RED},
904 @code{GLU_GREEN}, @code{GLU_BLUE}, @code{GLU_ALPHA}, @code{GLU_RGB},
905 @code{GLU_RGBA}, @code{GLU_BGR}, @code{GLU_BGRA}, @code{GLU_LUMINANCE},
906 or @code{GLU_LUMINANCE_ALPHA}.
909 Specifies the data type for @var{data}. Must be one of:
910 @code{GLU_UNSIGNED_BYTE}, @code{GLU_BYTE}, @code{GLU_BITMAP},
911 @code{GLU_UNSIGNED_SHORT}, @code{GLU_SHORT}, @code{GLU_UNSIGNED_INT},
912 @code{GLU_INT}, @code{GLU_FLOAT}, @code{GLU_UNSIGNED_BYTE_3_3_2},
913 @code{GLU_UNSIGNED_BYTE_2_3_3_REV}, @code{GLU_UNSIGNED_SHORT_5_6_5},
914 @code{GLU_UNSIGNED_SHORT_5_6_5_REV}, @code{GLU_UNSIGNED_SHORT_4_4_4_4},
915 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV},
916 @code{GLU_UNSIGNED_SHORT_5_5_5_1},
917 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GLU_UNSIGNED_INT_8_8_8_8},
918 @code{GLU_UNSIGNED_INT_8_8_8_8_REV}, @code{GLU_UNSIGNED_INT_10_10_10_2},
919 or @code{GLU_UNSIGNED_INT_2_10_10_10_REV}.
922 Specifies a pointer to the image data in memory.
926 @code{gluBuild3DMipmaps} builds a series of prefiltered
927 three-dimensional texture maps of decreasing resolutions called a
928 mipmap. This is used for the antialiasing of texture-mapped primitives.
930 A return value of zero indicates success, otherwise a GLU error code is
931 returned (see @code{gluErrorString}).
933 Initially, the @var{width}, @var{height} and @var{depth} of @var{data}
934 are checked to see if they are a power of 2. If not, a copy of
935 @var{data} is made and scaled up or down to the nearest power of 2. (If
936 @var{width}, @var{height}, or @var{depth} is exactly between powers of
937 2, then the copy of @var{data} will scale upwards.) This copy will be
938 used for subsequent mipmapping operations described below. For example,
939 if @var{width} is 57, @var{height} is 23, and @var{depth} is 24, then a
940 copy of @var{data} will scale up to 64 in width, down to 16 in height,
941 and up to 32 in depth before mipmapping takes place.
943 Then, proxy textures (see @code{glTexImage3D}) are used to determine if
944 the implementation can fit the requested texture. If not, all three
945 dimensions are continually halved until it fits.
947 Next, a series of mipmap levels is built by decimating a copy of
948 @var{data} in half along all three dimensions until size @r{1×1×1} is
949 reached. At each level, each texel in the halved mipmap level is an
950 average of the corresponding eight texels in the larger mipmap level.
951 (If exactly one of the dimensions is 1, four texels are averaged. If
952 exactly two of the dimensions are 1, two texels are averaged.)
954 @code{glTexImage3D} is called to load each of these mipmap levels. Level
955 0 is a copy of @var{data}. The highest level is
956 @r{@var{log}_2,(@var{max}(@var{width},@var{height}@var{depth}),)}. For
957 example, if @var{width} is 64, @var{height} is 16, and @var{depth} is
958 32, and the implementation can store a texture of this size, the
959 following mipmap levels are built: @r{64×16×32}, @r{32×8×16},
960 @r{16×4×8}, @r{8×2×4}, @r{4×1×2}, @r{2×1×1}, and @r{1×1×1}. These
961 correspond to levels 0 through 6, respectively.
963 See the @code{glTexImage1D} reference page for a description of the
964 acceptable values for @var{format} parameter. See the
965 @code{glDrawPixels} reference page for a description of the acceptable
966 values for @var{type} parameter.
968 @code{GLU_INVALID_VALUE} is returned if @var{width}, @var{height}, or
971 @code{GLU_INVALID_ENUM} is returned if @var{internalFormat},
972 @var{format}, or @var{type} is not legal.
974 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
975 @code{GLU_UNSIGNED_BYTE_3_3_2} or @code{GLU_UNSIGNED_BYTE_2_3_3_REV} and
976 @var{format} is not @code{GLU_RGB}.
978 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
979 @code{GLU_UNSIGNED_SHORT_5_6_5} or @code{GLU_UNSIGNED_SHORT_5_6_5_REV}
980 and @var{format} is not @code{GLU_RGB}.
982 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
983 @code{GLU_UNSIGNED_SHORT_4_4_4_4} or
984 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV} and @var{format} is neither
985 @code{GLU_RGBA} nor @code{GLU_BGRA}.
987 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
988 @code{GLU_UNSIGNED_SHORT_5_5_5_1} or
989 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV} and @var{format} is neither
990 @code{GLU_RGBA} nor @code{GLU_BGRA}.
992 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
993 @code{GLU_UNSIGNED_INT_8_8_8_8} or @code{GLU_UNSIGNED_INT_8_8_8_8_REV}
994 and @var{format} is neither @code{GLU_RGBA} nor @code{GLU_BGRA}.
996 @code{GLU_INVALID_OPERATION} is returned if @var{type} is
997 @code{GLU_UNSIGNED_INT_10_10_10_2} or
998 @code{GLU_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
999 @code{GLU_RGBA} nor @code{GLU_BGRA}.
1003 @deftypefun GLboolean gluCheckExtension extName extString
1004 Determines if an extension name is supported.
1008 Specifies an extension name.
1010 @item @var{extString}
1011 Specifies a space-separated list of extension names supported.
1015 @code{gluCheckExtension} returns @code{GLU_TRUE} if @var{extName} is
1016 supported otherwise @code{GLU_FALSE} is returned.
1018 This is used to check for the presence for OpenGL, GLU, or GLX extension
1019 names by passing the extension strings returned by @code{glGetString},
1020 @code{gluGetString}, @code{glXGetClientString},
1021 @code{glXQueryExtensionsString}, or @code{glXQueryServerString},
1022 respectively, as @var{extString}.
1026 @deftypefun void gluCylinder quad base top height slices stacks
1031 Specifies the quadrics object (created with @code{gluNewQuadric}).
1034 Specifies the radius of the cylinder at @var{z} = 0.
1037 Specifies the radius of the cylinder at @var{z} = @var{height}.
1040 Specifies the height of the cylinder.
1043 Specifies the number of subdivisions around the @var{z} axis.
1046 Specifies the number of subdivisions along the @var{z} axis.
1050 @code{gluCylinder} draws a cylinder oriented along the @var{z} axis. The
1051 base of the cylinder is placed at @var{z} = 0 and the top at
1052 @r{@var{z}=@var{height}}. Like a sphere, a cylinder is subdivided around
1053 the @var{z} axis into slices and along the @var{z} axis into stacks.
1055 Note that if @var{top} is set to 0.0, this routine generates a cone.
1057 If the orientation is set to @code{GLU_OUTSIDE} (with
1058 @code{gluQuadricOrientation}), then any generated normals point away
1059 from the @var{z} axis. Otherwise, they point toward the @var{z} axis.
1061 If texturing is turned on (with @code{gluQuadricTexture}), then texture
1062 coordinates are generated so that @var{t} ranges linearly from 0.0 at
1063 @var{z} = 0 to 1.0 at @var{z} = @var{height}, and @var{s} ranges from
1064 0.0 at the +@var{y} axis, to 0.25 at the +@var{x} axis, to 0.5 at the
1065 -@var{y} axis, to 0.75 at the \-@var{x} axis, and back to 1.0 at the
1070 @deftypefun void gluDeleteNurbsRenderer nurb
1071 Destroy a NURBS object.
1075 Specifies the NURBS object to be destroyed.
1079 @code{gluDeleteNurbsRenderer} destroys the NURBS object (which was
1080 created with @code{gluNewNurbsRenderer}) and frees any memory it uses.
1081 Once @code{gluDeleteNurbsRenderer} has been called, @var{nurb} cannot be
1086 @deftypefun void gluDeleteQuadric quad
1087 Destroy a quadrics object.
1091 Specifies the quadrics object to be destroyed.
1095 @code{gluDeleteQuadric} destroys the quadrics object (created with
1096 @code{gluNewQuadric}) and frees any memory it uses. Once
1097 @code{gluDeleteQuadric} has been called, @var{quad} cannot be used
1102 @deftypefun void gluDeleteTess tess
1103 Destroy a tessellation object.
1107 Specifies the tessellation object to destroy.
1111 @code{gluDeleteTess} destroys the indicated tessellation object (which
1112 was created with @code{gluNewTess}) and frees any memory that it used.
1116 @deftypefun void gluDisk quad inner outer slices loops
1121 Specifies the quadrics object (created with @code{gluNewQuadric}).
1124 Specifies the inner radius of the disk (may be 0).
1127 Specifies the outer radius of the disk.
1130 Specifies the number of subdivisions around the @var{z} axis.
1133 Specifies the number of concentric rings about the origin into which the
1138 @code{gluDisk} renders a disk on the @var{z} = 0 plane. The disk has a
1139 radius of @var{outer} and contains a concentric circular hole with a
1140 radius of @var{inner}. If @var{inner} is 0, then no hole is generated.
1141 The disk is subdivided around the @var{z} axis into slices (like pizza
1142 slices) and also about the @var{z} axis into rings (as specified by
1143 @var{slices} and @var{loops}, respectively).
1145 With respect to orientation, the +@var{z} side of the disk is considered
1146 to be ``outside'' (see @code{gluQuadricOrientation}). This means that if
1147 the orientation is set to @code{GLU_OUTSIDE}, then any normals generated
1148 point along the +@var{z} axis. Otherwise, they point along the \-@var{z}
1151 If texturing has been turned on (with @code{gluQuadricTexture}), texture
1152 coordinates are generated linearly such that where
1153 @r{@var{r}=@var{outer}}, the value at (@var{r}, 0, 0) is (1, 0.5), at
1154 (0, @var{r}, 0) it is (0.5, 1), at (\-@var{r}, 0, 0) it is (0, 0.5), and
1155 at (0, \-@var{r}, 0) it is (0.5, 0).
1159 @deftypefun const-GLubyte-* gluErrorString error
1160 Produce an error string from a GL or GLU error code.
1164 Specifies a GL or GLU error code.
1168 @code{gluErrorString} produces an error string from a GL or GLU error
1169 code. The string is in ISO Latin 1 format. For example,
1170 @code{gluErrorString}(@code{GLU_OUT_OF_MEMORY}) returns the string
1171 @var{out of memory}.
1173 The standard GLU error codes are @code{GLU_INVALID_ENUM},
1174 @code{GLU_INVALID_VALUE}, and @code{GLU_OUT_OF_MEMORY}. Certain other
1175 GLU functions can return specialized error codes through callbacks. See
1176 the @code{glGetError} reference page for the list of GL error codes.
1178 @code{NULL} is returned if @var{error} is not a valid GL or GLU error
1183 @deftypefun void gluGetNurbsProperty nurb property data
1184 Get a NURBS property.
1188 Specifies the NURBS object (created with @code{gluNewNurbsRenderer}).
1190 @item @var{property}
1191 Specifies the property whose value is to be fetched. Valid values are
1192 @code{GLU_CULLING}, @code{GLU_SAMPLING_TOLERANCE},
1193 @code{GLU_DISPLAY_MODE}, @code{GLU_AUTO_LOAD_MATRIX},
1194 @code{GLU_PARAMETRIC_TOLERANCE}, @code{GLU_SAMPLING_METHOD},
1195 @code{GLU_U_STEP}, @code{GLU_V_STEP}, and @code{GLU_NURBS_MODE}.
1198 Specifies a pointer to the location into which the value of the named
1199 property is written.
1203 @code{gluGetNurbsProperty} retrieves properties stored in a NURBS
1204 object. These properties affect the way that NURBS curves and surfaces
1205 are rendered. See the @code{gluNurbsProperty} reference page for
1206 information about what the properties are and what they do.
1210 @deftypefun const-GLubyte-* gluGetString name
1211 Return a string describing the GLU version or GLU extensions .
1215 Specifies a symbolic constant, one of @code{GLU_VERSION}, or
1216 @code{GLU_EXTENSIONS}.
1220 @code{gluGetString} returns a pointer to a static string describing the
1221 GLU version or the GLU extensions that are supported.
1223 The version number is one of the following forms:
1225 @var{major_number.minor_number}@var{major_number.minor_number.release_number}.
1227 The version string is of the following form:
1229 @var{version number<space>vendor-specific information}
1231 Vendor-specific information is optional. Its format and contents depend
1232 on the implementation.
1234 The standard GLU contains a basic set of features and capabilities. If a
1235 company or group of companies wish to support other features, these may
1236 be included as extensions to the GLU. If @var{name} is
1237 @code{GLU_EXTENSIONS}, then @code{gluGetString} returns a
1238 space-separated list of names of supported GLU extensions. (Extension
1239 names never contain spaces.)
1241 All strings are null-terminated.
1243 NULL is returned if @var{name} is not @code{GLU_VERSION} or
1244 @code{GLU_EXTENSIONS}.
1250 @deftypefun void gluGetTessProperty tess which data
1251 Get a tessellation object property.
1255 Specifies the tessellation object (created with @code{gluNewTess}).
1258 Specifies the property whose value is to be fetched. Valid values are
1259 @code{GLU_TESS_WINDING_RULE}, @code{GLU_TESS_BOUNDARY_ONLY}, and
1260 @code{GLU_TESS_TOLERANCE}.
1263 Specifies a pointer to the location into which the value of the named
1264 property is written.
1268 @code{gluGetTessProperty} retrieves properties stored in a tessellation
1269 object. These properties affect the way that tessellation objects are
1270 interpreted and rendered. See the @code{gluTessProperty} reference page
1271 for information about the properties and what they do.
1275 @deftypefun void gluLoadSamplingMatrices nurb model perspective view
1276 Load NURBS sampling and culling matrices.
1280 Specifies the NURBS object (created with @code{gluNewNurbsRenderer}).
1283 Specifies a modelview matrix (as from a @code{glGetFloatv} call).
1285 @item @var{perspective}
1286 Specifies a projection matrix (as from a @code{glGetFloatv} call).
1289 Specifies a viewport (as from a @code{glGetIntegerv} call).
1293 @code{gluLoadSamplingMatrices} uses @var{model}, @var{perspective}, and
1294 @var{view} to recompute the sampling and culling matrices stored in
1295 @var{nurb}. The sampling matrix determines how finely a NURBS curve or
1296 surface must be tessellated to satisfy the sampling tolerance (as
1297 determined by the @code{GLU_SAMPLING_TOLERANCE} property). The culling
1298 matrix is used in deciding if a NURBS curve or surface should be culled
1299 before rendering (when the @code{GLU_CULLING} property is turned on).
1301 @code{gluLoadSamplingMatrices} is necessary only if the
1302 @code{GLU_AUTO_LOAD_MATRIX} property is turned off (see
1303 @code{gluNurbsProperty}). Although it can be convenient to leave the
1304 @code{GLU_AUTO_LOAD_MATRIX} property turned on, there can be a
1305 performance penalty for doing so. (A round trip to the GL server is
1306 needed to fetch the current values of the modelview matrix, projection
1307 matrix, and viewport.)
1311 @deftypefun void gluLookAt eyeX eyeY eyeZ centerX centerY centerZ upX upY upZ
1312 Define a viewing transformation.
1318 Specifies the position of the eye point.
1321 @itemx @var{centerY}
1322 @itemx @var{centerZ}
1323 Specifies the position of the reference point.
1328 Specifies the direction of the @var{up} vector.
1332 @code{gluLookAt} creates a viewing matrix derived from an eye point, a
1333 reference point indicating the center of the scene, and an @var{UP}
1336 The matrix maps the reference point to the negative @var{z} axis and the
1337 eye point to the origin. When a typical projection matrix is used, the
1338 center of the scene therefore maps to the center of the viewport.
1339 Similarly, the direction described by the @var{UP} vector projected onto
1340 the viewing plane is mapped to the positive @var{y} axis so that it
1341 points upward in the viewport. The @var{UP} vector must not be parallel
1342 to the line of sight from the eye point to the reference point.
1346 @r{@var{F}=((@var{centerX}-@var{eyeX}), (@var{centerY}-@var{eyeY}),
1347 (@var{centerZ}-@var{eyeZ}),)}
1351 Let @var{UP} be the vector @r{(@var{upX},@var{upY}@var{upZ})}.
1353 Then normalize as follows: @r{@var{f}=@var{F}/∥@var{F},∥,}
1355 @r{@var{UP}^″=@var{UP}/∥@var{UP},∥,}
1359 Finally, let @r{@var{s}=@var{f}×@var{UP}^″}, and
1360 @r{@var{u}=@var{s}×@var{f}}.
1364 M is then constructed as follows: @r{@var{M}=((@var{s}[0,] @var{s}[1,]
1365 @var{s}[2,] 0), (@var{u}[0,] @var{u}[1,] @var{u}[2,] 0),
1366 (-@var{f}[0,] -@var{f}[1,] -@var{f}[2,] 0), (0 0 0 1),)}
1368 and @code{gluLookAt} is equivalent to
1373 glTranslated(-eyex, -eyey, -eyez);
1378 @deftypefun GLUnurbs* gluNewNurbsRenderer
1379 Create a NURBS object.
1381 @code{gluNewNurbsRenderer} creates and returns a pointer to a new NURBS
1382 object. This object must be referred to when calling NURBS rendering and
1383 control functions. A return value of 0 means that there is not enough
1384 memory to allocate the object.
1388 @deftypefun GLUquadric* gluNewQuadric
1389 Create a quadrics object.
1391 @code{gluNewQuadric} creates and returns a pointer to a new quadrics
1392 object. This object must be referred to when calling quadrics rendering
1393 and control functions. A return value of 0 means that there is not
1394 enough memory to allocate the object.
1398 @deftypefun GLUtesselator* gluNewTess
1399 Create a tessellation object.
1401 @code{gluNewTess} creates and returns a pointer to a new tessellation
1402 object. This object must be referred to when calling tessellation
1403 functions. A return value of 0 means that there is not enough memory to
1404 allocate the object.
1408 @deftypefun void gluNextContour tess type
1409 Mark the beginning of another contour.
1413 Specifies the tessellation object (created with @code{gluNewTess}).
1416 Specifies the type of the contour being defined. Valid values are
1417 @code{GLU_EXTERIOR}, @code{GLU_INTERIOR}, @code{GLU_UNKNOWN},
1418 @code{GLU_CCW}, and @code{GLU_CW}.
1422 @code{gluNextContour} is used in describing polygons with multiple
1423 contours. After the first contour has been described through a series of
1424 @code{gluTessVertex} calls, a @code{gluNextContour} call indicates that
1425 the previous contour is complete and that the next contour is about to
1426 begin. Another series of @code{gluTessVertex} calls is then used to
1427 describe the new contour. This process can be repeated until all
1428 contours have been described.
1430 @var{type} defines what type of contour follows. The legal contour types
1434 @item @code{GLU_EXTERIOR}
1435 An exterior contour defines an exterior boundary of the polygon.
1437 @item @code{GLU_INTERIOR}
1438 An interior contour defines an interior boundary of the polygon (such as
1441 @item @code{GLU_UNKNOWN}
1442 An unknown contour is analyzed by the library to determine if it is
1443 interior or exterior.
1445 @item @code{GLU_CCW},
1447 The first @code{GLU_CCW} or @code{GLU_CW} contour defined is considered
1448 to be exterior. All other contours are considered to be exterior if they
1449 are oriented in the same direction (clockwise or counterclockwise) as
1450 the first contour, and interior if they are not.
1454 If one contour is of type @code{GLU_CCW} or @code{GLU_CW}, then all
1455 contours must be of the same type (if they are not, then all
1456 @code{GLU_CCW} and @code{GLU_CW} contours will be changed to
1457 @code{GLU_UNKNOWN}).
1459 Note that there is no real difference between the @code{GLU_CCW} and
1460 @code{GLU_CW} contour types.
1462 Before the first contour is described, @code{gluNextContour} can be
1463 called to define the type of the first contour. If @code{gluNextContour}
1464 is not called before the first contour, then the first contour is marked
1465 @code{GLU_EXTERIOR}.
1467 This command is obsolete and is provided for backward compatibility
1468 only. Calls to @code{gluNextContour} are mapped to
1469 @code{gluTessEndContour} followed by @code{gluTessBeginContour}.
1473 @deftypefun void gluNurbsCallbackDataEXT nurb userData
1474 Set a user data pointer.
1478 Specifies the NURBS object (created with @code{gluNewNurbsRenderer}).
1480 @item @var{userData}
1481 Specifies a pointer to the user's data.
1485 @code{gluNurbsCallbackDataEXT} is used to pass a pointer to the
1486 application's data to NURBS tessellator. A copy of this pointer will be
1487 passed by the tessellator in the NURBS callback functions (set by
1488 @code{gluNurbsCallback}).
1492 @deftypefun void gluNurbsCallbackData nurb userData
1493 Set a user data pointer.
1497 Specifies the NURBS object (created with @code{gluNewNurbsRenderer}).
1499 @item @var{userData}
1500 Specifies a pointer to the user's data.
1504 @code{gluNurbsCallbackData} is used to pass a pointer to the
1505 application's data to NURBS tessellator. A copy of this pointer will be
1506 passed by the tessellator in the NURBS callback functions (set by
1507 @code{gluNurbsCallback}).
1511 @deftypefun void gluNurbsCallback nurb which CallBackFunc
1512 Define a callback for a NURBS object.
1516 Specifies the NURBS object (created with @code{gluNewNurbsRenderer}).
1519 Specifies the callback being defined. Valid values are
1520 @code{GLU_NURBS_BEGIN}, @code{GLU_NURBS_VERTEX},
1521 @code{GLU_NURBS_NORMAL}, @code{GLU_NURBS_COLOR},
1522 @code{GLU_NURBS_TEXTURE_COORD}, @code{GLU_NURBS_END},
1523 @code{GLU_NURBS_BEGIN_DATA}, @code{GLU_NURBS_VERTEX_DATA},
1524 @code{GLU_NURBS_NORMAL_DATA}, @code{GLU_NURBS_COLOR_DATA},
1525 @code{GLU_NURBS_TEXTURE_COORD_DATA}, @code{GLU_NURBS_END_DATA}, and
1526 @code{GLU_NURBS_ERROR}.
1528 @item @var{CallBackFunc}
1529 Specifies the function that the callback calls.
1533 @code{gluNurbsCallback} is used to define a callback to be used by a
1534 NURBS object. If the specified callback is already defined, then it is
1535 replaced. If @var{CallBackFunc} is NULL, then this callback will not get
1536 invoked and the related data, if any, will be lost.
1538 Except the error callback, these callbacks are used by NURBS tessellator
1539 (when @code{GLU_NURBS_MODE} is set to be @code{GLU_NURBS_TESSELLATOR})
1540 to return back the OpenGL polygon primitives resulting from the
1541 tessellation. Note that there are two versions of each callback: one
1542 with a user data pointer and one without. If both versions for a
1543 particular callback are specified then the callback with the user data
1544 pointer will be used. Note that ``userData'' is a copy of the pointer
1545 that was specified at the last call to @code{gluNurbsCallbackData}.
1547 The error callback function is effective no matter which value that
1548 @code{GLU_NURBS_MODE} is set to. All other callback functions are
1549 effective only when @code{GLU_NURBS_MODE} is set to
1550 @code{GLU_NURBS_TESSELLATOR}.
1552 The legal callbacks are as follows:
1555 @item @code{GLU_NURBS_BEGIN}
1558 The begin callback indicates the start of a primitive. The function
1559 takes a single argument of type GLenum, which can be one of
1560 @code{GLU_LINES}, @code{GLU_LINE_STRIP}, @code{GLU_TRIANGLE_FAN},
1561 @code{GLU_TRIANGLE_STRIP}, @code{GLU_TRIANGLES}, or
1562 @code{GLU_QUAD_STRIP}. The default begin callback function is NULL. The
1563 function prototype for this callback looks like:
1565 @item @code{GLU_NURBS_BEGIN_DATA}
1568 The same as the @code{GLU_NURBS_BEGIN} callback except that it takes an
1569 additional pointer argument. This pointer is a copy of the pointer that
1570 was specified at the last call to @code{gluNurbsCallbackData}. The
1571 default callback function is NULL. The function prototype for this
1572 callback function looks like:
1574 @item @code{GLU_NURBS_VERTEX}
1577 The vertex callback indicates a vertex of the primitive. The coordinates
1578 of the vertex are stored in the parameter ``vertex''. All the generated
1579 vertices have dimension 3; that is, homogeneous coordinates have been
1580 transformed into affine coordinates. The default vertex callback
1581 function is NULL. The function prototype for this callback function
1584 @item @code{GLU_NURBS_VERTEX_DATA}
1587 This is the same as the @code{GLU_NURBS_VERTEX} callback, except that it
1588 takes an additional pointer argument. This pointer is a copy of the
1589 pointer that was specified at the last call to
1590 @code{gluNurbsCallbackData}. The default callback function is NULL. The
1591 function prototype for this callback function looks like:
1593 @item @code{GLU_NURBS_NORMAL}
1596 The normal callback is invoked as the vertex normal is generated. The
1597 components of the normal are stored in the parameter ``normal.'' In the
1598 case of a NURBS curve, the callback function is effective only when the
1599 user provides a normal map (@code{GLU_MAP1_NORMAL}). In the case of a
1600 NURBS surface, if a normal map (@code{GLU_MAP2_NORMAL}) is provided,
1601 then the generated normal is computed from the normal map. If a normal
1602 map is not provided, then a surface normal is computed in a manner
1603 similar to that described for evaluators when @code{GLU_AUTO_NORMAL} is
1604 enabled. The default normal callback function is NULL. The function
1605 prototype for this callback function looks like:
1607 @item @code{GLU_NURBS_NORMAL_DATA}
1610 The same as the @code{GLU_NURBS_NORMAL} callback except that it takes an
1611 additional pointer argument. This pointer is a copy of the pointer that
1612 was specified at the last call to @code{gluNurbsCallbackData}. The
1613 default callback function is NULL. The function prototype for this
1614 callback function looks like:
1616 @item @code{GLU_NURBS_COLOR}
1619 The color callback is invoked as the color of a vertex is generated. The
1620 components of the color are stored in the parameter ``color.'' This
1621 callback is effective only when the user provides a color map
1622 (@code{GLU_MAP1_COLOR_4} or @code{GLU_MAP2_COLOR_4}). ``color'' contains
1623 four components: R, G, B, A. The default color callback function is
1624 NULL. The prototype for this callback function looks like:
1626 @item @code{GLU_NURBS_COLOR_DATA}
1629 The same as the @code{GLU_NURBS_COLOR} callback except that it takes an
1630 additional pointer argument. This pointer is a copy of the pointer that
1631 was specified at the last call to @code{gluNurbsCallbackData}. The
1632 default callback function is NULL. The function prototype for this
1633 callback function looks like:
1635 @item @code{GLU_NURBS_TEXTURE_COORD}
1638 The texture callback is invoked as the texture coordinates of a vertex
1639 are generated. These coordinates are stored in the parameter
1640 ``texCoord.'' The number of texture coordinates can be 1, 2, 3, or 4
1641 depending on which type of texture map is specified
1642 (@code{GLU_MAP1_TEXTURE_COORD_1}, @code{GLU_MAP1_TEXTURE_COORD_2},
1643 @code{GLU_MAP1_TEXTURE_COORD_3}, @code{GLU_MAP1_TEXTURE_COORD_4},
1644 @code{GLU_MAP2_TEXTURE_COORD_1}, @code{GLU_MAP2_TEXTURE_COORD_2},
1645 @code{GLU_MAP2_TEXTURE_COORD_3}, @code{GLU_MAP2_TEXTURE_COORD_4}). If no
1646 texture map is specified, this callback function will not be called. The
1647 default texture callback function is NULL. The function prototype for
1648 this callback function looks like:
1650 @item @code{GLU_NURBS_TEXTURE_COORD_DATA}
1653 This is the same as the @code{GLU_NURBS_TEXTURE_COORD} callback, except
1654 that it takes an additional pointer argument. This pointer is a copy of
1655 the pointer that was specified at the last call to
1656 @code{gluNurbsCallbackData}. The default callback function is NULL. The
1657 function prototype for this callback function looks like:
1659 @item @code{GLU_NURBS_END}
1662 The end callback is invoked at the end of a primitive. The default end
1663 callback function is NULL. The function prototype for this callback
1664 function looks like:
1666 @item @code{GLU_NURBS_END_DATA}
1669 This is the same as the @code{GLU_NURBS_END} callback, except that it
1670 takes an additional pointer argument. This pointer is a copy of the
1671 pointer that was specified at the last call to
1672 @code{gluNurbsCallbackData}. The default callback function is NULL. The
1673 function prototype for this callback function looks like:
1675 @item @code{GLU_NURBS_ERROR}
1678 The error function is called when an error is encountered. Its single
1679 argument is of type GLenum, and it indicates the specific error that
1680 occurred. There are 37 errors unique to NURBS, named
1681 @code{GLU_NURBS_ERROR1} through @code{GLU_NURBS_ERROR37}. Character
1682 strings describing these errors can be retrieved with
1683 @code{gluErrorString}.
1689 void begin( GLenum type );
1694 void beginData(GLenum type, void *userData);
1699 void vertex( GLfloat *vertex );
1704 void vertexData( GLfloat *vertex, void *userData );
1709 void normal( GLfloat *normal );
1714 void normalData( GLfloat *normal, void *userData );
1719 void color( GLfloat *color );
1724 void colorData( GLfloat *color, void *userData );
1729 void texCoord( GLfloat *texCoord );
1734 void texCoordData( GLfloat *texCoord, void *userData );
1744 void endData( void *userData );
1749 @deftypefun void gluNurbsCurve nurb knotCount knots stride control order type
1750 Define the shape of a NURBS curve.
1754 Specifies the NURBS object (created with @code{gluNewNurbsRenderer}).
1756 @item @var{knotCount}
1757 Specifies the number of knots in @var{knots}. @var{knotCount} equals the
1758 number of control points plus the order.
1761 Specifies an array of @var{knotCount} nondecreasing knot values.
1764 Specifies the offset (as a number of single-precision floating-point
1765 values) between successive curve control points.
1768 Specifies a pointer to an array of control points. The coordinates must
1769 agree with @var{type}, specified below.
1772 Specifies the order of the NURBS curve. @var{order} equals degree + 1,
1773 hence a cubic curve has an order of 4.
1776 Specifies the type of the curve. If this curve is defined within a
1777 @code{gluBeginCurve}/@code{gluEndCurve} pair, then the type can be any
1778 of the valid one-dimensional evaluator types (such as
1779 @code{GLU_MAP1_VERTEX_3} or @code{GLU_MAP1_COLOR_4}). Between a
1780 @code{gluBeginTrim}/@code{gluEndTrim} pair, the only valid types are
1781 @code{GLU_MAP1_TRIM_2} and @code{GLU_MAP1_TRIM_3}.
1785 Use @code{gluNurbsCurve} to describe a NURBS curve.
1787 When @code{gluNurbsCurve} appears between a
1788 @code{gluBeginCurve}/@code{gluEndCurve} pair, it is used to describe a
1789 curve to be rendered. Positional, texture, and color coordinates are
1790 associated by presenting each as a separate @code{gluNurbsCurve} between
1791 a @code{gluBeginCurve}/@code{gluEndCurve} pair. No more than one call to
1792 @code{gluNurbsCurve} for each of color, position, and texture data can
1793 be made within a single @code{gluBeginCurve}/@code{gluEndCurve} pair.
1794 Exactly one call must be made to describe the position of the curve (a
1795 @var{type} of @code{GLU_MAP1_VERTEX_3} or @code{GLU_MAP1_VERTEX_4}).
1797 When @code{gluNurbsCurve} appears between a
1798 @code{gluBeginTrim}/@code{gluEndTrim} pair, it is used to describe a
1799 trimming curve on a NURBS surface. If @var{type} is
1800 @code{GLU_MAP1_TRIM_2}, then it describes a curve in two-dimensional
1801 (@var{u} and @var{v}) parameter space. If it is @code{GLU_MAP1_TRIM_3},
1802 then it describes a curve in two-dimensional homogeneous (@var{u},
1803 @var{v}, and @var{w}) parameter space. See the @code{gluBeginTrim}
1804 reference page for more discussion about trimming curves.
1808 @deftypefun void gluNurbsProperty nurb property value
1809 Set a NURBS property.
1813 Specifies the NURBS object (created with @code{gluNewNurbsRenderer}).
1815 @item @var{property}
1816 Specifies the property to be set. Valid values are
1817 @code{GLU_SAMPLING_TOLERANCE}, @code{GLU_DISPLAY_MODE},
1818 @code{GLU_CULLING}, @code{GLU_AUTO_LOAD_MATRIX},
1819 @code{GLU_PARAMETRIC_TOLERANCE}, @code{GLU_SAMPLING_METHOD},
1820 @code{GLU_U_STEP}, @code{GLU_V_STEP}, or @code{GLU_NURBS_MODE}.
1823 Specifies the value of the indicated property. It may be a numeric value
1824 or one of @code{GLU_OUTLINE_POLYGON}, @code{GLU_FILL},
1825 @code{GLU_OUTLINE_PATCH}, @code{GLU_TRUE}, @code{GLU_FALSE},
1826 @code{GLU_PATH_LENGTH}, @code{GLU_PARAMETRIC_ERROR},
1827 @code{GLU_DOMAIN_DISTANCE}, @code{GLU_NURBS_RENDERER}, or
1828 @code{GLU_NURBS_TESSELLATOR}.
1832 @code{gluNurbsProperty} is used to control properties stored in a NURBS
1833 object. These properties affect the way that a NURBS curve is rendered.
1834 The accepted values for @var{property} are as follows:
1837 @item @code{GLU_NURBS_MODE}
1838 @var{value} should be set to be either @code{GLU_NURBS_RENDERER} or
1839 @code{GLU_NURBS_TESSELLATOR}. When set to @code{GLU_NURBS_RENDERER},
1840 NURBS objects are tessellated into OpenGL primitives and sent to the
1841 pipeline for rendering. When set to @code{GLU_NURBS_TESSELLATOR}, NURBS
1842 objects are tessellated into OpenGL primitives but the vertices,
1843 normals, colors, and/or textures are retrieved back through a callback
1844 interface (see @code{gluNurbsCallback}). This allows the user to cache
1845 the tessellated results for further processing. The initial value is
1846 @code{GLU_NURBS_RENDERER}.
1848 @item @code{GLU_SAMPLING_METHOD}
1849 Specifies how a NURBS surface should be tessellated. @var{value} may be
1850 one of @code{GLU_PATH_LENGTH}, @code{GLU_PARAMETRIC_ERROR},
1851 @code{GLU_DOMAIN_DISTANCE}, @code{GLU_OBJECT_PATH_LENGTH}, or
1852 @code{GLU_OBJECT_PARAMETRIC_ERROR}. When set to @code{GLU_PATH_LENGTH},
1853 the surface is rendered so that the maximum length, in pixels, of the
1854 edges of the tessellation polygons is no greater than what is specified
1855 by @code{GLU_SAMPLING_TOLERANCE}.
1857 @code{GLU_PARAMETRIC_ERROR} specifies that the surface is rendered in
1858 such a way that the value specified by @code{GLU_PARAMETRIC_TOLERANCE}
1859 describes the maximum distance, in pixels, between the tessellation
1860 polygons and the surfaces they approximate.
1862 @code{GLU_DOMAIN_DISTANCE} allows users to specify, in parametric
1863 coordinates, how many sample points per unit length are taken in
1864 @var{u}, @var{v} direction.
1866 @code{GLU_OBJECT_PATH_LENGTH} is similar to @code{GLU_PATH_LENGTH}
1867 except that it is view independent; that is, the surface is rendered so
1868 that the maximum length, in object space, of edges of the tessellation
1869 polygons is no greater than what is specified by
1870 @code{GLU_SAMPLING_TOLERANCE}.
1872 @code{GLU_OBJECT_PARAMETRIC_ERROR} is similar to
1873 @code{GLU_PARAMETRIC_ERROR} except that it is view independent; that is,
1874 the surface is rendered in such a way that the value specified by
1875 @code{GLU_PARAMETRIC_TOLERANCE} describes the maximum distance, in
1876 object space, between the tessellation polygons and the surfaces they
1879 The initial value of @code{GLU_SAMPLING_METHOD} is
1880 @code{GLU_PATH_LENGTH}.
1882 @item @code{GLU_SAMPLING_TOLERANCE}
1883 Specifies the maximum length, in pixels or in object space length unit,
1884 to use when the sampling method is set to @code{GLU_PATH_LENGTH} or
1885 @code{GLU_OBJECT_PATH_LENGTH}. The NURBS code is conservative when
1886 rendering a curve or surface, so the actual length can be somewhat
1887 shorter. The initial value is 50.0 pixels.
1889 @item @code{GLU_PARAMETRIC_TOLERANCE}
1890 Specifies the maximum distance, in pixels or in object space length
1891 unit, to use when the sampling method is @code{GLU_PARAMETRIC_ERROR} or
1892 @code{GLU_OBJECT_PARAMETRIC_ERROR}. The initial value is 0.5.
1894 @item @code{GLU_U_STEP}
1895 Specifies the number of sample points per unit length taken along the
1896 @var{u} axis in parametric coordinates. It is needed when
1897 @code{GLU_SAMPLING_METHOD} is set to @code{GLU_DOMAIN_DISTANCE}. The
1898 initial value is 100.
1900 @item @code{GLU_V_STEP}
1901 Specifies the number of sample points per unit length taken along the
1902 @var{v} axis in parametric coordinate. It is needed when
1903 @code{GLU_SAMPLING_METHOD} is set to @code{GLU_DOMAIN_DISTANCE}. The
1904 initial value is 100.
1906 @item @code{GLU_DISPLAY_MODE}
1907 @var{value} can be set to @code{GLU_OUTLINE_POLYGON}, @code{GLU_FILL},
1908 or @code{GLU_OUTLINE_PATCH}. When @code{GLU_NURBS_MODE} is set to be
1909 @code{GLU_NURBS_RENDERER}, @var{value} defines how a NURBS surface
1910 should be rendered. When @var{value} is set to @code{GLU_FILL}, the
1911 surface is rendered as a set of polygons. When @var{value} is set to
1912 @code{GLU_OUTLINE_POLYGON}, the NURBS library draws only the outlines of
1913 the polygons created by tessellation. When @var{value} is set to
1914 @code{GLU_OUTLINE_PATCH} just the outlines of patches and trim curves
1915 defined by the user are drawn.
1917 When @code{GLU_NURBS_MODE} is set to be @code{GLU_NURBS_TESSELLATOR},
1918 @var{value} defines how a NURBS surface should be tessellated. When
1919 @code{GLU_DISPLAY_MODE} is set to @code{GLU_FILL} or
1920 @code{GLU_OUTLINE_POLYGON}, the NURBS surface is tessellated into OpenGL
1921 triangle primitives that can be retrieved back through callback
1922 functions. If @code{GLU_DISPLAY_MODE} is set to
1923 @code{GLU_OUTLINE_PATCH}, only the outlines of the patches and trim
1924 curves are generated as a sequence of line strips that can be retrieved
1925 back through callback functions.
1927 The initial value is @code{GLU_FILL}.
1929 @item @code{GLU_CULLING}
1930 @var{value} is a boolean value that, when set to @code{GLU_TRUE},
1931 indicates that a NURBS curve should be discarded prior to tessellation
1932 if its control points lie outside the current viewport. The initial
1933 value is @code{GLU_FALSE}.
1935 @item @code{GLU_AUTO_LOAD_MATRIX}
1936 @var{value} is a boolean value. When set to @code{GLU_TRUE}, the NURBS
1937 code downloads the projection matrix, the modelview matrix, and the
1938 viewport from the GL server to compute sampling and culling matrices for
1939 each NURBS curve that is rendered. Sampling and culling matrices are
1940 required to determine the tessellation of a NURBS surface into line
1941 segments or polygons and to cull a NURBS surface if it lies outside the
1944 If this mode is set to @code{GLU_FALSE}, then the program needs to
1945 provide a projection matrix, a modelview matrix, and a viewport for the
1946 NURBS renderer to use to construct sampling and culling matrices. This
1947 can be done with the @code{gluLoadSamplingMatrices} function. This mode
1948 is initially set to @code{GLU_TRUE}. Changing it from @code{GLU_TRUE} to
1949 @code{GLU_FALSE} does not affect the sampling and culling matrices until
1950 @code{gluLoadSamplingMatrices} is called.
1956 @deftypefun void gluNurbsSurface nurb sKnotCount sKnots tKnotCount tKnots sStride tStride control sOrder tOrder type
1957 Define the shape of a NURBS surface.
1961 Specifies the NURBS object (created with @code{gluNewNurbsRenderer}).
1963 @item @var{sKnotCount}
1964 Specifies the number of knots in the parametric @var{u} direction.
1967 Specifies an array of @var{sKnotCount} nondecreasing knot values in the
1968 parametric @var{u} direction.
1970 @item @var{tKnotCount}
1971 Specifies the number of knots in the parametric @var{v} direction.
1974 Specifies an array of @var{tKnotCount} nondecreasing knot values in the
1975 parametric @var{v} direction.
1978 Specifies the offset (as a number of single-precision floating-point
1979 values) between successive control points in the parametric @var{u}
1980 direction in @var{control}.
1983 Specifies the offset (in single-precision floating-point values) between
1984 successive control points in the parametric @var{v} direction in
1988 Specifies an array containing control points for the NURBS surface. The
1989 offsets between successive control points in the parametric @var{u} and
1990 @var{v} directions are given by @var{sStride} and @var{tStride}.
1993 Specifies the order of the NURBS surface in the parametric @var{u}
1994 direction. The order is one more than the degree, hence a surface that
1995 is cubic in @var{u} has a @var{u} order of 4.
1998 Specifies the order of the NURBS surface in the parametric @var{v}
1999 direction. The order is one more than the degree, hence a surface that
2000 is cubic in @var{v} has a @var{v} order of 4.
2003 Specifies type of the surface. @var{type} can be any of the valid
2004 two-dimensional evaluator types (such as @code{GLU_MAP2_VERTEX_3} or
2005 @code{GLU_MAP2_COLOR_4}).
2009 Use @code{gluNurbsSurface} within a NURBS (Non-Uniform Rational
2010 B-Spline) surface definition to describe the shape of a NURBS surface
2011 (before any trimming). To mark the beginning of a NURBS surface
2012 definition, use the @code{gluBeginSurface} command. To mark the end of a
2013 NURBS surface definition, use the @code{gluEndSurface} command. Call
2014 @code{gluNurbsSurface} within a NURBS surface definition only.
2016 Positional, texture, and color coordinates are associated with a surface
2017 by presenting each as a separate @code{gluNurbsSurface} between a
2018 @code{gluBeginSurface}/@code{gluEndSurface} pair. No more than one call
2019 to @code{gluNurbsSurface} for each of color, position, and texture data
2020 can be made within a single @code{gluBeginSurface}/@code{gluEndSurface}
2021 pair. Exactly one call must be made to describe the position of the
2022 surface (a @var{type} of @code{GLU_MAP2_VERTEX_3} or
2023 @code{GLU_MAP2_VERTEX_4}).
2025 A NURBS surface can be trimmed by using the commands
2026 @code{gluNurbsCurve} and @code{gluPwlCurve} between calls to
2027 @code{gluBeginTrim} and @code{gluEndTrim}.
2029 Note that a @code{gluNurbsSurface} with @var{sKnotCount} knots in the
2030 @var{u} direction and @var{tKnotCount} knots in the @var{v} direction
2031 with orders @var{sOrder} and @var{tOrder} must have (@var{sKnotCount} -
2032 @var{sOrder}) @r{@var{times}} (@var{tKnotCount} - @var{tOrder}) control
2037 @deftypefun void gluOrtho2D left right bottom top
2038 Define a 2D orthographic projection matrix.
2043 Specify the coordinates for the left and right vertical clipping planes.
2047 Specify the coordinates for the bottom and top horizontal clipping
2052 @code{gluOrtho2D} sets up a two-dimensional orthographic viewing region.
2053 This is equivalent to calling @code{glOrtho} with @r{@var{near}=-1} and
2058 @deftypefun void gluPartialDisk quad inner outer slices loops start sweep
2059 Draw an arc of a disk.
2063 Specifies a quadrics object (created with @code{gluNewQuadric}).
2066 Specifies the inner radius of the partial disk (can be 0).
2069 Specifies the outer radius of the partial disk.
2072 Specifies the number of subdivisions around the @var{z} axis.
2075 Specifies the number of concentric rings about the origin into which the
2076 partial disk is subdivided.
2079 Specifies the starting angle, in degrees, of the disk portion.
2082 Specifies the sweep angle, in degrees, of the disk portion.
2086 @code{gluPartialDisk} renders a partial disk on the @r{@var{z}=0} plane.
2087 A partial disk is similar to a full disk, except that only the subset of
2088 the disk from @var{start} through @var{start} + @var{sweep} is included
2089 (where 0 degrees is along the +\f2y\f axis, 90 degrees along the
2090 +@var{x} axis, 180 degrees along the \-@var{y} axis, and 270 degrees
2091 along the \-@var{x} axis).
2093 The partial disk has a radius of @var{outer} and contains a concentric
2094 circular hole with a radius of @var{inner}. If @var{inner} is 0, then no
2095 hole is generated. The partial disk is subdivided around the @var{z}
2096 axis into slices (like pizza slices) and also about the @var{z} axis
2097 into rings (as specified by @var{slices} and @var{loops}, respectively).
2099 With respect to orientation, the +@var{z} side of the partial disk is
2100 considered to be outside (see @code{gluQuadricOrientation}). This means
2101 that if the orientation is set to @code{GLU_OUTSIDE}, then any normals
2102 generated point along the +@var{z} axis. Otherwise, they point along the
2105 If texturing is turned on (with @code{gluQuadricTexture}), texture
2106 coordinates are generated linearly such that where
2107 @r{@var{r}=@var{outer}}, the value at (@var{r}, 0, 0) is (1.0, 0.5), at
2108 (0, @var{r}, 0) it is (0.5, 1.0), at (\-@var{r}, 0, 0) it is (0.0, 0.5),
2109 and at (0, \-@var{r}, 0) it is (0.5, 0.0).
2113 @deftypefun void gluPerspective fovy aspect zNear zFar
2114 Set up a perspective projection matrix.
2118 Specifies the field of view angle, in degrees, in the @var{y} direction.
2121 Specifies the aspect ratio that determines the field of view in the
2122 @var{x} direction. The aspect ratio is the ratio of @var{x} (width) to
2126 Specifies the distance from the viewer to the near clipping plane
2130 Specifies the distance from the viewer to the far clipping plane (always
2135 @code{gluPerspective} specifies a viewing frustum into the world
2136 coordinate system. In general, the aspect ratio in @code{gluPerspective}
2137 should match the aspect ratio of the associated viewport. For example,
2138 @r{@var{aspect}=2.0} means the viewer's angle of view is twice as wide
2139 in @var{x} as it is in @var{y}. If the viewport is twice as wide as it
2140 is tall, it displays the image without distortion.
2142 The matrix generated by @code{gluPerspective} is multipled by the
2143 current matrix, just as if @code{glMultMatrix} were called with the
2144 generated matrix. To load the perspective matrix onto the current matrix
2145 stack instead, precede the call to @code{gluPerspective} with a call to
2146 @code{glLoadIdentity}.
2148 Given @var{f} defined as follows:
2150 @r{@var{f}=@var{cotangent}(@var{fovy}/2,)} The generated matrix is
2152 @r{((@var{f}/@var{aspect} 0 0 0), (0 @var{f} 0 0), (0 0
2153 @var{zFar}+@var{zNear},/@var{zNear}-@var{zFar},
2154 2×@var{zFar}×@var{zNear},/@var{zNear}-@var{zFar},), (0 0 -1 0),)}
2158 @deftypefun void gluPickMatrix x y delX delY viewport
2159 Define a picking region.
2164 Specify the center of a picking region in window coordinates.
2168 Specify the width and height, respectively, of the picking region in
2171 @item @var{viewport}
2172 Specifies the current viewport (as from a @code{glGetIntegerv} call).
2176 @code{gluPickMatrix} creates a projection matrix that can be used to
2177 restrict drawing to a small region of the viewport. This is typically
2178 useful to determine what objects are being drawn near the cursor. Use
2179 @code{gluPickMatrix} to restrict drawing to a small region around the
2180 cursor. Then, enter selection mode (with @code{glRenderMode}) and
2181 rerender the scene. All primitives that would have been drawn near the
2182 cursor are identified and stored in the selection buffer.
2184 The matrix created by @code{gluPickMatrix} is multiplied by the current
2185 matrix just as if @code{glMultMatrix} is called with the generated
2186 matrix. To effectively use the generated pick matrix for picking, first
2187 call @code{glLoadIdentity} to load an identity matrix onto the
2188 perspective matrix stack. Then call @code{gluPickMatrix}, and, finally,
2189 call a command (such as @code{gluPerspective}) to multiply the
2190 perspective matrix by the pick matrix.
2192 When using @code{gluPickMatrix} to pick NURBS, be careful to turn off
2193 the NURBS property @code{GLU_AUTO_LOAD_MATRIX}. If
2194 @code{GLU_AUTO_LOAD_MATRIX} is not turned off, then any NURBS surface
2195 rendered is subdivided differently with the pick matrix than the way it
2196 was subdivided without the pick matrix.
2200 @deftypefun GLint gluProject objX objY objZ model proj view winX winY winZ
2201 Map object coordinates to window coordinates.
2207 Specify the object coordinates.
2210 Specifies the current modelview matrix (as from a @code{glGetDoublev}
2214 Specifies the current projection matrix (as from a @code{glGetDoublev}
2218 Specifies the current viewport (as from a @code{glGetIntegerv} call).
2223 Return the computed window coordinates.
2227 @code{gluProject} transforms the specified object coordinates into
2228 window coordinates using @var{model}, @var{proj}, and @var{view}. The
2229 result is stored in @var{winX}, @var{winY}, and @var{winZ}. A return
2230 value of @code{GLU_TRUE} indicates success, a return value of
2231 @code{GLU_FALSE} indicates failure.
2233 To compute the coordinates, let
2234 @r{@var{v}=(@var{objX},@var{objY}@var{objZ}1.0)} represented as a matrix
2235 with 4 rows and 1 column. Then @code{gluProject} computes @r{@var{v}^″}
2238 @r{@var{v}^″=@var{P}×@var{M}×@var{v}}
2240 where @r{@var{P}} is the current projection matrix @var{proj} and
2241 @r{@var{M}} is the current modelview matrix @var{model} (both
2242 represented as @r{4×4} matrices in column-major order).
2244 The window coordinates are then computed as follows:
2246 @r{@var{winX}=@var{view}(0,)+@var{view}(2,)×(@var{v}^″(0,)+1,)/2}@r{@var{winY}=@var{view}(1,)+@var{view}(3,)×(@var{v}^″(1,)+1,)/2}
2247 @r{@var{winZ}=(@var{v}^″(2,)+1,)/2}
2253 @deftypefun void gluPwlCurve nurb count data stride type
2254 Describe a piecewise linear NURBS trimming curve.
2258 Specifies the NURBS object (created with @code{gluNewNurbsRenderer}).
2261 Specifies the number of points on the curve.
2264 Specifies an array containing the curve points.
2267 Specifies the offset (a number of single-precision floating-point
2268 values) between points on the curve.
2271 Specifies the type of curve. Must be either @code{GLU_MAP1_TRIM_2} or
2272 @code{GLU_MAP1_TRIM_3}.
2276 @code{gluPwlCurve} describes a piecewise linear trimming curve for a
2277 NURBS surface. A piecewise linear curve consists of a list of
2278 coordinates of points in the parameter space for the NURBS surface to be
2279 trimmed. These points are connected with line segments to form a curve.
2280 If the curve is an approximation to a curve that is not piecewise
2281 linear, the points should be close enough in parameter space that the
2282 resulting path appears curved at the resolution used in the application.
2284 If @var{type} is @code{GLU_MAP1_TRIM_2}, then it describes a curve in
2285 two-dimensional (@var{u} and @var{v}) parameter space. If it is
2286 @code{GLU_MAP1_TRIM_3}, then it describes a curve in two-dimensional
2287 homogeneous (@var{u}, @var{v}, and @var{w}) parameter space. See the
2288 @code{gluBeginTrim} reference page for more information about trimming
2293 @deftypefun void gluQuadricCallback quad which CallBackFunc
2294 Define a callback for a quadrics object.
2298 Specifies the quadrics object (created with @code{gluNewQuadric}).
2301 Specifies the callback being defined. The only valid value is
2304 @item @var{CallBackFunc}
2305 Specifies the function to be called.
2309 @code{gluQuadricCallback} is used to define a new callback to be used by
2310 a quadrics object. If the specified callback is already defined, then it
2311 is replaced. If @var{CallBackFunc} is NULL, then any existing callback
2314 The one legal callback is @code{GLU_ERROR}:
2317 @item @code{GLU_ERROR}
2318 The function is called when an error is encountered. Its single argument
2319 is of type GLenum, and it indicates the specific error that occurred.
2320 Character strings describing these errors can be retrieved with the
2321 @code{gluErrorString} call.
2327 @deftypefun void gluQuadricDrawStyle quad draw
2328 Specify the draw style desired for quadrics.
2332 Specifies the quadrics object (created with @code{gluNewQuadric}).
2335 Specifies the desired draw style. Valid values are @code{GLU_FILL},
2336 @code{GLU_LINE}, @code{GLU_SILHOUETTE}, and @code{GLU_POINT}.
2340 @code{gluQuadricDrawStyle} specifies the draw style for quadrics
2341 rendered with @var{quad}. The legal values are as follows:
2344 @item @code{GLU_FILL}
2345 Quadrics are rendered with polygon primitives. The polygons are drawn in
2346 a counterclockwise fashion with respect to their normals (as defined
2347 with @code{gluQuadricOrientation}).
2349 @item @code{GLU_LINE}
2350 Quadrics are rendered as a set of lines.
2352 @item @code{GLU_SILHOUETTE}
2353 Quadrics are rendered as a set of lines, except that edges separating
2354 coplanar faces will not be drawn.
2356 @item @code{GLU_POINT}
2357 Quadrics are rendered as a set of points.
2363 @deftypefun void gluQuadricNormals quad normal
2364 Specify what kind of normals are desired for quadrics.
2368 Specifies the quadrics object (created with @code{gluNewQuadric}).
2371 Specifies the desired type of normals. Valid values are @code{GLU_NONE},
2372 @code{GLU_FLAT}, and @code{GLU_SMOOTH}.
2376 @code{gluQuadricNormals} specifies what kind of normals are desired for
2377 quadrics rendered with @var{quad}. The legal values are as follows:
2380 @item @code{GLU_NONE}
2381 No normals are generated.
2383 @item @code{GLU_FLAT}
2384 One normal is generated for every facet of a quadric.
2386 @item @code{GLU_SMOOTH}
2387 One normal is generated for every vertex of a quadric. This is the
2394 @deftypefun void gluQuadricOrientation quad orientation
2395 Specify inside/outside orientation for quadrics.
2399 Specifies the quadrics object (created with @code{gluNewQuadric}).
2401 @item @var{orientation}
2402 Specifies the desired orientation. Valid values are @code{GLU_OUTSIDE}
2403 and @code{GLU_INSIDE}.
2407 @code{gluQuadricOrientation} specifies what kind of orientation is
2408 desired for quadrics rendered with @var{quad}. The @var{orientation}
2409 values are as follows:
2412 @item @code{GLU_OUTSIDE}
2413 Quadrics are drawn with normals pointing outward (the initial value).
2415 @item @code{GLU_INSIDE}
2416 Quadrics are drawn with normals pointing inward.
2420 Note that the interpretation of @var{outward} and @var{inward} depends
2421 on the quadric being drawn.
2425 @deftypefun void gluQuadricTexture quad texture
2426 Specify if texturing is desired for quadrics.
2430 Specifies the quadrics object (created with @code{gluNewQuadric}).
2433 Specifies a flag indicating if texture coordinates should be generated.
2437 @code{gluQuadricTexture} specifies if texture coordinates should be
2438 generated for quadrics rendered with @var{quad}. If the value of
2439 @var{texture} is @code{GLU_TRUE}, then texture coordinates are
2440 generated, and if @var{texture} is @code{GLU_FALSE}, they are not. The
2441 initial value is @code{GLU_FALSE}.
2443 The manner in which texture coordinates are generated depends upon the
2444 specific quadric rendered.
2448 @deftypefun GLint gluScaleImage format wIn hIn typeIn dataIn wOut hOut typeOut dataOut
2449 Scale an image to an arbitrary size.
2453 Specifies the format of the pixel data. The following symbolic values
2454 are valid: @code{GLU_COLOR_INDEX}, @code{GLU_STENCIL_INDEX},
2455 @code{GLU_DEPTH_COMPONENT}, @code{GLU_RED}, @code{GLU_GREEN},
2456 @code{GLU_BLUE}, @code{GLU_ALPHA}, @code{GLU_RGB}, @code{GLU_RGBA},
2457 @code{GLU_BGR}, @code{GLU_BGRA}, @code{GLU_LUMINANCE}, and
2458 @code{GLU_LUMINANCE_ALPHA}.
2462 Specify in pixels the width and height, respectively, of the source
2466 Specifies the data type for @var{dataIn}. Must be one of
2467 @code{GLU_UNSIGNED_BYTE}, @code{GLU_BYTE}, @code{GLU_BITMAP},
2468 @code{GLU_UNSIGNED_SHORT}, @code{GLU_SHORT}, @code{GLU_UNSIGNED_INT},
2469 @code{GLU_INT}, @code{GLU_FLOAT}, @code{GLU_UNSIGNED_BYTE_3_3_2},
2470 @code{GLU_UNSIGNED_BYTE_2_3_3_REV}, @code{GLU_UNSIGNED_SHORT_5_6_5},
2471 @code{GLU_UNSIGNED_SHORT_5_6_5_REV}, @code{GLU_UNSIGNED_SHORT_4_4_4_4},
2472 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV},
2473 @code{GLU_UNSIGNED_SHORT_5_5_5_1},
2474 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GLU_UNSIGNED_INT_8_8_8_8},
2475 @code{GLU_UNSIGNED_INT_8_8_8_8_REV}, @code{GLU_UNSIGNED_INT_10_10_10_2},
2476 or @code{GLU_UNSIGNED_INT_2_10_10_10_REV}.
2479 Specifies a pointer to the source image.
2483 Specify the width and height, respectively, in pixels of the destination
2487 Specifies the data type for @var{dataOut}. Must be one of
2488 @code{GLU_UNSIGNED_BYTE}, @code{GLU_BYTE}, @code{GLU_BITMAP},
2489 @code{GLU_UNSIGNED_SHORT}, @code{GLU_SHORT}, @code{GLU_UNSIGNED_INT},
2490 @code{GLU_INT}, @code{GLU_FLOAT}, @code{GLU_UNSIGNED_BYTE_3_3_2},
2491 @code{GLU_UNSIGNED_BYTE_2_3_3_REV}, @code{GLU_UNSIGNED_SHORT_5_6_5},
2492 @code{GLU_UNSIGNED_SHORT_5_6_5_REV}, @code{GLU_UNSIGNED_SHORT_4_4_4_4},
2493 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV},
2494 @code{GLU_UNSIGNED_SHORT_5_5_5_1},
2495 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GLU_UNSIGNED_INT_8_8_8_8},
2496 @code{GLU_UNSIGNED_INT_8_8_8_8_REV}, @code{GLU_UNSIGNED_INT_10_10_10_2},
2497 or @code{GLU_UNSIGNED_INT_2_10_10_10_REV}.
2500 Specifies a pointer to the destination image.
2504 @code{gluScaleImage} scales a pixel image using the appropriate pixel
2505 store modes to unpack data from the source image and pack data into the
2508 When shrinking an image, @code{gluScaleImage} uses a box filter to
2509 sample the source image and create pixels for the destination image.
2510 When magnifying an image, the pixels from the source image are linearly
2511 interpolated to create the destination image.
2513 A return value of zero indicates success, otherwise a GLU error code is
2514 returned (see @code{gluErrorString}).
2516 See the @code{glReadPixels} reference page for a description of the
2517 acceptable values for the @var{format}, @var{typeIn}, and @var{typeOut}
2520 @code{GLU_INVALID_VALUE} is returned if @var{wIn}, @var{hIn},
2521 @var{wOut}, or @var{hOut} is negative.
2523 @code{GLU_INVALID_ENUM} is returned if @var{format}, @var{typeIn}, or
2524 @var{typeOut} is not legal.
2526 @code{GLU_INVALID_OPERATION} is returned if @var{typeIn} or
2527 @var{typeOut} is @code{GLU_UNSIGNED_BYTE_3_3_2} or
2528 @code{GLU_UNSIGNED_BYTE_2_3_3_REV} and @var{format} is not
2531 @code{GLU_INVALID_OPERATION} is returned if @var{typeIn} or
2532 @var{typeOut} is @code{GLU_UNSIGNED_SHORT_5_6_5} or
2533 @code{GLU_UNSIGNED_SHORT_5_6_5_REV} and @var{format} is not
2536 @code{GLU_INVALID_OPERATION} is returned if @var{typeIn} or
2537 @var{typeOut} is @code{GLU_UNSIGNED_SHORT_4_4_4_4} or
2538 @code{GLU_UNSIGNED_SHORT_4_4_4_4_REV} and @var{format} is neither
2539 @code{GLU_RGBA} nor @code{GLU_BGRA}.
2541 @code{GLU_INVALID_OPERATION} is returned if @var{typeIn} or
2542 @var{typeOut} is @code{GLU_UNSIGNED_SHORT_5_5_5_1} or
2543 @code{GLU_UNSIGNED_SHORT_1_5_5_5_REV} and @var{format} is neither
2544 @code{GLU_RGBA} nor @code{GLU_BGRA}.
2546 @code{GLU_INVALID_OPERATION} is returned if @var{typeIn} or
2547 @var{typeOut} is @code{GLU_UNSIGNED_INT_8_8_8_8} or
2548 @code{GLU_UNSIGNED_INT_8_8_8_8_REV} and @var{format} is neither
2549 @code{GLU_RGBA} nor @code{GLU_BGRA}.
2551 @code{GLU_INVALID_OPERATION} is returned if @var{typeIn} or
2552 @var{typeOut} is @code{GLU_UNSIGNED_INT_10_10_10_2} or
2553 @code{GLU_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
2554 @code{GLU_RGBA} nor @code{GLU_BGRA}.
2558 @deftypefun void gluSphere quad radius slices stacks
2563 Specifies the quadrics object (created with @code{gluNewQuadric}).
2566 Specifies the radius of the sphere.
2569 Specifies the number of subdivisions around the @var{z} axis (similar to
2570 lines of longitude).
2573 Specifies the number of subdivisions along the @var{z} axis (similar to
2578 @code{gluSphere} draws a sphere of the given radius centered around the
2579 origin. The sphere is subdivided around the @var{z} axis into slices and
2580 along the @var{z} axis into stacks (similar to lines of longitude and
2583 If the orientation is set to @code{GLU_OUTSIDE} (with
2584 @code{gluQuadricOrientation}), then any normals generated point away
2585 from the center of the sphere. Otherwise, they point toward the center
2588 If texturing is turned on (with @code{gluQuadricTexture}), then texture
2589 coordinates are generated so that @var{t} ranges from 0.0 at
2590 @r{@var{z}=-@var{radius}} to 1.0 at @r{@var{z}=@var{radius}} (@var{t}
2591 increases linearly along longitudinal lines), and @var{s} ranges from
2592 0.0 at the +@var{y} axis, to 0.25 at the +@var{x} axis, to 0.5 at the
2593 \-@var{y} axis, to 0.75 at the \-@var{x} axis, and back to 1.0 at the
2598 @deftypefun void gluTessBeginContour tess
2599 @deftypefunx void gluTessEndContour tess
2600 Delimit a contour description.
2604 Specifies the tessellation object (created with @code{gluNewTess}).
2608 @code{gluTessBeginContour} and @code{gluTessEndContour} delimit the
2609 definition of a polygon contour. Within each
2610 @code{gluTessBeginContour}/@code{gluTessEndContour} pair, there can be
2611 zero or more calls to @code{gluTessVertex}. The vertices specify a
2612 closed contour (the last vertex of each contour is automatically linked
2613 to the first). See the @code{gluTessVertex} reference page for more
2614 details. @code{gluTessBeginContour} can only be called between
2615 @code{gluTessBeginPolygon} and @code{gluTessEndPolygon}.
2619 @deftypefun void gluTessBeginPolygon tess data
2620 Delimit a polygon description.
2624 Specifies the tessellation object (created with @code{gluNewTess}).
2627 Specifies a pointer to user polygon data.
2631 @code{gluTessBeginPolygon} and @code{gluTessEndPolygon} delimit the
2632 definition of a convex, concave or self-intersecting polygon. Within
2633 each @code{gluTessBeginPolygon}/@code{gluTessEndPolygon} pair, there
2634 must be one or more calls to
2635 @code{gluTessBeginContour}/@code{gluTessEndContour}. Within each
2636 contour, there are zero or more calls to @code{gluTessVertex}. The
2637 vertices specify a closed contour (the last vertex of each contour is
2638 automatically linked to the first). See the @code{gluTessVertex},
2639 @code{gluTessBeginContour}, and @code{gluTessEndContour} reference pages
2642 @var{data} is a pointer to a user-defined data structure. If the
2643 appropriate callback(s) are specified (see @code{gluTessCallback}), then
2644 this pointer is returned to the callback function(s). Thus, it is a
2645 convenient way to store per-polygon information.
2647 Once @code{gluTessEndPolygon} is called, the polygon is tessellated, and
2648 the resulting triangles are described through callbacks. See
2649 @code{gluTessCallback} for descriptions of the callback functions.
2653 @deftypefun void gluTessCallback tess which CallBackFunc
2654 Define a callback for a tessellation object.
2658 Specifies the tessellation object (created with @code{gluNewTess}).
2661 Specifies the callback being defined. The following values are valid:
2662 @code{GLU_TESS_BEGIN}, @code{GLU_TESS_BEGIN_DATA},
2663 @code{GLU_TESS_EDGE_FLAG}, @code{GLU_TESS_EDGE_FLAG_DATA},
2664 @code{GLU_TESS_VERTEX}, @code{GLU_TESS_VERTEX_DATA},
2665 @code{GLU_TESS_END}, @code{GLU_TESS_END_DATA}, @code{GLU_TESS_COMBINE},
2666 @code{GLU_TESS_COMBINE_DATA}, @code{GLU_TESS_ERROR}, and
2667 @code{GLU_TESS_ERROR_DATA}.
2669 @item @var{CallBackFunc}
2670 Specifies the function to be called.
2674 @code{gluTessCallback} is used to indicate a callback to be used by a
2675 tessellation object. If the specified callback is already defined, then
2676 it is replaced. If @var{CallBackFunc} is NULL, then the existing
2677 callback becomes undefined.
2679 These callbacks are used by the tessellation object to describe how a
2680 polygon specified by the user is broken into triangles. Note that there
2681 are two versions of each callback: one with user-specified polygon data
2682 and one without. If both versions of a particular callback are
2683 specified, then the callback with user-specified polygon data will be
2684 used. Note that the @var{polygon_data} parameter used by some of the
2685 functions is a copy of the pointer that was specified when
2686 @code{gluTessBeginPolygon} was called. The legal callbacks are as
2690 @item @code{GLU_TESS_BEGIN}
2691 The begin callback is invoked like @code{glBegin} to indicate the start
2692 of a (triangle) primitive. The function takes a single argument of type
2693 GLenum. If the @code{GLU_TESS_BOUNDARY_ONLY} property is set to
2694 @code{GLU_FALSE}, then the argument is set to either
2695 @code{GLU_TRIANGLE_FAN}, @code{GLU_TRIANGLE_STRIP}, or
2696 @code{GLU_TRIANGLES}. If the @code{GLU_TESS_BOUNDARY_ONLY} property is
2697 set to @code{GLU_TRUE}, then the argument will be set to
2698 @code{GLU_LINE_LOOP}. The function prototype for this callback is:
2700 @item @code{GLU_TESS_BEGIN_DATA}
2701 The same as the @code{GLU_TESS_BEGIN} callback except that it takes an
2702 additional pointer argument. This pointer is identical to the opaque
2703 pointer provided when @code{gluTessBeginPolygon} was called. The
2704 function prototype for this callback is:
2706 @item @code{GLU_TESS_EDGE_FLAG}
2707 The edge flag callback is similar to @code{glEdgeFlag}. The function
2708 takes a single boolean flag that indicates which edges lie on the
2709 polygon boundary. If the flag is @code{GLU_TRUE}, then each vertex that
2710 follows begins an edge that lies on the polygon boundary, that is, an
2711 edge that separates an interior region from an exterior one. If the flag
2712 is @code{GLU_FALSE}, then each vertex that follows begins an edge that
2713 lies in the polygon interior. The edge flag callback (if defined) is
2714 invoked before the first vertex callback.
2716 Since triangle fans and triangle strips do not support edge flags, the
2717 begin callback is not called with @code{GLU_TRIANGLE_FAN} or
2718 @code{GLU_TRIANGLE_STRIP} if a non-NULL edge flag callback is provided.
2719 (If the callback is initialized to NULL, there is no impact on
2720 performance). Instead, the fans and strips are converted to independent
2721 triangles. The function prototype for this callback is:
2723 @item @code{GLU_TESS_EDGE_FLAG_DATA}
2724 The same as the @code{GLU_TESS_EDGE_FLAG} callback except that it takes
2725 an additional pointer argument. This pointer is identical to the opaque
2726 pointer provided when @code{gluTessBeginPolygon} was called. The
2727 function prototype for this callback is:
2729 @item @code{GLU_TESS_VERTEX}
2730 The vertex callback is invoked between the begin and end callbacks. It
2731 is similar to @code{glVertex}, and it defines the vertices of the
2732 triangles created by the tessellation process. The function takes a
2733 pointer as its only argument. This pointer is identical to the opaque
2734 pointer provided by the user when the vertex was described (see
2735 @code{gluTessVertex}). The function prototype for this callback is:
2737 @item @code{GLU_TESS_VERTEX_DATA}
2738 The same as the @code{GLU_TESS_VERTEX} callback except that it takes an
2739 additional pointer argument. This pointer is identical to the opaque
2740 pointer provided when @code{gluTessBeginPolygon} was called. The
2741 function prototype for this callback is:
2743 @item @code{GLU_TESS_END}
2744 The end callback serves the same purpose as @code{glEnd}. It indicates
2745 the end of a primitive and it takes no arguments. The function prototype
2746 for this callback is:
2748 @item @code{GLU_TESS_END_DATA}
2749 The same as the @code{GLU_TESS_END} callback except that it takes an
2750 additional pointer argument. This pointer is identical to the opaque
2751 pointer provided when @code{gluTessBeginPolygon} was called. The
2752 function prototype for this callback is:
2754 @item @code{GLU_TESS_COMBINE}
2755 The combine callback is called to create a new vertex when the
2756 tessellation detects an intersection or wishes to merge features. The
2757 function takes four arguments: an array of three elements each of type
2758 GLdouble, an array of four pointers, an array of four elements each of
2759 type GLfloat, and a pointer to a pointer. The prototype is:
2761 The vertex is defined as a linear combination of up to four existing
2762 vertices, stored in @var{vertex_data}. The coefficients of the linear
2763 combination are given by @var{weight}; these weights always add up to 1.
2764 All vertex pointers are valid even when some of the weights are 0.
2765 @var{coords} gives the location of the new vertex.
2767 The user must allocate another vertex, interpolate parameters using
2768 @var{vertex_data} and @var{weight}, and return the new vertex pointer in
2769 @var{outData}. This handle is supplied during rendering callbacks. The
2770 user is responsible for freeing the memory some time after
2771 @code{gluTessEndPolygon} is called.
2773 For example, if the polygon lies in an arbitrary plane in 3-space, and a
2774 color is associated with each vertex, the @code{GLU_TESS_COMBINE}
2775 callback might look like this:
2777 If the tessellation detects an intersection, then the
2778 @code{GLU_TESS_COMBINE} or @code{GLU_TESS_COMBINE_DATA} callback (see
2779 below) must be defined, and it must write a non-NULL pointer into
2780 @var{dataOut}. Otherwise the @code{GLU_TESS_NEED_COMBINE_CALLBACK} error
2781 occurs, and no output is generated.
2783 @item @code{GLU_TESS_COMBINE_DATA}
2784 The same as the @code{GLU_TESS_COMBINE} callback except that it takes an
2785 additional pointer argument. This pointer is identical to the opaque
2786 pointer provided when @code{gluTessBeginPolygon} was called. The
2787 function prototype for this callback is:
2789 @item @code{GLU_TESS_ERROR}
2790 The error callback is called when an error is encountered. The one
2791 argument is of type GLenum; it indicates the specific error that
2792 occurred and will be set to one of
2793 @code{GLU_TESS_MISSING_BEGIN_POLYGON},
2794 @code{GLU_TESS_MISSING_END_POLYGON},
2795 @code{GLU_TESS_MISSING_BEGIN_CONTOUR},
2796 @code{GLU_TESS_MISSING_END_CONTOUR}, @code{GLU_TESS_COORD_TOO_LARGE},
2797 @code{GLU_TESS_NEED_COMBINE_CALLBACK}, or @code{GLU_OUT_OF_MEMORY}.
2798 Character strings describing these errors can be retrieved with the
2799 @code{gluErrorString} call. The function prototype for this callback is:
2801 The GLU library will recover from the first four errors by inserting the
2802 missing call(s). @code{GLU_TESS_COORD_TOO_LARGE} indicates that some
2803 vertex coordinate exceeded the predefined constant
2804 @code{GLU_TESS_MAX_COORD} in absolute value, and that the value has been
2805 clamped. (Coordinate values must be small enough so that two can be
2806 multiplied together without overflow.)
2807 @code{GLU_TESS_NEED_COMBINE_CALLBACK} indicates that the tessellation
2808 detected an intersection between two edges in the input data, and the
2809 @code{GLU_TESS_COMBINE} or @code{GLU_TESS_COMBINE_DATA} callback was not
2810 provided. No output is generated. @code{GLU_OUT_OF_MEMORY} indicates
2811 that there is not enough memory so no output is generated.
2813 @item @code{GLU_TESS_ERROR_DATA}
2814 The same as the @code{GLU_TESS_ERROR} callback except that it takes an
2815 additional pointer argument. This pointer is identical to the opaque
2816 pointer provided when @code{gluTessBeginPolygon} was called. The
2817 function prototype for this callback is:
2823 void begin( GLenum type );
2828 void beginData( GLenum type, void *polygon_data );
2833 void edgeFlag( GLboolean flag );
2838 void edgeFlagData( GLboolean flag, void *polygon_data );
2843 void vertex( void *vertex_data );
2848 void vertexData( void *vertex_data, void *polygon_data );
2858 void endData( void *polygon_data );
2863 void combine( GLdouble coords[3], void *vertex_data[4],
2864 GLfloat weight[4], void **outData );
2869 void myCombine( GLdouble coords[3], VERTEX *d[4],
2870 GLfloat w[4], VERTEX **dataOut )
2872 VERTEX *new = new_vertex();
2877 new->r = w[0]*d[0]->r + w[1]*d[1]->r + w[2]*d[2]->r + w[3]*d[3]->r;
2878 new->g = w[0]*d[0]->g + w[1]*d[1]->g + w[2]*d[2]->g + w[3]*d[3]->g;
2879 new->b = w[0]*d[0]->b + w[1]*d[1]->b + w[2]*d[2]->b + w[3]*d[3]->b;
2880 new->a = w[0]*d[0]->a + w[1]*d[1]->a + w[2]*d[2]->a + w[3]*d[3]->a;
2887 void combineData( GLdouble coords[3], void *vertex_data[4],
2888 GLfloat weight[4], void **outData,
2889 void *polygon_data );
2894 void error( GLenum errno );
2899 void errorData( GLenum errno, void *polygon_data );
2904 @deftypefun void gluTessEndPolygon tess
2905 Delimit a polygon description.
2909 Specifies the tessellation object (created with @code{gluNewTess}).
2913 @code{gluTessBeginPolygon} and @code{gluTessEndPolygon} delimit the
2914 definition of a convex, concave, or self-intersecting polygon. Within
2915 each @code{gluTessBeginPolygon}/@code{gluTessEndPolygon} pair, there
2916 must be one or more calls to
2917 @code{gluTessBeginContour}/@code{gluTessEndContour}. Within each
2918 contour, there are zero or more calls to @code{gluTessVertex}. The
2919 vertices specify a closed contour (the last vertex of each contour is
2920 automatically linked to the first). See the @code{gluTessVertex},
2921 @code{gluTessBeginContour}, and @code{gluTessEndContour} reference pages
2924 Once @code{gluTessEndPolygon} is called, the polygon is tessellated, and
2925 the resulting triangles are described through callbacks. See
2926 @code{gluTessCallback} for descriptions of the callback functions.
2930 @deftypefun void gluTessNormal tess valueX valueY valueZ
2931 Specify a normal for a polygon.
2935 Specifies the tessellation object (created with @code{gluNewTess}).
2938 Specifies the first component of the normal.
2941 Specifies the second component of the normal.
2944 Specifies the third component of the normal.
2948 @code{gluTessNormal} describes a normal for a polygon that the program
2949 is defining. All input data will be projected onto a plane perpendicular
2950 to one of the three coordinate axes before tessellation and all output
2951 triangles will be oriented CCW with respect to the normal (CW
2952 orientation can be obtained by reversing the sign of the supplied
2953 normal). For example, if you know that all polygons lie in the x-y
2954 plane, call @code{gluTessNormal}(tess, 0.0, 0.0, 1.0) before rendering
2957 If the supplied normal is (0.0, 0.0, 0.0) (the initial value), the
2958 normal is determined as follows. The direction of the normal, up to its
2959 sign, is found by fitting a plane to the vertices, without regard to how
2960 the vertices are connected. It is expected that the input data lies
2961 approximately in the plane; otherwise, projection perpendicular to one
2962 of the three coordinate axes may substantially change the geometry. The
2963 sign of the normal is chosen so that the sum of the signed areas of all
2964 input contours is nonnegative (where a CCW contour has positive area).
2966 The supplied normal persists until it is changed by another call to
2967 @code{gluTessNormal}.
2971 @deftypefun void gluTessProperty tess which data
2972 Set a tessellation object property.
2976 Specifies the tessellation object (created with @code{gluNewTess}).
2979 Specifies the property to be set. Valid values are
2980 @code{GLU_TESS_WINDING_RULE}, @code{GLU_TESS_BOUNDARY_ONLY}, and
2981 @code{GLU_TESS_TOLERANCE}.
2984 Specifies the value of the indicated property.
2988 @code{gluTessProperty} is used to control properties stored in a
2989 tessellation object. These properties affect the way that the polygons
2990 are interpreted and rendered. The legal values for @var{which} are as
2994 @item @code{GLU_TESS_WINDING_RULE}
2995 Determines which parts of the polygon are on the ``interior''.
2996 @var{data} may be set to one of @code{GLU_TESS_WINDING_ODD},
2997 @code{GLU_TESS_WINDING_NONZERO}, @code{GLU_TESS_WINDING_POSITIVE},
2998 @code{GLU_TESS_WINDING_NEGATIVE}, or
2999 @code{GLU_TESS_WINDING_ABS_GEQ_TWO}.
3001 To understand how the winding rule works, consider that the input
3002 contours partition the plane into regions. The winding rule determines
3003 which of these regions are inside the polygon.
3005 For a single contour C, the winding number of a point x is simply the
3006 signed number of revolutions we make around x as we travel once around C
3007 (where CCW is positive). When there are several contours, the individual
3008 winding numbers are summed. This procedure associates a signed integer
3009 value with each point x in the plane. Note that the winding number is
3010 the same for all points in a single region.
3012 The winding rule classifies a region as ``inside'' if its winding number
3013 belongs to the chosen category (odd, nonzero, positive, negative, or
3014 absolute value of at least two). The previous GLU tessellator (prior to
3015 GLU 1.2) used the ``odd'' rule. The ``nonzero'' rule is another common
3016 way to define the interior. The other three rules are useful for polygon
3019 @item @code{GLU_TESS_BOUNDARY_ONLY}
3020 Is a boolean value (``value'' should be set to GL_TRUE or GL_FALSE).
3021 When set to GL_TRUE, a set of closed contours separating the polygon
3022 interior and exterior are returned instead of a tessellation. Exterior
3023 contours are oriented CCW with respect to the normal; interior contours
3024 are oriented CW. The @code{GLU_TESS_BEGIN} and
3025 @code{GLU_TESS_BEGIN_DATA} callbacks use the type GL_LINE_LOOP for each
3028 @item @code{GLU_TESS_TOLERANCE}
3029 Specifies a tolerance for merging features to reduce the size of the
3030 output. For example, two vertices that are very close to each other
3031 might be replaced by a single vertex. The tolerance is multiplied by the
3032 largest coordinate magnitude of any input vertex; this specifies the
3033 maximum distance that any feature can move as the result of a single
3034 merge operation. If a single feature takes part in several merge
3035 operations, the total distance moved could be larger.
3037 Feature merging is completely optional; the tolerance is only a hint.
3038 The implementation is free to merge in some cases and not in others, or
3039 to never merge features at all. The initial tolerance is 0.
3041 The current implementation merges vertices only if they are exactly
3042 coincident, regardless of the current tolerance. A vertex is spliced
3043 into an edge only if the implementation is unable to distinguish which
3044 side of the edge the vertex lies on. Two edges are merged only when both
3045 endpoints are identical.
3051 @deftypefun void gluTessVertex tess location data
3052 Specify a vertex on a polygon.
3056 Specifies the tessellation object (created with @code{gluNewTess}).
3058 @item @var{location}
3059 Specifies the location of the vertex.
3062 Specifies an opaque pointer passed back to the program with the vertex
3063 callback (as specified by @code{gluTessCallback}).
3067 @code{gluTessVertex} describes a vertex on a polygon that the program
3068 defines. Successive @code{gluTessVertex} calls describe a closed
3069 contour. For example, to describe a quadrilateral, @code{gluTessVertex}
3070 should be called four times. @code{gluTessVertex} can only be called
3071 between @code{gluTessBeginContour} and @code{gluTessEndContour}.
3073 @var{data} normally points to a structure containing the vertex
3074 location, as well as other per-vertex attributes such as color and
3075 normal. This pointer is passed back to the user through the
3076 @code{GLU_TESS_VERTEX} or @code{GLU_TESS_VERTEX_DATA} callback after
3077 tessellation (see the @code{gluTessCallback} reference page).
3081 @deftypefun GLint gluUnProject4 winX winY winZ clipW model proj view nearVal farVal objX objY objZ objW
3082 Map window and clip coordinates to object coordinates.
3088 Specify the window coordinates to be mapped.
3091 Specify the clip w coordinate to be mapped.
3094 Specifies the modelview matrix (as from a @code{glGetDoublev} call).
3097 Specifies the projection matrix (as from a @code{glGetDoublev} call).
3100 Specifies the viewport (as from a @code{glGetIntegerv} call).
3104 Specifies the near and far planes (as from a @code{glGetDoublev} call).
3110 Returns the computed object coordinates.
3114 @code{gluUnProject4} maps the specified window coordinatesi: @var{winX},
3115 @var{winY}, and @var{winZ} and its clip w coordinate @var{clipW} into
3116 object coordinates @r{(@var{objX},@var{objY}@var{objZ}@var{objW})} using
3117 @var{model}, @var{proj}, and @var{view}. @var{clipW} can be other than 1
3118 as for vertices in @code{glFeedbackBuffer} when data type
3119 @code{GLU_4D_COLOR_TEXTURE} is returned. This also handles the case
3120 where the @var{nearVal} and @var{farVal} planes are different from the
3121 default, 0 and 1, respectively. A return value of @code{GLU_TRUE}
3122 indicates success; a return value of @code{GLU_FALSE} indicates failure.
3124 To compute the coordinates
3125 @r{(@var{objX},@var{objY}@var{objZ}@var{objW})}, @code{gluUnProject4}
3126 multiplies the normalized device coordinates by the inverse of
3127 @var{model} * @var{proj} as follows:
3129 @r{((@var{objX}), (@var{objY}), (@var{objZ}),
3130 (@var{objW}),)=@var{INV}(@var{P}@var{M},)((2(@var{winX}-@var{view}[0,],),/@var{view}[2,],-1),
3131 (2(@var{winY}-@var{view}[1,],),/@var{view}[3,],-1),
3132 (2(@var{winZ}-@var{nearVal},),/(@var{farVal}-@var{nearVal},),-1),
3135 @r{@var{INV}} denotes matrix inversion.
3137 @code{gluUnProject4} is equivalent to @code{gluUnProject} when
3138 @var{clipW} is 1, @var{nearVal} is 0, and @var{farVal} is 1.
3142 @deftypefun GLint gluUnProject winX winY winZ model proj view objX objY objZ
3143 Map window coordinates to object coordinates.
3149 Specify the window coordinates to be mapped.
3152 Specifies the modelview matrix (as from a @code{glGetDoublev} call).
3155 Specifies the projection matrix (as from a @code{glGetDoublev} call).
3158 Specifies the viewport (as from a @code{glGetIntegerv} call).
3163 Returns the computed object coordinates.
3167 @code{gluUnProject} maps the specified window coordinates into object
3168 coordinates using @var{model}, @var{proj}, and @var{view}. The result is
3169 stored in @var{objX}, @var{objY}, and @var{objZ}. A return value of
3170 @code{GLU_TRUE} indicates success; a return value of @code{GLU_FALSE}
3173 To compute the coordinates @r{(@var{objX},@var{objY}@var{objZ})},
3174 @code{gluUnProject} multiplies the normalized device coordinates by the
3175 inverse of @var{model} * @var{proj} as follows:
3177 @r{((@var{objX}), (@var{objY}), (@var{objZ}),
3178 (@var{W}),)=@var{INV}(@var{P}@var{M},)((2(@var{winX}-@var{view}[0,],),/@var{view}[2,],-1),
3179 (2(@var{winY}-@var{view}[1,],),/@var{view}[3,],-1),
3180 (2(@var{winZ},)-1), (1),)}@r{@var{INV}} denotes matrix inversion. W is
3181 an unused variable, included for consistent matrix notation.