| 1 | |
| 2 | @c %start of fragment |
| 3 | |
| 4 | The functions from this section may be had by loading the module: |
| 5 | |
| 6 | @example |
| 7 | (use-modules (figl glu low-level) |
| 8 | @end example |
| 9 | |
| 10 | @copying |
| 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. |
| 15 | |
| 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/}. |
| 19 | |
| 20 | @end copying |
| 21 | |
| 22 | @deftypefun void gluBeginCurve nurb |
| 23 | @deftypefunx void gluEndCurve nurb |
| 24 | Delimit a NURBS curve definition. |
| 25 | |
| 26 | @table @asis |
| 27 | @item @var{nurb} |
| 28 | Specifies the NURBS object (created with @code{gluNewNurbsRenderer}). |
| 29 | |
| 30 | @end table |
| 31 | |
| 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}. |
| 38 | |
| 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 |
| 43 | these calls preserve. |
| 44 | |
| 45 | @end deftypefun |
| 46 | |
| 47 | @deftypefun void gluBeginPolygon tess |
| 48 | @deftypefunx void gluEndPolygon tess |
| 49 | Delimit a polygon description. |
| 50 | |
| 51 | @table @asis |
| 52 | @item @var{tess} |
| 53 | Specifies the tessellation object (created with @code{gluNewTess}). |
| 54 | |
| 55 | @end table |
| 56 | |
| 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. |
| 64 | |
| 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. |
| 68 | |
| 69 | @end deftypefun |
| 70 | |
| 71 | @deftypefun void gluBeginSurface nurb |
| 72 | @deftypefunx void gluEndSurface nurb |
| 73 | Delimit a NURBS surface definition. |
| 74 | |
| 75 | @table @asis |
| 76 | @item @var{nurb} |
| 77 | Specifies the NURBS object (created with @code{gluNewNurbsRenderer}). |
| 78 | |
| 79 | @end table |
| 80 | |
| 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}. |
| 87 | |
| 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. |
| 91 | |
| 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 |
| 96 | these calls preserve. |
| 97 | |
| 98 | @end deftypefun |
| 99 | |
| 100 | @deftypefun void gluBeginTrim nurb |
| 101 | @deftypefunx void gluEndTrim nurb |
| 102 | Delimit a NURBS trimming loop definition. |
| 103 | |
| 104 | @table @asis |
| 105 | @item @var{nurb} |
| 106 | Specifies the NURBS object (created with @code{gluNewNurbsRenderer}). |
| 107 | |
| 108 | @end table |
| 109 | |
| 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}. |
| 116 | |
| 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. |
| 124 | |
| 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}. |
| 132 | |
| 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. |
| 140 | |
| 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}). |
| 148 | |
| 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. |
| 154 | |
| 155 | If no trimming information is given for a NURBS surface, the entire |
| 156 | surface is drawn. |
| 157 | |
| 158 | @end deftypefun |
| 159 | |
| 160 | @deftypefun GLint gluBuild1DMipmapLevels target internalFormat width format type level base max data |
| 161 | Builds a subset of one-dimensional mipmap levels. |
| 162 | |
| 163 | @table @asis |
| 164 | @item @var{target} |
| 165 | Specifies the target texture. Must be @code{GLU_TEXTURE_1D}. |
| 166 | |
| 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 |
| 190 | @code{GLU_RGBA16}. |
| 191 | |
| 192 | @item @var{width} |
| 193 | Specifies the width in pixels of the texture image. This should be a |
| 194 | power of 2. |
| 195 | |
| 196 | @item @var{format} |
| 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}. |
| 202 | |
| 203 | @item @var{type} |
| 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}. |
| 215 | |
| 216 | @item @var{level} |
| 217 | Specifies the mipmap level of the image data. |
| 218 | |
| 219 | @item @var{base} |
| 220 | Specifies the minimum mipmap level to pass to @code{glTexImage1D}. |
| 221 | |
| 222 | @item @var{max} |
| 223 | Specifies the maximum mipmap level to pass to @code{glTexImage1D}. |
| 224 | |
| 225 | @item @var{data} |
| 226 | Specifies a pointer to the image data in memory. |
| 227 | |
| 228 | @end table |
| 229 | |
| 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. |
| 233 | |
| 234 | A return value of zero indicates success, otherwise a GLU error code is |
| 235 | returned (see @code{gluErrorString}). |
| 236 | |
| 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. |
| 245 | |
| 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. |
| 253 | |
| 254 | The highest mipmap level can be derived from the formula |
| 255 | @r{@var{log}_2(@var{width}×2^@var{level},)}. |
| 256 | |
| 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. |
| 261 | |
| 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}. |
| 265 | |
| 266 | @code{GLU_INVALID_VALUE} is returned if @var{width} is < 1. |
| 267 | |
| 268 | @code{GLU_INVALID_ENUM} is returned if @var{internalFormat}, |
| 269 | @var{format}, or @var{type} are not legal. |
| 270 | |
| 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}. |
| 274 | |
| 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}. |
| 278 | |
| 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}. |
| 283 | |
| 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}. |
| 288 | |
| 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}. |
| 292 | |
| 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}. |
| 297 | |
| 298 | @end deftypefun |
| 299 | |
| 300 | @deftypefun GLint gluBuild1DMipmaps target internalFormat width format type data |
| 301 | Builds a one-dimensional mipmap. |
| 302 | |
| 303 | @table @asis |
| 304 | @item @var{target} |
| 305 | Specifies the target texture. Must be @code{GLU_TEXTURE_1D}. |
| 306 | |
| 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 |
| 330 | @code{GLU_RGBA16}. |
| 331 | |
| 332 | @item @var{width} |
| 333 | Specifies the width, in pixels, of the texture image. |
| 334 | |
| 335 | @item @var{format} |
| 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}. |
| 341 | |
| 342 | @item @var{type} |
| 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}. |
| 354 | |
| 355 | @item @var{data} |
| 356 | Specifies a pointer to the image data in memory. |
| 357 | |
| 358 | @end table |
| 359 | |
| 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. |
| 363 | |
| 364 | A return value of zero indicates success, otherwise a GLU error code is |
| 365 | returned (see @code{gluErrorString}). |
| 366 | |
| 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. |
| 374 | |
| 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. |
| 378 | |
| 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. |
| 383 | |
| 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, |
| 390 | respectively. |
| 391 | |
| 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. |
| 396 | |
| 397 | @code{GLU_INVALID_VALUE} is returned if @var{width} is < 1. |
| 398 | |
| 399 | @code{GLU_INVALID_ENUM} is returned if @var{format} or @var{type} are |
| 400 | not legal. |
| 401 | |
| 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}. |
| 405 | |
| 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}. |
| 409 | |
| 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}. |
| 414 | |
| 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}. |
| 419 | |
| 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}. |
| 423 | |
| 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}. |
| 428 | |
| 429 | @end deftypefun |
| 430 | |
| 431 | @deftypefun GLint gluBuild2DMipmapLevels target internalFormat width height format type level base max data |
| 432 | Builds a subset of two-dimensional mipmap levels. |
| 433 | |
| 434 | @table @asis |
| 435 | @item @var{target} |
| 436 | Specifies the target texture. Must be @code{GLU_TEXTURE_2D}. |
| 437 | |
| 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 |
| 461 | @code{GLU_RGBA16}. |
| 462 | |
| 463 | @item @var{width} |
| 464 | @itemx @var{height} |
| 465 | Specifies the width and height, respectively, in pixels of the texture |
| 466 | image. These should be a power of 2. |
| 467 | |
| 468 | @item @var{format} |
| 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}. |
| 474 | |
| 475 | @item @var{type} |
| 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}. |
| 487 | |
| 488 | @item @var{level} |
| 489 | Specifies the mipmap level of the image data. |
| 490 | |
| 491 | @item @var{base} |
| 492 | Specifies the minimum mipmap level to pass to @code{glTexImage2D}. |
| 493 | |
| 494 | @item @var{max} |
| 495 | Specifies the maximum mipmap level to pass to @code{glTexImage2D}. |
| 496 | |
| 497 | @item @var{data} |
| 498 | Specifies a pointer to the image data in memory. |
| 499 | |
| 500 | @end table |
| 501 | |
| 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. |
| 505 | |
| 506 | A return value of zero indicates success, otherwise a GLU error code is |
| 507 | returned (see @code{gluErrorString}). |
| 508 | |
| 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 |
| 519 | loaded. |
| 520 | |
| 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. |
| 528 | |
| 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},)}. |
| 531 | |
| 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. |
| 536 | |
| 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}. |
| 540 | |
| 541 | @code{GLU_INVALID_VALUE} is returned if @var{width} or @var{height} is < |
| 542 | 1. |
| 543 | |
| 544 | @code{GLU_INVALID_ENUM} is returned if @var{internalFormat}, |
| 545 | @var{format}, or @var{type} is not legal. |
| 546 | |
| 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}. |
| 550 | |
| 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}. |
| 554 | |
| 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}. |
| 559 | |
| 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}. |
| 564 | |
| 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}. |
| 568 | |
| 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}. |
| 573 | |
| 574 | @end deftypefun |
| 575 | |
| 576 | @deftypefun GLint gluBuild2DMipmaps target internalFormat width height format type data |
| 577 | Builds a two-dimensional mipmap. |
| 578 | |
| 579 | @table @asis |
| 580 | @item @var{target} |
| 581 | Specifies the target texture. Must be @code{GLU_TEXTURE_2D}. |
| 582 | |
| 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 |
| 606 | @code{GLU_RGBA16}. |
| 607 | |
| 608 | @item @var{width} |
| 609 | @itemx @var{height} |
| 610 | Specifies in pixels the width and height, respectively, of the texture |
| 611 | image. |
| 612 | |
| 613 | @item @var{format} |
| 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}. |
| 619 | |
| 620 | @item @var{type} |
| 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}. |
| 632 | |
| 633 | @item @var{data} |
| 634 | Specifies a pointer to the image data in memory. |
| 635 | |
| 636 | @end table |
| 637 | |
| 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. |
| 641 | |
| 642 | A return value of zero indicates success, otherwise a GLU error code is |
| 643 | returned (see @code{gluErrorString}). |
| 644 | |
| 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. |
| 653 | |
| 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}.) |
| 660 | |
| 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 |
| 667 | averaged instead.) |
| 668 | |
| 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. |
| 676 | |
| 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. |
| 681 | |
| 682 | @code{GLU_INVALID_VALUE} is returned if @var{width} or @var{height} is < |
| 683 | 1. |
| 684 | |
| 685 | @code{GLU_INVALID_ENUM} is returned if @var{internalFormat}, |
| 686 | @var{format}, or @var{type} is not legal. |
| 687 | |
| 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}. |
| 691 | |
| 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}. |
| 695 | |
| 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}. |
| 700 | |
| 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}. |
| 705 | |
| 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}. |
| 709 | |
| 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}. |
| 714 | |
| 715 | @end deftypefun |
| 716 | |
| 717 | @deftypefun GLint gluBuild3DMipmapLevels target internalFormat width height depth format type level base max data |
| 718 | Builds a subset of three-dimensional mipmap levels. |
| 719 | |
| 720 | @table @asis |
| 721 | @item @var{target} |
| 722 | Specifies the target texture. Must be @code{GLU_TEXTURE_3D}. |
| 723 | |
| 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 |
| 747 | @code{GLU_RGBA16}. |
| 748 | |
| 749 | @item @var{width} |
| 750 | @itemx @var{height} |
| 751 | @itemx @var{depth} |
| 752 | Specifies in pixels the width, height and depth respectively, of the |
| 753 | texture image. These should be a power of 2. |
| 754 | |
| 755 | @item @var{format} |
| 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}. |
| 761 | |
| 762 | @item @var{type} |
| 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}. |
| 774 | |
| 775 | @item @var{level} |
| 776 | Specifies the mipmap level of the image data. |
| 777 | |
| 778 | @item @var{base} |
| 779 | Specifies the minimum mipmap level to pass to @code{glTexImage3D}. |
| 780 | |
| 781 | @item @var{max} |
| 782 | Specifies the maximum mipmap level to pass to @code{glTexImage3D}. |
| 783 | |
| 784 | @item @var{data} |
| 785 | Specifies a pointer to the image data in memory. |
| 786 | |
| 787 | @end table |
| 788 | |
| 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. |
| 792 | |
| 793 | A return value of zero indicates success, otherwise a GLU error code is |
| 794 | returned (see @code{gluErrorString}). |
| 795 | |
| 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. |
| 806 | |
| 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 |
| 814 | this case, 6. |
| 815 | |
| 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},)}. |
| 818 | |
| 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. |
| 823 | |
| 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}. |
| 827 | |
| 828 | @code{GLU_INVALID_VALUE} is returned if @var{width}, @var{height}, or |
| 829 | @var{depth} is < 1. |
| 830 | |
| 831 | @code{GLU_INVALID_ENUM} is returned if @var{internalFormat}, |
| 832 | @var{format}, or @var{type} is not legal. |
| 833 | |
| 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}. |
| 837 | |
| 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}. |
| 841 | |
| 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}. |
| 846 | |
| 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}. |
| 851 | |
| 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}. |
| 855 | |
| 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}. |
| 860 | |
| 861 | @end deftypefun |
| 862 | |
| 863 | @deftypefun GLint gluBuild3DMipmaps target internalFormat width height depth format type data |
| 864 | Builds a three-dimensional mipmap. |
| 865 | |
| 866 | @table @asis |
| 867 | @item @var{target} |
| 868 | Specifies the target texture. Must be @code{GLU_TEXTURE_3D}. |
| 869 | |
| 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 |
| 893 | @code{GLU_RGBA16}. |
| 894 | |
| 895 | @item @var{width} |
| 896 | @itemx @var{height} |
| 897 | @itemx @var{depth} |
| 898 | Specifies in pixels the width, height and depth respectively, in pixels |
| 899 | of the texture image. |
| 900 | |
| 901 | @item @var{format} |
| 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}. |
| 907 | |
| 908 | @item @var{type} |
| 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}. |
| 920 | |
| 921 | @item @var{data} |
| 922 | Specifies a pointer to the image data in memory. |
| 923 | |
| 924 | @end table |
| 925 | |
| 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. |
| 929 | |
| 930 | A return value of zero indicates success, otherwise a GLU error code is |
| 931 | returned (see @code{gluErrorString}). |
| 932 | |
| 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. |
| 942 | |
| 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. |
| 946 | |
| 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.) |
| 953 | |
| 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. |
| 962 | |
| 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. |
| 967 | |
| 968 | @code{GLU_INVALID_VALUE} is returned if @var{width}, @var{height}, or |
| 969 | @var{depth} is < 1. |
| 970 | |
| 971 | @code{GLU_INVALID_ENUM} is returned if @var{internalFormat}, |
| 972 | @var{format}, or @var{type} is not legal. |
| 973 | |
| 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}. |
| 977 | |
| 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}. |
| 981 | |
| 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}. |
| 986 | |
| 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}. |
| 991 | |
| 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}. |
| 995 | |
| 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}. |
| 1000 | |
| 1001 | @end deftypefun |
| 1002 | |
| 1003 | @deftypefun GLboolean gluCheckExtension extName extString |
| 1004 | Determines if an extension name is supported. |
| 1005 | |
| 1006 | @table @asis |
| 1007 | @item @var{extName} |
| 1008 | Specifies an extension name. |
| 1009 | |
| 1010 | @item @var{extString} |
| 1011 | Specifies a space-separated list of extension names supported. |
| 1012 | |
| 1013 | @end table |
| 1014 | |
| 1015 | @code{gluCheckExtension} returns @code{GLU_TRUE} if @var{extName} is |
| 1016 | supported otherwise @code{GLU_FALSE} is returned. |
| 1017 | |
| 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}. |
| 1023 | |
| 1024 | @end deftypefun |
| 1025 | |
| 1026 | @deftypefun void gluCylinder quad base top height slices stacks |
| 1027 | Draw a cylinder. |
| 1028 | |
| 1029 | @table @asis |
| 1030 | @item @var{quad} |
| 1031 | Specifies the quadrics object (created with @code{gluNewQuadric}). |
| 1032 | |
| 1033 | @item @var{base} |
| 1034 | Specifies the radius of the cylinder at @var{z} = 0. |
| 1035 | |
| 1036 | @item @var{top} |
| 1037 | Specifies the radius of the cylinder at @var{z} = @var{height}. |
| 1038 | |
| 1039 | @item @var{height} |
| 1040 | Specifies the height of the cylinder. |
| 1041 | |
| 1042 | @item @var{slices} |
| 1043 | Specifies the number of subdivisions around the @var{z} axis. |
| 1044 | |
| 1045 | @item @var{stacks} |
| 1046 | Specifies the number of subdivisions along the @var{z} axis. |
| 1047 | |
| 1048 | @end table |
| 1049 | |
| 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. |
| 1054 | |
| 1055 | Note that if @var{top} is set to 0.0, this routine generates a cone. |
| 1056 | |
| 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. |
| 1060 | |
| 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 |
| 1066 | +@var{y} axis. |
| 1067 | |
| 1068 | @end deftypefun |
| 1069 | |
| 1070 | @deftypefun void gluDeleteNurbsRenderer nurb |
| 1071 | Destroy a NURBS object. |
| 1072 | |
| 1073 | @table @asis |
| 1074 | @item @var{nurb} |
| 1075 | Specifies the NURBS object to be destroyed. |
| 1076 | |
| 1077 | @end table |
| 1078 | |
| 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 |
| 1082 | used again. |
| 1083 | |
| 1084 | @end deftypefun |
| 1085 | |
| 1086 | @deftypefun void gluDeleteQuadric quad |
| 1087 | Destroy a quadrics object. |
| 1088 | |
| 1089 | @table @asis |
| 1090 | @item @var{quad} |
| 1091 | Specifies the quadrics object to be destroyed. |
| 1092 | |
| 1093 | @end table |
| 1094 | |
| 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 |
| 1098 | again. |
| 1099 | |
| 1100 | @end deftypefun |
| 1101 | |
| 1102 | @deftypefun void gluDeleteTess tess |
| 1103 | Destroy a tessellation object. |
| 1104 | |
| 1105 | @table @asis |
| 1106 | @item @var{tess} |
| 1107 | Specifies the tessellation object to destroy. |
| 1108 | |
| 1109 | @end table |
| 1110 | |
| 1111 | @code{gluDeleteTess} destroys the indicated tessellation object (which |
| 1112 | was created with @code{gluNewTess}) and frees any memory that it used. |
| 1113 | |
| 1114 | @end deftypefun |
| 1115 | |
| 1116 | @deftypefun void gluDisk quad inner outer slices loops |
| 1117 | Draw a disk. |
| 1118 | |
| 1119 | @table @asis |
| 1120 | @item @var{quad} |
| 1121 | Specifies the quadrics object (created with @code{gluNewQuadric}). |
| 1122 | |
| 1123 | @item @var{inner} |
| 1124 | Specifies the inner radius of the disk (may be 0). |
| 1125 | |
| 1126 | @item @var{outer} |
| 1127 | Specifies the outer radius of the disk. |
| 1128 | |
| 1129 | @item @var{slices} |
| 1130 | Specifies the number of subdivisions around the @var{z} axis. |
| 1131 | |
| 1132 | @item @var{loops} |
| 1133 | Specifies the number of concentric rings about the origin into which the |
| 1134 | disk is subdivided. |
| 1135 | |
| 1136 | @end table |
| 1137 | |
| 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). |
| 1144 | |
| 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} |
| 1149 | axis. |
| 1150 | |
| 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). |
| 1156 | |
| 1157 | @end deftypefun |
| 1158 | |
| 1159 | @deftypefun const-GLubyte-* gluErrorString error |
| 1160 | Produce an error string from a GL or GLU error code. |
| 1161 | |
| 1162 | @table @asis |
| 1163 | @item @var{error} |
| 1164 | Specifies a GL or GLU error code. |
| 1165 | |
| 1166 | @end table |
| 1167 | |
| 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}. |
| 1172 | |
| 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. |
| 1177 | |
| 1178 | @code{NULL} is returned if @var{error} is not a valid GL or GLU error |
| 1179 | code. |
| 1180 | |
| 1181 | @end deftypefun |
| 1182 | |
| 1183 | @deftypefun void gluGetNurbsProperty nurb property data |
| 1184 | Get a NURBS property. |
| 1185 | |
| 1186 | @table @asis |
| 1187 | @item @var{nurb} |
| 1188 | Specifies the NURBS object (created with @code{gluNewNurbsRenderer}). |
| 1189 | |
| 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}. |
| 1196 | |
| 1197 | @item @var{data} |
| 1198 | Specifies a pointer to the location into which the value of the named |
| 1199 | property is written. |
| 1200 | |
| 1201 | @end table |
| 1202 | |
| 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. |
| 1207 | |
| 1208 | @end deftypefun |
| 1209 | |
| 1210 | @deftypefun const-GLubyte-* gluGetString name |
| 1211 | Return a string describing the GLU version or GLU extensions . |
| 1212 | |
| 1213 | @table @asis |
| 1214 | @item @var{name} |
| 1215 | Specifies a symbolic constant, one of @code{GLU_VERSION}, or |
| 1216 | @code{GLU_EXTENSIONS}. |
| 1217 | |
| 1218 | @end table |
| 1219 | |
| 1220 | @code{gluGetString} returns a pointer to a static string describing the |
| 1221 | GLU version or the GLU extensions that are supported. |
| 1222 | |
| 1223 | The version number is one of the following forms: |
| 1224 | |
| 1225 | @var{major_number.minor_number}@var{major_number.minor_number.release_number}. |
| 1226 | |
| 1227 | The version string is of the following form: |
| 1228 | |
| 1229 | @var{version number<space>vendor-specific information} |
| 1230 | |
| 1231 | Vendor-specific information is optional. Its format and contents depend |
| 1232 | on the implementation. |
| 1233 | |
| 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.) |
| 1240 | |
| 1241 | All strings are null-terminated. |
| 1242 | |
| 1243 | NULL is returned if @var{name} is not @code{GLU_VERSION} or |
| 1244 | @code{GLU_EXTENSIONS}. |
| 1245 | |
| 1246 | |
| 1247 | |
| 1248 | @end deftypefun |
| 1249 | |
| 1250 | @deftypefun void gluGetTessProperty tess which data |
| 1251 | Get a tessellation object property. |
| 1252 | |
| 1253 | @table @asis |
| 1254 | @item @var{tess} |
| 1255 | Specifies the tessellation object (created with @code{gluNewTess}). |
| 1256 | |
| 1257 | @item @var{which} |
| 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}. |
| 1261 | |
| 1262 | @item @var{data} |
| 1263 | Specifies a pointer to the location into which the value of the named |
| 1264 | property is written. |
| 1265 | |
| 1266 | @end table |
| 1267 | |
| 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. |
| 1272 | |
| 1273 | @end deftypefun |
| 1274 | |
| 1275 | @deftypefun void gluLoadSamplingMatrices nurb model perspective view |
| 1276 | Load NURBS sampling and culling matrices. |
| 1277 | |
| 1278 | @table @asis |
| 1279 | @item @var{nurb} |
| 1280 | Specifies the NURBS object (created with @code{gluNewNurbsRenderer}). |
| 1281 | |
| 1282 | @item @var{model} |
| 1283 | Specifies a modelview matrix (as from a @code{glGetFloatv} call). |
| 1284 | |
| 1285 | @item @var{perspective} |
| 1286 | Specifies a projection matrix (as from a @code{glGetFloatv} call). |
| 1287 | |
| 1288 | @item @var{view} |
| 1289 | Specifies a viewport (as from a @code{glGetIntegerv} call). |
| 1290 | |
| 1291 | @end table |
| 1292 | |
| 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). |
| 1300 | |
| 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.) |
| 1308 | |
| 1309 | @end deftypefun |
| 1310 | |
| 1311 | @deftypefun void gluLookAt eyeX eyeY eyeZ centerX centerY centerZ upX upY upZ |
| 1312 | Define a viewing transformation. |
| 1313 | |
| 1314 | @table @asis |
| 1315 | @item @var{eyeX} |
| 1316 | @itemx @var{eyeY} |
| 1317 | @itemx @var{eyeZ} |
| 1318 | Specifies the position of the eye point. |
| 1319 | |
| 1320 | @item @var{centerX} |
| 1321 | @itemx @var{centerY} |
| 1322 | @itemx @var{centerZ} |
| 1323 | Specifies the position of the reference point. |
| 1324 | |
| 1325 | @item @var{upX} |
| 1326 | @itemx @var{upY} |
| 1327 | @itemx @var{upZ} |
| 1328 | Specifies the direction of the @var{up} vector. |
| 1329 | |
| 1330 | @end table |
| 1331 | |
| 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} |
| 1334 | vector. |
| 1335 | |
| 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. |
| 1343 | |
| 1344 | Let |
| 1345 | |
| 1346 | @r{@var{F}=((@var{centerX}-@var{eyeX}), (@var{centerY}-@var{eyeY}), |
| 1347 | (@var{centerZ}-@var{eyeZ}),)} |
| 1348 | |
| 1349 | |
| 1350 | |
| 1351 | Let @var{UP} be the vector @r{(@var{upX},@var{upY}@var{upZ})}. |
| 1352 | |
| 1353 | Then normalize as follows: @r{@var{f}=@var{F}/∥@var{F},∥,} |
| 1354 | |
| 1355 | @r{@var{UP}^″=@var{UP}/∥@var{UP},∥,} |
| 1356 | |
| 1357 | |
| 1358 | |
| 1359 | Finally, let @r{@var{s}=@var{f}×@var{UP}^″}, and |
| 1360 | @r{@var{u}=@var{s}×@var{f}}. |
| 1361 | |
| 1362 | |
| 1363 | |
| 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),)} |
| 1367 | |
| 1368 | and @code{gluLookAt} is equivalent to |
| 1369 | |
| 1370 | @example |
| 1371 | |
| 1372 | glMultMatrixf(M); |
| 1373 | glTranslated(-eyex, -eyey, -eyez); |
| 1374 | @end example |
| 1375 | |
| 1376 | @end deftypefun |
| 1377 | |
| 1378 | @deftypefun GLUnurbs* gluNewNurbsRenderer |
| 1379 | Create a NURBS object. |
| 1380 | |
| 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. |
| 1385 | |
| 1386 | @end deftypefun |
| 1387 | |
| 1388 | @deftypefun GLUquadric* gluNewQuadric |
| 1389 | Create a quadrics object. |
| 1390 | |
| 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. |
| 1395 | |
| 1396 | @end deftypefun |
| 1397 | |
| 1398 | @deftypefun GLUtesselator* gluNewTess |
| 1399 | Create a tessellation object. |
| 1400 | |
| 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. |
| 1405 | |
| 1406 | @end deftypefun |
| 1407 | |
| 1408 | @deftypefun void gluNextContour tess type |
| 1409 | Mark the beginning of another contour. |
| 1410 | |
| 1411 | @table @asis |
| 1412 | @item @var{tess} |
| 1413 | Specifies the tessellation object (created with @code{gluNewTess}). |
| 1414 | |
| 1415 | @item @var{type} |
| 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}. |
| 1419 | |
| 1420 | @end table |
| 1421 | |
| 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. |
| 1429 | |
| 1430 | @var{type} defines what type of contour follows. The legal contour types |
| 1431 | are as follows: |
| 1432 | |
| 1433 | @table @asis |
| 1434 | @item @code{GLU_EXTERIOR} |
| 1435 | An exterior contour defines an exterior boundary of the polygon. |
| 1436 | |
| 1437 | @item @code{GLU_INTERIOR} |
| 1438 | An interior contour defines an interior boundary of the polygon (such as |
| 1439 | a hole). |
| 1440 | |
| 1441 | @item @code{GLU_UNKNOWN} |
| 1442 | An unknown contour is analyzed by the library to determine if it is |
| 1443 | interior or exterior. |
| 1444 | |
| 1445 | @item @code{GLU_CCW}, |
| 1446 | @item @code{GLU_CW} |
| 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. |
| 1451 | |
| 1452 | @end table |
| 1453 | |
| 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}). |
| 1458 | |
| 1459 | Note that there is no real difference between the @code{GLU_CCW} and |
| 1460 | @code{GLU_CW} contour types. |
| 1461 | |
| 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}. |
| 1466 | |
| 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}. |
| 1470 | |
| 1471 | @end deftypefun |
| 1472 | |
| 1473 | @deftypefun void gluNurbsCallbackDataEXT nurb userData |
| 1474 | Set a user data pointer. |
| 1475 | |
| 1476 | @table @asis |
| 1477 | @item @var{nurb} |
| 1478 | Specifies the NURBS object (created with @code{gluNewNurbsRenderer}). |
| 1479 | |
| 1480 | @item @var{userData} |
| 1481 | Specifies a pointer to the user's data. |
| 1482 | |
| 1483 | @end table |
| 1484 | |
| 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}). |
| 1489 | |
| 1490 | @end deftypefun |
| 1491 | |
| 1492 | @deftypefun void gluNurbsCallbackData nurb userData |
| 1493 | Set a user data pointer. |
| 1494 | |
| 1495 | @table @asis |
| 1496 | @item @var{nurb} |
| 1497 | Specifies the NURBS object (created with @code{gluNewNurbsRenderer}). |
| 1498 | |
| 1499 | @item @var{userData} |
| 1500 | Specifies a pointer to the user's data. |
| 1501 | |
| 1502 | @end table |
| 1503 | |
| 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}). |
| 1508 | |
| 1509 | @end deftypefun |
| 1510 | |
| 1511 | @deftypefun void gluNurbsCallback nurb which CallBackFunc |
| 1512 | Define a callback for a NURBS object. |
| 1513 | |
| 1514 | @table @asis |
| 1515 | @item @var{nurb} |
| 1516 | Specifies the NURBS object (created with @code{gluNewNurbsRenderer}). |
| 1517 | |
| 1518 | @item @var{which} |
| 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}. |
| 1527 | |
| 1528 | @item @var{CallBackFunc} |
| 1529 | Specifies the function that the callback calls. |
| 1530 | |
| 1531 | @end table |
| 1532 | |
| 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. |
| 1537 | |
| 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}. |
| 1546 | |
| 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}. |
| 1551 | |
| 1552 | The legal callbacks are as follows: |
| 1553 | |
| 1554 | @table @asis |
| 1555 | @item @code{GLU_NURBS_BEGIN} |
| 1556 | |
| 1557 | |
| 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: |
| 1564 | |
| 1565 | @item @code{GLU_NURBS_BEGIN_DATA} |
| 1566 | |
| 1567 | |
| 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: |
| 1573 | |
| 1574 | @item @code{GLU_NURBS_VERTEX} |
| 1575 | |
| 1576 | |
| 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 |
| 1582 | looks like: |
| 1583 | |
| 1584 | @item @code{GLU_NURBS_VERTEX_DATA} |
| 1585 | |
| 1586 | |
| 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: |
| 1592 | |
| 1593 | @item @code{GLU_NURBS_NORMAL} |
| 1594 | |
| 1595 | |
| 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: |
| 1606 | |
| 1607 | @item @code{GLU_NURBS_NORMAL_DATA} |
| 1608 | |
| 1609 | |
| 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: |
| 1615 | |
| 1616 | @item @code{GLU_NURBS_COLOR} |
| 1617 | |
| 1618 | |
| 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: |
| 1625 | |
| 1626 | @item @code{GLU_NURBS_COLOR_DATA} |
| 1627 | |
| 1628 | |
| 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: |
| 1634 | |
| 1635 | @item @code{GLU_NURBS_TEXTURE_COORD} |
| 1636 | |
| 1637 | |
| 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: |
| 1649 | |
| 1650 | @item @code{GLU_NURBS_TEXTURE_COORD_DATA} |
| 1651 | |
| 1652 | |
| 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: |
| 1658 | |
| 1659 | @item @code{GLU_NURBS_END} |
| 1660 | |
| 1661 | |
| 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: |
| 1665 | |
| 1666 | @item @code{GLU_NURBS_END_DATA} |
| 1667 | |
| 1668 | |
| 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: |
| 1674 | |
| 1675 | @item @code{GLU_NURBS_ERROR} |
| 1676 | |
| 1677 | |
| 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}. |
| 1684 | |
| 1685 | @end table |
| 1686 | |
| 1687 | @example |
| 1688 | |
| 1689 | void begin( GLenum type ); |
| 1690 | @end example |
| 1691 | |
| 1692 | @example |
| 1693 | |
| 1694 | void beginData(GLenum type, void *userData); |
| 1695 | @end example |
| 1696 | |
| 1697 | @example |
| 1698 | |
| 1699 | void vertex( GLfloat *vertex ); |
| 1700 | @end example |
| 1701 | |
| 1702 | @example |
| 1703 | |
| 1704 | void vertexData( GLfloat *vertex, void *userData ); |
| 1705 | @end example |
| 1706 | |
| 1707 | @example |
| 1708 | |
| 1709 | void normal( GLfloat *normal ); |
| 1710 | @end example |
| 1711 | |
| 1712 | @example |
| 1713 | |
| 1714 | void normalData( GLfloat *normal, void *userData ); |
| 1715 | @end example |
| 1716 | |
| 1717 | @example |
| 1718 | |
| 1719 | void color( GLfloat *color ); |
| 1720 | @end example |
| 1721 | |
| 1722 | @example |
| 1723 | |
| 1724 | void colorData( GLfloat *color, void *userData ); |
| 1725 | @end example |
| 1726 | |
| 1727 | @example |
| 1728 | |
| 1729 | void texCoord( GLfloat *texCoord ); |
| 1730 | @end example |
| 1731 | |
| 1732 | @example |
| 1733 | |
| 1734 | void texCoordData( GLfloat *texCoord, void *userData ); |
| 1735 | @end example |
| 1736 | |
| 1737 | @example |
| 1738 | |
| 1739 | void end( void ); |
| 1740 | @end example |
| 1741 | |
| 1742 | @example |
| 1743 | |
| 1744 | void endData( void *userData ); |
| 1745 | @end example |
| 1746 | |
| 1747 | @end deftypefun |
| 1748 | |
| 1749 | @deftypefun void gluNurbsCurve nurb knotCount knots stride control order type |
| 1750 | Define the shape of a NURBS curve. |
| 1751 | |
| 1752 | @table @asis |
| 1753 | @item @var{nurb} |
| 1754 | Specifies the NURBS object (created with @code{gluNewNurbsRenderer}). |
| 1755 | |
| 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. |
| 1759 | |
| 1760 | @item @var{knots} |
| 1761 | Specifies an array of @var{knotCount} nondecreasing knot values. |
| 1762 | |
| 1763 | @item @var{stride} |
| 1764 | Specifies the offset (as a number of single-precision floating-point |
| 1765 | values) between successive curve control points. |
| 1766 | |
| 1767 | @item @var{control} |
| 1768 | Specifies a pointer to an array of control points. The coordinates must |
| 1769 | agree with @var{type}, specified below. |
| 1770 | |
| 1771 | @item @var{order} |
| 1772 | Specifies the order of the NURBS curve. @var{order} equals degree + 1, |
| 1773 | hence a cubic curve has an order of 4. |
| 1774 | |
| 1775 | @item @var{type} |
| 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}. |
| 1782 | |
| 1783 | @end table |
| 1784 | |
| 1785 | Use @code{gluNurbsCurve} to describe a NURBS curve. |
| 1786 | |
| 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}). |
| 1796 | |
| 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. |
| 1805 | |
| 1806 | @end deftypefun |
| 1807 | |
| 1808 | @deftypefun void gluNurbsProperty nurb property value |
| 1809 | Set a NURBS property. |
| 1810 | |
| 1811 | @table @asis |
| 1812 | @item @var{nurb} |
| 1813 | Specifies the NURBS object (created with @code{gluNewNurbsRenderer}). |
| 1814 | |
| 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}. |
| 1821 | |
| 1822 | @item @var{value} |
| 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}. |
| 1829 | |
| 1830 | @end table |
| 1831 | |
| 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: |
| 1835 | |
| 1836 | @table @asis |
| 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}. |
| 1847 | |
| 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}. |
| 1856 | |
| 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. |
| 1861 | |
| 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. |
| 1865 | |
| 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}. |
| 1871 | |
| 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 |
| 1877 | approximate. |
| 1878 | |
| 1879 | The initial value of @code{GLU_SAMPLING_METHOD} is |
| 1880 | @code{GLU_PATH_LENGTH}. |
| 1881 | |
| 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. |
| 1888 | |
| 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. |
| 1893 | |
| 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. |
| 1899 | |
| 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. |
| 1905 | |
| 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. |
| 1916 | |
| 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. |
| 1926 | |
| 1927 | The initial value is @code{GLU_FILL}. |
| 1928 | |
| 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}. |
| 1934 | |
| 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 |
| 1942 | viewport. |
| 1943 | |
| 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. |
| 1951 | |
| 1952 | @end table |
| 1953 | |
| 1954 | @end deftypefun |
| 1955 | |
| 1956 | @deftypefun void gluNurbsSurface nurb sKnotCount sKnots tKnotCount tKnots sStride tStride control sOrder tOrder type |
| 1957 | Define the shape of a NURBS surface. |
| 1958 | |
| 1959 | @table @asis |
| 1960 | @item @var{nurb} |
| 1961 | Specifies the NURBS object (created with @code{gluNewNurbsRenderer}). |
| 1962 | |
| 1963 | @item @var{sKnotCount} |
| 1964 | Specifies the number of knots in the parametric @var{u} direction. |
| 1965 | |
| 1966 | @item @var{sKnots} |
| 1967 | Specifies an array of @var{sKnotCount} nondecreasing knot values in the |
| 1968 | parametric @var{u} direction. |
| 1969 | |
| 1970 | @item @var{tKnotCount} |
| 1971 | Specifies the number of knots in the parametric @var{v} direction. |
| 1972 | |
| 1973 | @item @var{tKnots} |
| 1974 | Specifies an array of @var{tKnotCount} nondecreasing knot values in the |
| 1975 | parametric @var{v} direction. |
| 1976 | |
| 1977 | @item @var{sStride} |
| 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}. |
| 1981 | |
| 1982 | @item @var{tStride} |
| 1983 | Specifies the offset (in single-precision floating-point values) between |
| 1984 | successive control points in the parametric @var{v} direction in |
| 1985 | @var{control}. |
| 1986 | |
| 1987 | @item @var{control} |
| 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}. |
| 1991 | |
| 1992 | @item @var{sOrder} |
| 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. |
| 1996 | |
| 1997 | @item @var{tOrder} |
| 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. |
| 2001 | |
| 2002 | @item @var{type} |
| 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}). |
| 2006 | |
| 2007 | @end table |
| 2008 | |
| 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. |
| 2015 | |
| 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}). |
| 2024 | |
| 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}. |
| 2028 | |
| 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 |
| 2033 | points. |
| 2034 | |
| 2035 | @end deftypefun |
| 2036 | |
| 2037 | @deftypefun void gluOrtho2D left right bottom top |
| 2038 | Define a 2D orthographic projection matrix. |
| 2039 | |
| 2040 | @table @asis |
| 2041 | @item @var{left} |
| 2042 | @itemx @var{right} |
| 2043 | Specify the coordinates for the left and right vertical clipping planes. |
| 2044 | |
| 2045 | @item @var{bottom} |
| 2046 | @itemx @var{top} |
| 2047 | Specify the coordinates for the bottom and top horizontal clipping |
| 2048 | planes. |
| 2049 | |
| 2050 | @end table |
| 2051 | |
| 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 |
| 2054 | @r{@var{far}=1}. |
| 2055 | |
| 2056 | @end deftypefun |
| 2057 | |
| 2058 | @deftypefun void gluPartialDisk quad inner outer slices loops start sweep |
| 2059 | Draw an arc of a disk. |
| 2060 | |
| 2061 | @table @asis |
| 2062 | @item @var{quad} |
| 2063 | Specifies a quadrics object (created with @code{gluNewQuadric}). |
| 2064 | |
| 2065 | @item @var{inner} |
| 2066 | Specifies the inner radius of the partial disk (can be 0). |
| 2067 | |
| 2068 | @item @var{outer} |
| 2069 | Specifies the outer radius of the partial disk. |
| 2070 | |
| 2071 | @item @var{slices} |
| 2072 | Specifies the number of subdivisions around the @var{z} axis. |
| 2073 | |
| 2074 | @item @var{loops} |
| 2075 | Specifies the number of concentric rings about the origin into which the |
| 2076 | partial disk is subdivided. |
| 2077 | |
| 2078 | @item @var{start} |
| 2079 | Specifies the starting angle, in degrees, of the disk portion. |
| 2080 | |
| 2081 | @item @var{sweep} |
| 2082 | Specifies the sweep angle, in degrees, of the disk portion. |
| 2083 | |
| 2084 | @end table |
| 2085 | |
| 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). |
| 2092 | |
| 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). |
| 2098 | |
| 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 |
| 2103 | \-@var{z} axis. |
| 2104 | |
| 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). |
| 2110 | |
| 2111 | @end deftypefun |
| 2112 | |
| 2113 | @deftypefun void gluPerspective fovy aspect zNear zFar |
| 2114 | Set up a perspective projection matrix. |
| 2115 | |
| 2116 | @table @asis |
| 2117 | @item @var{fovy} |
| 2118 | Specifies the field of view angle, in degrees, in the @var{y} direction. |
| 2119 | |
| 2120 | @item @var{aspect} |
| 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 |
| 2123 | @var{y} (height). |
| 2124 | |
| 2125 | @item @var{zNear} |
| 2126 | Specifies the distance from the viewer to the near clipping plane |
| 2127 | (always positive). |
| 2128 | |
| 2129 | @item @var{zFar} |
| 2130 | Specifies the distance from the viewer to the far clipping plane (always |
| 2131 | positive). |
| 2132 | |
| 2133 | @end table |
| 2134 | |
| 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. |
| 2141 | |
| 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}. |
| 2147 | |
| 2148 | Given @var{f} defined as follows: |
| 2149 | |
| 2150 | @r{@var{f}=@var{cotangent}(@var{fovy}/2,)} The generated matrix is |
| 2151 | |
| 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),)} |
| 2155 | |
| 2156 | @end deftypefun |
| 2157 | |
| 2158 | @deftypefun void gluPickMatrix x y delX delY viewport |
| 2159 | Define a picking region. |
| 2160 | |
| 2161 | @table @asis |
| 2162 | @item @var{x} |
| 2163 | @itemx @var{y} |
| 2164 | Specify the center of a picking region in window coordinates. |
| 2165 | |
| 2166 | @item @var{delX} |
| 2167 | @itemx @var{delY} |
| 2168 | Specify the width and height, respectively, of the picking region in |
| 2169 | window coordinates. |
| 2170 | |
| 2171 | @item @var{viewport} |
| 2172 | Specifies the current viewport (as from a @code{glGetIntegerv} call). |
| 2173 | |
| 2174 | @end table |
| 2175 | |
| 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. |
| 2183 | |
| 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. |
| 2191 | |
| 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. |
| 2197 | |
| 2198 | @end deftypefun |
| 2199 | |
| 2200 | @deftypefun GLint gluProject objX objY objZ model proj view winX winY winZ |
| 2201 | Map object coordinates to window coordinates. |
| 2202 | |
| 2203 | @table @asis |
| 2204 | @item @var{objX} |
| 2205 | @itemx @var{objY} |
| 2206 | @itemx @var{objZ} |
| 2207 | Specify the object coordinates. |
| 2208 | |
| 2209 | @item @var{model} |
| 2210 | Specifies the current modelview matrix (as from a @code{glGetDoublev} |
| 2211 | call). |
| 2212 | |
| 2213 | @item @var{proj} |
| 2214 | Specifies the current projection matrix (as from a @code{glGetDoublev} |
| 2215 | call). |
| 2216 | |
| 2217 | @item @var{view} |
| 2218 | Specifies the current viewport (as from a @code{glGetIntegerv} call). |
| 2219 | |
| 2220 | @item @var{winX} |
| 2221 | @itemx @var{winY} |
| 2222 | @itemx @var{winZ} |
| 2223 | Return the computed window coordinates. |
| 2224 | |
| 2225 | @end table |
| 2226 | |
| 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. |
| 2232 | |
| 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}^″} |
| 2236 | as follows: |
| 2237 | |
| 2238 | @r{@var{v}^″=@var{P}×@var{M}×@var{v}} |
| 2239 | |
| 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). |
| 2243 | |
| 2244 | The window coordinates are then computed as follows: |
| 2245 | |
| 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} |
| 2248 | |
| 2249 | |
| 2250 | |
| 2251 | @end deftypefun |
| 2252 | |
| 2253 | @deftypefun void gluPwlCurve nurb count data stride type |
| 2254 | Describe a piecewise linear NURBS trimming curve. |
| 2255 | |
| 2256 | @table @asis |
| 2257 | @item @var{nurb} |
| 2258 | Specifies the NURBS object (created with @code{gluNewNurbsRenderer}). |
| 2259 | |
| 2260 | @item @var{count} |
| 2261 | Specifies the number of points on the curve. |
| 2262 | |
| 2263 | @item @var{data} |
| 2264 | Specifies an array containing the curve points. |
| 2265 | |
| 2266 | @item @var{stride} |
| 2267 | Specifies the offset (a number of single-precision floating-point |
| 2268 | values) between points on the curve. |
| 2269 | |
| 2270 | @item @var{type} |
| 2271 | Specifies the type of curve. Must be either @code{GLU_MAP1_TRIM_2} or |
| 2272 | @code{GLU_MAP1_TRIM_3}. |
| 2273 | |
| 2274 | @end table |
| 2275 | |
| 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. |
| 2283 | |
| 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 |
| 2289 | curves. |
| 2290 | |
| 2291 | @end deftypefun |
| 2292 | |
| 2293 | @deftypefun void gluQuadricCallback quad which CallBackFunc |
| 2294 | Define a callback for a quadrics object. |
| 2295 | |
| 2296 | @table @asis |
| 2297 | @item @var{quad} |
| 2298 | Specifies the quadrics object (created with @code{gluNewQuadric}). |
| 2299 | |
| 2300 | @item @var{which} |
| 2301 | Specifies the callback being defined. The only valid value is |
| 2302 | @code{GLU_ERROR}. |
| 2303 | |
| 2304 | @item @var{CallBackFunc} |
| 2305 | Specifies the function to be called. |
| 2306 | |
| 2307 | @end table |
| 2308 | |
| 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 |
| 2312 | is erased. |
| 2313 | |
| 2314 | The one legal callback is @code{GLU_ERROR}: |
| 2315 | |
| 2316 | @table @asis |
| 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. |
| 2322 | |
| 2323 | @end table |
| 2324 | |
| 2325 | @end deftypefun |
| 2326 | |
| 2327 | @deftypefun void gluQuadricDrawStyle quad draw |
| 2328 | Specify the draw style desired for quadrics. |
| 2329 | |
| 2330 | @table @asis |
| 2331 | @item @var{quad} |
| 2332 | Specifies the quadrics object (created with @code{gluNewQuadric}). |
| 2333 | |
| 2334 | @item @var{draw} |
| 2335 | Specifies the desired draw style. Valid values are @code{GLU_FILL}, |
| 2336 | @code{GLU_LINE}, @code{GLU_SILHOUETTE}, and @code{GLU_POINT}. |
| 2337 | |
| 2338 | @end table |
| 2339 | |
| 2340 | @code{gluQuadricDrawStyle} specifies the draw style for quadrics |
| 2341 | rendered with @var{quad}. The legal values are as follows: |
| 2342 | |
| 2343 | @table @asis |
| 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}). |
| 2348 | |
| 2349 | @item @code{GLU_LINE} |
| 2350 | Quadrics are rendered as a set of lines. |
| 2351 | |
| 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. |
| 2355 | |
| 2356 | @item @code{GLU_POINT} |
| 2357 | Quadrics are rendered as a set of points. |
| 2358 | |
| 2359 | @end table |
| 2360 | |
| 2361 | @end deftypefun |
| 2362 | |
| 2363 | @deftypefun void gluQuadricNormals quad normal |
| 2364 | Specify what kind of normals are desired for quadrics. |
| 2365 | |
| 2366 | @table @asis |
| 2367 | @item @var{quad} |
| 2368 | Specifies the quadrics object (created with @code{gluNewQuadric}). |
| 2369 | |
| 2370 | @item @var{normal} |
| 2371 | Specifies the desired type of normals. Valid values are @code{GLU_NONE}, |
| 2372 | @code{GLU_FLAT}, and @code{GLU_SMOOTH}. |
| 2373 | |
| 2374 | @end table |
| 2375 | |
| 2376 | @code{gluQuadricNormals} specifies what kind of normals are desired for |
| 2377 | quadrics rendered with @var{quad}. The legal values are as follows: |
| 2378 | |
| 2379 | @table @asis |
| 2380 | @item @code{GLU_NONE} |
| 2381 | No normals are generated. |
| 2382 | |
| 2383 | @item @code{GLU_FLAT} |
| 2384 | One normal is generated for every facet of a quadric. |
| 2385 | |
| 2386 | @item @code{GLU_SMOOTH} |
| 2387 | One normal is generated for every vertex of a quadric. This is the |
| 2388 | initial value. |
| 2389 | |
| 2390 | @end table |
| 2391 | |
| 2392 | @end deftypefun |
| 2393 | |
| 2394 | @deftypefun void gluQuadricOrientation quad orientation |
| 2395 | Specify inside/outside orientation for quadrics. |
| 2396 | |
| 2397 | @table @asis |
| 2398 | @item @var{quad} |
| 2399 | Specifies the quadrics object (created with @code{gluNewQuadric}). |
| 2400 | |
| 2401 | @item @var{orientation} |
| 2402 | Specifies the desired orientation. Valid values are @code{GLU_OUTSIDE} |
| 2403 | and @code{GLU_INSIDE}. |
| 2404 | |
| 2405 | @end table |
| 2406 | |
| 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: |
| 2410 | |
| 2411 | @table @asis |
| 2412 | @item @code{GLU_OUTSIDE} |
| 2413 | Quadrics are drawn with normals pointing outward (the initial value). |
| 2414 | |
| 2415 | @item @code{GLU_INSIDE} |
| 2416 | Quadrics are drawn with normals pointing inward. |
| 2417 | |
| 2418 | @end table |
| 2419 | |
| 2420 | Note that the interpretation of @var{outward} and @var{inward} depends |
| 2421 | on the quadric being drawn. |
| 2422 | |
| 2423 | @end deftypefun |
| 2424 | |
| 2425 | @deftypefun void gluQuadricTexture quad texture |
| 2426 | Specify if texturing is desired for quadrics. |
| 2427 | |
| 2428 | @table @asis |
| 2429 | @item @var{quad} |
| 2430 | Specifies the quadrics object (created with @code{gluNewQuadric}). |
| 2431 | |
| 2432 | @item @var{texture} |
| 2433 | Specifies a flag indicating if texture coordinates should be generated. |
| 2434 | |
| 2435 | @end table |
| 2436 | |
| 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}. |
| 2442 | |
| 2443 | The manner in which texture coordinates are generated depends upon the |
| 2444 | specific quadric rendered. |
| 2445 | |
| 2446 | @end deftypefun |
| 2447 | |
| 2448 | @deftypefun GLint gluScaleImage format wIn hIn typeIn dataIn wOut hOut typeOut dataOut |
| 2449 | Scale an image to an arbitrary size. |
| 2450 | |
| 2451 | @table @asis |
| 2452 | @item @var{format} |
| 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}. |
| 2459 | |
| 2460 | @item @var{wIn} |
| 2461 | @itemx @var{hIn} |
| 2462 | Specify in pixels the width and height, respectively, of the source |
| 2463 | image. |
| 2464 | |
| 2465 | @item @var{typeIn} |
| 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}. |
| 2477 | |
| 2478 | @item @var{dataIn} |
| 2479 | Specifies a pointer to the source image. |
| 2480 | |
| 2481 | @item @var{wOut} |
| 2482 | @itemx @var{hOut} |
| 2483 | Specify the width and height, respectively, in pixels of the destination |
| 2484 | image. |
| 2485 | |
| 2486 | @item @var{typeOut} |
| 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}. |
| 2498 | |
| 2499 | @item @var{dataOut} |
| 2500 | Specifies a pointer to the destination image. |
| 2501 | |
| 2502 | @end table |
| 2503 | |
| 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 |
| 2506 | destination image. |
| 2507 | |
| 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. |
| 2512 | |
| 2513 | A return value of zero indicates success, otherwise a GLU error code is |
| 2514 | returned (see @code{gluErrorString}). |
| 2515 | |
| 2516 | See the @code{glReadPixels} reference page for a description of the |
| 2517 | acceptable values for the @var{format}, @var{typeIn}, and @var{typeOut} |
| 2518 | parameters. |
| 2519 | |
| 2520 | @code{GLU_INVALID_VALUE} is returned if @var{wIn}, @var{hIn}, |
| 2521 | @var{wOut}, or @var{hOut} is negative. |
| 2522 | |
| 2523 | @code{GLU_INVALID_ENUM} is returned if @var{format}, @var{typeIn}, or |
| 2524 | @var{typeOut} is not legal. |
| 2525 | |
| 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 |
| 2529 | @code{GLU_RGB}. |
| 2530 | |
| 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 |
| 2534 | @code{GLU_RGB}. |
| 2535 | |
| 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}. |
| 2540 | |
| 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}. |
| 2545 | |
| 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}. |
| 2550 | |
| 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}. |
| 2555 | |
| 2556 | @end deftypefun |
| 2557 | |
| 2558 | @deftypefun void gluSphere quad radius slices stacks |
| 2559 | Draw a sphere. |
| 2560 | |
| 2561 | @table @asis |
| 2562 | @item @var{quad} |
| 2563 | Specifies the quadrics object (created with @code{gluNewQuadric}). |
| 2564 | |
| 2565 | @item @var{radius} |
| 2566 | Specifies the radius of the sphere. |
| 2567 | |
| 2568 | @item @var{slices} |
| 2569 | Specifies the number of subdivisions around the @var{z} axis (similar to |
| 2570 | lines of longitude). |
| 2571 | |
| 2572 | @item @var{stacks} |
| 2573 | Specifies the number of subdivisions along the @var{z} axis (similar to |
| 2574 | lines of latitude). |
| 2575 | |
| 2576 | @end table |
| 2577 | |
| 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 |
| 2581 | latitude). |
| 2582 | |
| 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 |
| 2586 | of the sphere. |
| 2587 | |
| 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 |
| 2594 | +@var{y} axis. |
| 2595 | |
| 2596 | @end deftypefun |
| 2597 | |
| 2598 | @deftypefun void gluTessBeginContour tess |
| 2599 | @deftypefunx void gluTessEndContour tess |
| 2600 | Delimit a contour description. |
| 2601 | |
| 2602 | @table @asis |
| 2603 | @item @var{tess} |
| 2604 | Specifies the tessellation object (created with @code{gluNewTess}). |
| 2605 | |
| 2606 | @end table |
| 2607 | |
| 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}. |
| 2616 | |
| 2617 | @end deftypefun |
| 2618 | |
| 2619 | @deftypefun void gluTessBeginPolygon tess data |
| 2620 | Delimit a polygon description. |
| 2621 | |
| 2622 | @table @asis |
| 2623 | @item @var{tess} |
| 2624 | Specifies the tessellation object (created with @code{gluNewTess}). |
| 2625 | |
| 2626 | @item @var{data} |
| 2627 | Specifies a pointer to user polygon data. |
| 2628 | |
| 2629 | @end table |
| 2630 | |
| 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 |
| 2640 | for more details. |
| 2641 | |
| 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. |
| 2646 | |
| 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. |
| 2650 | |
| 2651 | @end deftypefun |
| 2652 | |
| 2653 | @deftypefun void gluTessCallback tess which CallBackFunc |
| 2654 | Define a callback for a tessellation object. |
| 2655 | |
| 2656 | @table @asis |
| 2657 | @item @var{tess} |
| 2658 | Specifies the tessellation object (created with @code{gluNewTess}). |
| 2659 | |
| 2660 | @item @var{which} |
| 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}. |
| 2668 | |
| 2669 | @item @var{CallBackFunc} |
| 2670 | Specifies the function to be called. |
| 2671 | |
| 2672 | @end table |
| 2673 | |
| 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. |
| 2678 | |
| 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 |
| 2687 | follows: |
| 2688 | |
| 2689 | @table @asis |
| 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: |
| 2699 | |
| 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: |
| 2705 | |
| 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. |
| 2715 | |
| 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: |
| 2722 | |
| 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: |
| 2728 | |
| 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: |
| 2736 | |
| 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: |
| 2742 | |
| 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: |
| 2747 | |
| 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: |
| 2753 | |
| 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: |
| 2760 | |
| 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. |
| 2766 | |
| 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. |
| 2772 | |
| 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: |
| 2776 | |
| 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. |
| 2782 | |
| 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: |
| 2788 | |
| 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: |
| 2800 | |
| 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. |
| 2812 | |
| 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: |
| 2818 | |
| 2819 | @end table |
| 2820 | |
| 2821 | @example |
| 2822 | |
| 2823 | void begin( GLenum type ); |
| 2824 | @end example |
| 2825 | |
| 2826 | @example |
| 2827 | |
| 2828 | void beginData( GLenum type, void *polygon_data ); |
| 2829 | @end example |
| 2830 | |
| 2831 | @example |
| 2832 | |
| 2833 | void edgeFlag( GLboolean flag ); |
| 2834 | @end example |
| 2835 | |
| 2836 | @example |
| 2837 | |
| 2838 | void edgeFlagData( GLboolean flag, void *polygon_data ); |
| 2839 | @end example |
| 2840 | |
| 2841 | @example |
| 2842 | |
| 2843 | void vertex( void *vertex_data ); |
| 2844 | @end example |
| 2845 | |
| 2846 | @example |
| 2847 | |
| 2848 | void vertexData( void *vertex_data, void *polygon_data ); |
| 2849 | @end example |
| 2850 | |
| 2851 | @example |
| 2852 | |
| 2853 | void end( void ); |
| 2854 | @end example |
| 2855 | |
| 2856 | @example |
| 2857 | |
| 2858 | void endData( void *polygon_data ); |
| 2859 | @end example |
| 2860 | |
| 2861 | @example |
| 2862 | |
| 2863 | void combine( GLdouble coords[3], void *vertex_data[4], |
| 2864 | GLfloat weight[4], void **outData ); |
| 2865 | @end example |
| 2866 | |
| 2867 | @example |
| 2868 | |
| 2869 | void myCombine( GLdouble coords[3], VERTEX *d[4], |
| 2870 | GLfloat w[4], VERTEX **dataOut ) |
| 2871 | @{ |
| 2872 | VERTEX *new = new_vertex(); |
| 2873 | |
| 2874 | new->x = coords[0]; |
| 2875 | new->y = coords[1]; |
| 2876 | new->z = coords[2]; |
| 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; |
| 2881 | *dataOut = new; |
| 2882 | @} |
| 2883 | @end example |
| 2884 | |
| 2885 | @example |
| 2886 | |
| 2887 | void combineData( GLdouble coords[3], void *vertex_data[4], |
| 2888 | GLfloat weight[4], void **outData, |
| 2889 | void *polygon_data ); |
| 2890 | @end example |
| 2891 | |
| 2892 | @example |
| 2893 | |
| 2894 | void error( GLenum errno ); |
| 2895 | @end example |
| 2896 | |
| 2897 | @example |
| 2898 | |
| 2899 | void errorData( GLenum errno, void *polygon_data ); |
| 2900 | @end example |
| 2901 | |
| 2902 | @end deftypefun |
| 2903 | |
| 2904 | @deftypefun void gluTessEndPolygon tess |
| 2905 | Delimit a polygon description. |
| 2906 | |
| 2907 | @table @asis |
| 2908 | @item @var{tess} |
| 2909 | Specifies the tessellation object (created with @code{gluNewTess}). |
| 2910 | |
| 2911 | @end table |
| 2912 | |
| 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 |
| 2922 | for more details. |
| 2923 | |
| 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. |
| 2927 | |
| 2928 | @end deftypefun |
| 2929 | |
| 2930 | @deftypefun void gluTessNormal tess valueX valueY valueZ |
| 2931 | Specify a normal for a polygon. |
| 2932 | |
| 2933 | @table @asis |
| 2934 | @item @var{tess} |
| 2935 | Specifies the tessellation object (created with @code{gluNewTess}). |
| 2936 | |
| 2937 | @item @var{valueX} |
| 2938 | Specifies the first component of the normal. |
| 2939 | |
| 2940 | @item @var{valueY} |
| 2941 | Specifies the second component of the normal. |
| 2942 | |
| 2943 | @item @var{valueZ} |
| 2944 | Specifies the third component of the normal. |
| 2945 | |
| 2946 | @end table |
| 2947 | |
| 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 |
| 2955 | any polygons. |
| 2956 | |
| 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). |
| 2965 | |
| 2966 | The supplied normal persists until it is changed by another call to |
| 2967 | @code{gluTessNormal}. |
| 2968 | |
| 2969 | @end deftypefun |
| 2970 | |
| 2971 | @deftypefun void gluTessProperty tess which data |
| 2972 | Set a tessellation object property. |
| 2973 | |
| 2974 | @table @asis |
| 2975 | @item @var{tess} |
| 2976 | Specifies the tessellation object (created with @code{gluNewTess}). |
| 2977 | |
| 2978 | @item @var{which} |
| 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}. |
| 2982 | |
| 2983 | @item @var{data} |
| 2984 | Specifies the value of the indicated property. |
| 2985 | |
| 2986 | @end table |
| 2987 | |
| 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 |
| 2991 | follows: |
| 2992 | |
| 2993 | @table @asis |
| 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}. |
| 3000 | |
| 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. |
| 3004 | |
| 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. |
| 3011 | |
| 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 |
| 3017 | CSG operations. |
| 3018 | |
| 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 |
| 3026 | contour. |
| 3027 | |
| 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. |
| 3036 | |
| 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. |
| 3040 | |
| 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. |
| 3046 | |
| 3047 | @end table |
| 3048 | |
| 3049 | @end deftypefun |
| 3050 | |
| 3051 | @deftypefun void gluTessVertex tess location data |
| 3052 | Specify a vertex on a polygon. |
| 3053 | |
| 3054 | @table @asis |
| 3055 | @item @var{tess} |
| 3056 | Specifies the tessellation object (created with @code{gluNewTess}). |
| 3057 | |
| 3058 | @item @var{location} |
| 3059 | Specifies the location of the vertex. |
| 3060 | |
| 3061 | @item @var{data} |
| 3062 | Specifies an opaque pointer passed back to the program with the vertex |
| 3063 | callback (as specified by @code{gluTessCallback}). |
| 3064 | |
| 3065 | @end table |
| 3066 | |
| 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}. |
| 3072 | |
| 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). |
| 3078 | |
| 3079 | @end deftypefun |
| 3080 | |
| 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. |
| 3083 | |
| 3084 | @table @asis |
| 3085 | @item @var{winX} |
| 3086 | @itemx @var{winY} |
| 3087 | @itemx @var{winZ} |
| 3088 | Specify the window coordinates to be mapped. |
| 3089 | |
| 3090 | @item @var{clipW} |
| 3091 | Specify the clip w coordinate to be mapped. |
| 3092 | |
| 3093 | @item @var{model} |
| 3094 | Specifies the modelview matrix (as from a @code{glGetDoublev} call). |
| 3095 | |
| 3096 | @item @var{proj} |
| 3097 | Specifies the projection matrix (as from a @code{glGetDoublev} call). |
| 3098 | |
| 3099 | @item @var{view} |
| 3100 | Specifies the viewport (as from a @code{glGetIntegerv} call). |
| 3101 | |
| 3102 | @item @var{nearVal} |
| 3103 | @itemx @var{farVal} |
| 3104 | Specifies the near and far planes (as from a @code{glGetDoublev} call). |
| 3105 | |
| 3106 | @item @var{objX} |
| 3107 | @itemx @var{objY} |
| 3108 | @itemx @var{objZ} |
| 3109 | @itemx @var{objW} |
| 3110 | Returns the computed object coordinates. |
| 3111 | |
| 3112 | @end table |
| 3113 | |
| 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. |
| 3123 | |
| 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: |
| 3128 | |
| 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), |
| 3133 | (@var{clipW}),)} |
| 3134 | |
| 3135 | @r{@var{INV}} denotes matrix inversion. |
| 3136 | |
| 3137 | @code{gluUnProject4} is equivalent to @code{gluUnProject} when |
| 3138 | @var{clipW} is 1, @var{nearVal} is 0, and @var{farVal} is 1. |
| 3139 | |
| 3140 | @end deftypefun |
| 3141 | |
| 3142 | @deftypefun GLint gluUnProject winX winY winZ model proj view objX objY objZ |
| 3143 | Map window coordinates to object coordinates. |
| 3144 | |
| 3145 | @table @asis |
| 3146 | @item @var{winX} |
| 3147 | @itemx @var{winY} |
| 3148 | @itemx @var{winZ} |
| 3149 | Specify the window coordinates to be mapped. |
| 3150 | |
| 3151 | @item @var{model} |
| 3152 | Specifies the modelview matrix (as from a @code{glGetDoublev} call). |
| 3153 | |
| 3154 | @item @var{proj} |
| 3155 | Specifies the projection matrix (as from a @code{glGetDoublev} call). |
| 3156 | |
| 3157 | @item @var{view} |
| 3158 | Specifies the viewport (as from a @code{glGetIntegerv} call). |
| 3159 | |
| 3160 | @item @var{objX} |
| 3161 | @itemx @var{objY} |
| 3162 | @itemx @var{objZ} |
| 3163 | Returns the computed object coordinates. |
| 3164 | |
| 3165 | @end table |
| 3166 | |
| 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} |
| 3171 | indicates failure. |
| 3172 | |
| 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: |
| 3176 | |
| 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. |
| 3182 | |
| 3183 | @end deftypefun |
| 3184 | |
| 3185 | |
| 3186 | @c %end of fragment |