0
# GLU Utilities
1

2
OpenGL Utility Library (GLU) providing high-level convenience functions for common OpenGL operations including perspective projection, coordinate transformations, geometric primitive rendering, polygon tessellation, and NURBS surface generation.
3

4
## Capabilities
5

6
### Projection and Viewing
7

8
Viewing transformation utilities that simplify camera setup and coordinate system management.
9

10
```python { .api }
11
def gluPerspective(fovy: float, aspect: float, zNear: float, zFar: float):
12
    """
13
    Set up perspective projection matrix.
14
    
15
    Parameters:
16
    - fovy: Field of view angle in Y direction (degrees)
17
    - aspect: Aspect ratio (width/height)
18
    - zNear: Distance to near clipping plane (must be positive)
19
    - zFar: Distance to far clipping plane (must be positive)
20
    """
21

22
def gluLookAt(eyeX: float, eyeY: float, eyeZ: float,
23
              centerX: float, centerY: float, centerZ: float,
24
              upX: float, upY: float, upZ: float):
25
    """
26
    Set up viewing transformation matrix.
27
    
28
    Parameters:
29
    - eyeX, eyeY, eyeZ: Eye position (camera location)
30
    - centerX, centerY, centerZ: Look-at point (target)
31
    - upX, upY, upZ: Up vector direction
32
    """
33

34
def gluOrtho2D(left: float, right: float, bottom: float, top: float):
35
    """
36
    Set up 2D orthographic projection.
37
    
38
    Parameters:
39
    - left, right: Left and right clipping planes
40
    - bottom, top: Bottom and top clipping planes
41
    """
42

43
def gluPickMatrix(x: float, y: float, delX: float, delY: float, viewport: list):
44
    """
45
    Set up picking matrix for selection.
46
    
47
    Parameters:
48
    - x, y: Pick point in window coordinates
49
    - delX, delY: Pick region size
50
    - viewport: Current viewport [x, y, width, height]
51
    """
52
```
53

54
### Coordinate Transformation
55

56
Functions for converting between different coordinate systems.
57

58
```python { .api }
59
def gluProject(objX: float, objY: float, objZ: float,
60
               model: list, proj: list, view: list) -> tuple:
61
    """
62
    Map object coordinates to window coordinates.
63
    
64
    Parameters:
65
    - objX, objY, objZ: Object coordinates
66
    - model: Model-view matrix (16-element array)
67
    - proj: Projection matrix (16-element array)
68
    - view: Viewport [x, y, width, height]
69
    
70
    Returns:
71
    Tuple of (winX, winY, winZ) window coordinates
72
    """
73

74
def gluUnProject(winX: float, winY: float, winZ: float,
75
                 model: list, proj: list, view: list) -> tuple:
76
    """
77
    Map window coordinates to object coordinates.
78
    
79
    Parameters:
80
    - winX, winY: Window coordinates
81
    - winZ: Window Z coordinate (depth value 0.0-1.0)
82
    - model: Model-view matrix (16-element array)
83
    - proj: Projection matrix (16-element array)  
84
    - view: Viewport [x, y, width, height]
85
    
86
    Returns:
87
    Tuple of (objX, objY, objZ) object coordinates
88
    """
89

90
def gluUnProject4(winX: float, winY: float, winZ: float, clipW: float,
91
                  model: list, proj: list, view: list,
92
                  nearVal: float, farVal: float) -> tuple:
93
    """
94
    Enhanced unprojection with explicit near/far planes.
95
    
96
    Returns:
97
    Tuple of (objX, objY, objZ, objW) object coordinates
98
    """
99
```
100

101
### Quadric Objects
102

103
Geometric primitive generation for common 3D shapes.
104

105
```python { .api }
106
def gluNewQuadric() -> GLUquadric:
107
    """
108
    Create quadric object for rendering geometric primitives.
109
    
110
    Returns:
111
    Quadric object handle
112
    """
113

114
def gluDeleteQuadric(quad: GLUquadric):
115
    """
116
    Delete quadric object.
117
    
118
    Parameters:
119
    - quad: Quadric object to delete
120
    """
121

122
def gluQuadricDrawStyle(quad: GLUquadric, draw):
123
    """
124
    Set quadric rendering style.
125
    
126
    Parameters:
127
    - quad: Quadric object
128
    - draw: Draw style (GLU_FILL, GLU_LINE, GLU_SILHOUETTE, GLU_POINT)
129
    """
130

131
def gluQuadricOrientation(quad: GLUquadric, orientation):
132
    """
133
    Set quadric orientation.
134
    
135
    Parameters:
136
    - orientation: GLU_OUTSIDE (default) or GLU_INSIDE
137
    """
138

139
def gluQuadricNormals(quad: GLUquadric, normal):
140
    """
141
    Set normal generation for quadric.
142
    
143
    Parameters:
144
    - normal: GLU_NONE, GLU_FLAT, or GLU_SMOOTH
145
    """
146

147
def gluQuadricTexture(quad: GLUquadric, texture: bool):
148
    """
149
    Enable/disable texture coordinate generation.
150
    
151
    Parameters:
152
    - texture: True to generate texture coordinates
153
    """
154
```
155

156
### Geometric Primitives
157

158
Ready-to-use geometric shapes with customizable parameters.
159

160
```python { .api }
161
def gluSphere(quad: GLUquadric, radius: float, slices: int, stacks: int):
162
    """
163
    Render sphere primitive.
164
    
165
    Parameters:
166
    - quad: Quadric object
167
    - radius: Sphere radius
168
    - slices: Number of longitude subdivisions
169
    - stacks: Number of latitude subdivisions
170
    """
171

172
def gluCylinder(quad: GLUquadric, base: float, top: float,
173
                height: float, slices: int, stacks: int):
174
    """
175
    Render cylinder primitive.
176
    
177
    Parameters:
178
    - quad: Quadric object
179
    - base: Base radius
180
    - top: Top radius (can differ from base for cone)
181
    - height: Cylinder height
182
    - slices: Number of subdivisions around Z axis
183
    - stacks: Number of subdivisions along Z axis
184
    """
185

186
def gluDisk(quad: GLUquadric, inner: float, outer: float,
187
            slices: int, loops: int):
188
    """
189
    Render disk primitive.
190
    
191
    Parameters:
192
    - quad: Quadric object
193
    - inner: Inner radius (0 for solid disk)
194
    - outer: Outer radius
195
    - slices: Number of radial subdivisions
196
    - loops: Number of concentric ring subdivisions
197
    """
198

199
def gluPartialDisk(quad: GLUquadric, inner: float, outer: float,
200
                   slices: int, loops: int, start: float, sweep: float):
201
    """
202
    Render partial disk (sector) primitive.
203
    
204
    Parameters:
205
    - inner, outer: Inner and outer radii
206
    - slices, loops: Subdivision counts
207
    - start: Starting angle in degrees
208
    - sweep: Sweep angle in degrees
209
    """
210
```
211

212
### Polygon Tessellation
213

214
Complex polygon tessellation for rendering arbitrary polygons with holes.
215

216
```python { .api }
217
def gluNewTess() -> GLUtesselator:
218
    """
219
    Create tessellation object.
220
    
221
    Returns:
222
    Tessellator object handle
223
    """
224

225
def gluDeleteTess(tess: GLUtesselator):
226
    """
227
    Delete tessellation object.
228
    
229
    Parameters:
230
    - tess: Tessellator object to delete
231
    """
232

233
def gluTessProperty(tess: GLUtesselator, which, data: float):
234
    """
235
    Set tessellation property.
236
    
237
    Parameters:
238
    - tess: Tessellator object
239
    - which: Property type (GLU_TESS_WINDING_RULE, GLU_TESS_BOUNDARY_ONLY)
240
    - data: Property value
241
    """
242

243
def gluTessCallback(tess: GLUtesselator, which, function):
244
    """
245
    Set tessellation callback function.
246
    
247
    Parameters:
248
    - tess: Tessellator object
249
    - which: Callback type (GLU_TESS_BEGIN, GLU_TESS_VERTEX, GLU_TESS_END, etc.)
250
    - function: Callback function or None
251
    """
252

253
def gluTessBeginPolygon(tess: GLUtesselator, data):
254
    """
255
    Begin polygon definition.
256
    
257
    Parameters:
258
    - tess: Tessellator object
259
    - data: User data passed to callbacks
260
    """
261

262
def gluTessEndPolygon(tess: GLUtesselator):
263
    """End polygon definition and perform tessellation."""
264

265
def gluTessBeginContour(tess: GLUtesselator):
266
    """Begin contour definition (polygon outline or hole)."""
267

268
def gluTessEndContour(tess: GLUtesselator):
269
    """End current contour definition."""
270

271
def gluTessVertex(tess: GLUtesselator, location: list, data):
272
    """
273
    Specify tessellation vertex.
274
    
275
    Parameters:
276
    - tess: Tessellator object
277
    - location: Vertex coordinates [x, y, z]
278
    - data: User data for this vertex
279
    """
280
```
281

282
### NURBS Surfaces
283

284
Non-Uniform Rational B-Spline surface generation for smooth curved surfaces.
285

286
```python { .api }
287
def gluNewNurbsRenderer() -> GLUnurbs:
288
    """
289
    Create NURBS renderer object.
290
    
291
    Returns:
292
    NURBS renderer handle
293
    """
294

295
def gluDeleteNurbsRenderer(nurb: GLUnurbs):
296
    """
297
    Delete NURBS renderer.
298
    
299
    Parameters:
300
    - nurb: NURBS renderer to delete
301
    """
302

303
def gluNurbsProperty(nurb: GLUnurbs, property, value: float):
304
    """
305
    Set NURBS rendering property.
306
    
307
    Parameters:
308
    - nurb: NURBS renderer
309
    - property: Property type (GLU_SAMPLING_TOLERANCE, GLU_DISPLAY_MODE)
310
    - value: Property value
311
    """
312

313
def gluNurbsCallback(nurb: GLUnurbs, which, function):
314
    """
315
    Set NURBS callback function.
316
    
317
    Parameters:
318
    - nurb: NURBS renderer
319
    - which: Callback type (GLU_NURBS_ERROR)
320
    - function: Callback function
321
    """
322

323
def gluBeginSurface(nurb: GLUnurbs):
324
    """Begin NURBS surface definition."""
325

326
def gluEndSurface(nurb: GLUnurbs):
327
    """End NURBS surface definition."""
328

329
def gluNurbsSurface(nurb: GLUnurbs, sKnotCount: int, sKnots: list,
330
                    tKnotCount: int, tKnots: list, sStride: int, tStride: int,
331
                    control: list, sOrder: int, tOrder: int, type):
332
    """
333
    Define NURBS surface.
334
    
335
    Parameters:
336
    - nurb: NURBS renderer
337
    - sKnotCount, tKnotCount: Number of knots in s and t directions
338
    - sKnots, tKnots: Knot sequences
339
    - sStride, tStride: Control point strides
340
    - control: Control point array
341
    - sOrder, tOrder: Surface order in s and t directions
342
    - type: Surface type (GL_MAP2_VERTEX_3, GL_MAP2_COLOR_4, etc.)
343
    """
344

345
def gluBeginCurve(nurb: GLUnurbs):
346
    """Begin NURBS curve definition."""
347

348
def gluEndCurve(nurb: GLUnurbs):
349
    """End NURBS curve definition."""
350

351
def gluNurbsCurve(nurb: GLUnurbs, knotCount: int, knots: list,
352
                  stride: int, control: list, order: int, type):
353
    """
354
    Define NURBS curve.
355
    
356
    Parameters:
357
    - knotCount: Number of knots
358
    - knots: Knot sequence
359
    - stride: Control point stride
360
    - control: Control point array
361
    - order: Curve order
362
    - type: Curve type
363
    """
364
```
365

366
### Error Handling
367

368
GLU-specific error reporting and string conversion.
369

370
```python { .api }
371
def gluErrorString(error: int) -> str:
372
    """
373
    Convert GLU error code to descriptive string.
374
    
375
    Parameters:
376
    - error: GLU error code
377
    
378
    Returns:
379
    Error description string
380
    """
381

382
def gluGetString(name: int) -> str:
383
    """
384
    Get GLU version or extension string.
385
    
386
    Parameters:
387
    - name: String identifier (GLU_VERSION, GLU_EXTENSIONS)
388
    
389
    Returns:
390
    Information string
391
    """
392
```
393

394
## Types
395

396
```python { .api }
397
class GLUquadric:
398
    """Opaque quadric object handle for geometric primitive rendering."""
399

400
class GLUtesselator:
401
    """Opaque tessellator object handle for polygon tessellation."""
402

403
class GLUnurbs:
404
    """Opaque NURBS renderer object handle for surface generation."""
405
```
406

407
## Constants
408

409
### Quadric Draw Styles
410
```python { .api }
411
GLU_FILL: int      # Filled polygons
412
GLU_LINE: int      # Wireframe
413
GLU_SILHOUETTE: int # Silhouette edges only
414
GLU_POINT: int     # Points only
415
```
416

417
### Quadric Orientations
418
```python { .api }
419
GLU_OUTSIDE: int   # Normals point outward
420
GLU_INSIDE: int    # Normals point inward
421
```
422

423
### Quadric Normals
424
```python { .api }
425
GLU_NONE: int      # No normals generated
426
GLU_FLAT: int      # Flat normals
427
GLU_SMOOTH: int    # Smooth normals
428
```
429

430
### Tessellation Properties
431
```python { .api }
432
GLU_TESS_WINDING_RULE: int
433
GLU_TESS_BOUNDARY_ONLY: int
434
GLU_TESS_TOLERANCE: int
435
```
436

437
### Tessellation Callbacks
438
```python { .api }
439
GLU_TESS_BEGIN: int
440
GLU_TESS_VERTEX: int
441
GLU_TESS_END: int
442
GLU_TESS_ERROR: int
443
GLU_TESS_EDGE_FLAG: int
444
GLU_TESS_COMBINE: int
445
```
446

447
### NURBS Properties
448
```python { .api }
449
GLU_SAMPLING_TOLERANCE: int
450
GLU_DISPLAY_MODE: int
451
GLU_CULLING: int
452
GLU_AUTO_LOAD_MATRIX: int
453
```