1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
5 <meta name="Author" content="John F. Fay">
6 <meta name="GENERATOR" content="Mozilla/4.77 [en] (Windows NT 5.0; U) [Netscape]">
7 <title>FREEGLUT Application Program Interface</title>
14 The Open-Source</h1></center>
18 OpenGL Utility Toolkit</h1></center>
22 (freeglut)</h1></center>
26 Application Programming Interface</h1></center>
31 Version 4.0</h1></center>
35 The freeglut Programming Consortium</h2></center>
39 November, 2002</h2></center>
41 <p><br>OpenGL is a trademark of Silicon Graphics, Inc. X Window System
42 is a trademark of X Consortium, Inc. Spaceball is a registered trademark
43 of Spatial Systems Inc.
44 <br>The authors have taken care in preparation of this documentation but
45 make no expressed or implied warranty of any kind and assumes no responsibility
46 for errors or omissions. No liability is assumed for incidental or consequential
47 damages in connection with or arising from the use of information or programs
51 1.0 <a NAME="Contents"></a>Contents</h1>
52 1.0 <a href="#Contents">Contents</a>
53 <p>2.0 <a href="#Introduction">Introduction</a>
54 <p>3.0 <a href="#Background">Background</a>
55 <blockquote>3.1 Design Philosophy
56 <br>3.2 Conventions
57 <br>3.3 Terminology
58 <br>3.4 Differences from GLUT 3.7</blockquote>
60 <p><br>4.0 <a href="#Initialization">Initialization Functions</a>
61 <blockquote>4.1 glutInit
62 <br>4.2 glutInitWindowPosition, glutInitWindowSize
63 <br>4.3 glutInitDisplayMode
64 <br>4.4 glutInitDisplayString</blockquote>
66 <p><br>5.0 <a href="#EventProcessing">Event Processing Functions</a>
67 <blockquote>5.1 glutMainLoop
68 <br>5.2 glutMainLoopEvent
69 <br>5.3 glutLeaveMainLoop</blockquote>
71 <p><br>6.0 <a href="#Window">Window Functions</a>
72 <blockquote>6.1 glutCreateWindow
73 <br>6.2 glutCreateSubwindow
74 <br>6.3 glutDestroyWindow
75 <br>6.4 glutSetWindow, glutGetWindow
76 <br>6.5 glutSetWindowTitle, glutSetIconTitle
77 <br>6.6 glutReshapeWindow
78 <br>6.7 glutPositionWindow
79 <br>6.8 glutShowWindow, glutHideWindow, glutIconifyWindow
80 <br>6.9 glutPushWindow, glutPopWindow
81 <br>6.10 glutFullScreen</blockquote>
83 <p><br>7.0 <a href="#Display">Display Functions</a>
84 <blockquote>7.1 glutPostRedisplay
85 <br>7.2 glutPostWindowRedisplay
86 <br>7.3 glutSwapBuffers</blockquote>
88 <p><br>8.0 <a href="#MouseCursor">Mouse Cursor Functions</a>
89 <blockquote>8.1 glutSetCursor
90 <br>8.2 glutWarpPointer</blockquote>
92 <p><br>9.0 <a href="#Overlay">Overlay Functions</a>
93 <blockquote>9.1 glutEstablishOverlay
94 <br>9.2 glutRemoveOverlay
95 <br>9.3 glutUseLayer
96 <br>9.4 glutPostOverlayRedisplay
97 <br>9.5 glutPostWindowOverlayRedisplay
98 <br>9.6 glutShowOverlay, glutHideOverlay</blockquote>
100 <p><br>10.0 <a href="#Menu">Menu Functions</a>
101 <blockquote>10.1 glutCreateMenu
102 <br>10.2 glutDestroyMenu
103 <br>10.3 glutGetMenu, glutSetMenu
104 <br>10.4 glutAddMenuEntry
105 <br>10.5 glutAddSubMenu
106 <br>10.6 glutChangeToMenuEntry
107 <br>10.7 glutChangeToSubMenu
108 <br>10.8 glutRemoveMenuItem
109 <br>10.9 glutAttachMenu, glutDetachMenu</blockquote>
111 <p><br>11.0 <a href="#GlobalCallback">Global Callback Registration
113 <blockquote>11.1 glutTimerFunc
114 <br>11.2 glutIdleFunc</blockquote>
116 <p><br>12.0 <a href="#WindowCallback">Window-Specific Callback Registration
118 <blockquote>12.1 glutDisplayFunc
119 <br>12.2 glutOverlayDisplayFunc
120 <br>12.3 glutReshapeFunc
121 <br>12.4 glutCloseFunc
122 <br>12.5 glutKeyboardFunc
123 <br>12.6 glutSpecialFunc
124 <br>12.7 glutKeyboardUpFunc
125 <br>12.8 glutSpecialUpFunc
126 <br>12.9 glutMouseFunc
127 <br>12.10 glutMotionFunc, glutPassiveMotionFunc
128 <br>12.11 glutVisibilityFunc
129 <br>12.12 glutEntryFunc
130 <br>12.13 glutJoystickFunc
131 <br>12.14 glutSpaceballMotionFunc
132 <br>12.15 glutSpaceballRotateFunc
133 <br>12.16 glutSpaceballButtonFunc
134 <br>12.17 glutButtonBoxFunc
135 <br>12.18 glutDialsFunc
136 <br>12.19 glutTabletMotionFunc
137 <br>12.20 glutTabletButtonFunc
138 <p>12.21 glutMenuStatusFunc
139 <br>12.22 glutWindowStatusFunc</blockquote>
141 <p><br>13.0 <a href="#StateSetting">State Setting and Retrieval Functions</a>
142 <blockquote>13.1 glutSetOption
143 <br>13.2 glutGet
144 <br>13.3 glutDeviceGet
145 <br>13.4 glutGetModifiers
146 <br>13.5 glutLayerGet
147 <br>13.6 glutExtensionSupported</blockquote>
149 <p><br>14.0 <a href="#FontRendering">Font Rendering Functions</a>
150 <blockquote>14.1 glutBitmapCharacter
151 <br>14.2 glutBitmapString
152 <br>14.3 glutBitmapWidth
153 <br>14.4 glutBitmapLength
154 <br>14.5 glutBitmapHeight
155 <br>14.6 glutStrokeCharacter
156 <br>14.7 glutStrokeString
157 <br>14.8 glutStrokeWidth
158 <br>14.9 glutStrokeLength
159 <br>14.10 glutStrokeHeight</blockquote>
161 <p><br>15.0 <a href="#GeometricObject">Geometric Object Rendering
163 <blockquote>15.1 glutWireSphere, glutSolidSphere
164 <br>15.2 glutWireTorus, glutSolidTorus
165 <br>15.3 glutWireCone, glutSolidCone
166 <br>15.4 glutWireCube, glutSolidCube
167 <br>15.5 glutWireTetrahedron, glutSolidTetrahedron
168 <br>15.6 glutWireOctahedron, glutSolidOctahedron
169 <br>15.7 glutWireDodecahedron, glutSolidDodecahedron
170 <br>15.8 glutWireIcosahedron, glutSolidIcosahedron
171 <br>15.9 glutWireRhombicDodecahedron, glutSolidRhombicDodecahedron
172 <br>15.10 glutWireTeapot, glutSolidTeapot</blockquote>
174 <p><br>16.0 <a href="#GameMode">Game Mode Functions</a>
175 <blockquote>16.1 glutGameModeString
176 <br>16.2 glutEnterGameMode, glutLeaveGameMode
177 <br>16.3 glutGameModeGet</blockquote>
179 <p><br>17.0 <a href="#VideoResize">Video Resize Functions</a>
180 <blockquote>17.1 glutVideoResizeGet
181 <br>17.2 glutSetupVideoResizing, glutStopVideoResizing
182 <br>17.3 glutVideoResize
183 <br>17.4 glutVideoPan</blockquote>
185 <p><br>18.0 <a href="#ColorMap">Color Map Functions</a>
186 <blockquote>18.1 glutSetColor, glutGetColor
187 <br>18.2 glutCopyColormap</blockquote>
189 <p><br>19.0 <a href="#Miscellaneous">Miscellaneous Functions</a>
190 <blockquote>19.1 glutIgnoreKeyRepeat, glutSetKeyRepeat
191 <br>19.2 glutForceJoystickFunc
192 <br>19.3 glutReportErrors</blockquote>
194 <p><br>20.0 <a href="#UsageNotes">Usage Notes</a>
195 <p>21.0 <a href="#ImplementationNotes">Implementation Notes</a>
196 <p>22.0 <a href="#GLUT_State">GLUT State</a>
197 <p>23.0 <a href="#Freeglut.h_Header">"freeglut.h" Header File</a>
198 <p>24.0 <a href="#References">References</a>
199 <p>25.0 <a href="#Index">Index</a>
203 2.0 <a NAME="Introduction"></a>Introduction</h1>
206 3.0 <a NAME="Background"></a>Background</h1>
207 The OpenGL programming world owes a tremendous debt to Mr. Mark J. Kilgard
208 for writing the OpenGL Utility Toolkit, or GLUT. The GLUT library
209 of functions allows an application programmer to create, control, and manipulate
210 windows independent of what operating system the program is running on.
211 By hiding the dependency on the operating system from the application programmer,
212 he allowed people to write truly portable OpenGL applications.
213 <p> Mr. Kilgard copyrighted his library and gave it a
214 rather unusual license. Under his license, people are allowed freely
215 to copy and distribute the libraries and the source code, but they are
216 not allowed to modify it. For a long time this did not matter because
217 the GLUT library worked so well and because Mr. Kilgard was releasing updates
218 on a regular basis. But with the passage of time, people started
219 wanting some slightly different behaviours in their windowing system.
220 When Mr. Kilgard stopped supporting the GLUT library in 1999, having moved
221 on to bigger and better things, this started to become a problem.
222 <p> In December 1999, Mr. Pawel Olzsta started work on
223 an open-source clone of the GLUT library. This open-source clone,
224 which does not use any of the GLUT source code, has evolved into the present
226 library. This documentation specifies the application program interface
227 to the <i>freeglut</i> library.
229 3.1 Design Philosophy</h2>
232 3.2 Conventions</h2>
235 3.3 Terminology</h2>
238 3.4 Differences from GLUT 3.7</h2>
239 Since the <i>freeglut</i> library was developed in order to update GLUT,
240 it is natural that there will be some differences between the two.
241 Each function in the API notes any differences between the GLUT and the
243 function behaviours. The important ones are summarized here.
245 3.4.1 glutMainLoop Behaviour</h3>
246 One of the commonest complaints about the GLUT library was that once an
247 application called "<tt>glutMainLoop</tt>", it never got control back.
248 There was no way for an application to loop in GLUT for a while, possibly
249 as a subloop while a specific window was open, and then return to the calling
250 function. A new function, "<tt>glutMainLoopEvent</tt>", has been
251 added to allow this functionality. Another function, "<tt>glutLeaveMainLoop</tt>",
252 has also been added to allow the application to tell freeglut to clean
255 3.4.2 Action on Window Closure</h3>
256 Another difficulty with GLUT, especially with multiple-window programs,
257 is that if the user clicks on the "x" in the window header the application
258 exits immediately. The application programmer can now set an option,
259 "<tt>GLUT_ACTION_ON_WINDOW_CLOSE</tt>", to specify whether execution should
260 continue, whether GLUT should return control to the main program, or whether
261 GLUT should simply exit (the default).
263 3.4.3 String Rendering</h3>
264 New functions have been added to render full character strings (including
265 carriage returns) rather than rendering one character at a time.
266 More functions return the widths of character strings and the font heights,
267 in pixels for bitmapped fonts and in OpenGL units for the stroke fonts.
269 3.4.4 Geometry Rendering</h3>
270 Two functions have been added to render a wireframe and a solid rhombic
273 4.0 <a NAME="Initialization"></a>Initialization Functions</h1>
276 4.1 glutInit</h2>
279 4.2 glutInitWindowPosition, glutInitWindowSize</h2>
282 4.3 glutInitDisplayMode</h2>
285 4.4 glutInitDisplayString</h2>
288 5.0 <a NAME="EventProcessing"></a>Event Processing Functions</h1>
289 After an application has finished initializing its windows and menus, it
290 enters an event loop. Within this loop, <i>freeglut</i> polls the
291 data entry devices (keyboard, mouse, etc.) and calls the application's
292 appropriate callbacks.
293 <p>In GLUT, control never returned from the event loop (as invoked by the
294 "<tt>glutMainLoop</tt>" function) to the calling function. This prevented
295 an application from having re-entrant code, in which GLUT could be invoked
296 from within a callback, and it prevented the application from doing any
297 post-processing (such as freeing allocated memory) after GLUT had closed
298 down. <i>Freeglut</i> allows the application programmer to specify
299 more direct control over the event loop by means of two new functions.
300 The first, "<tt>glutMainLoopEvent</tt>", processes a single iteration of
301 the event loop and allows the application to use a different event loop
302 controller or to contain re-entrant code. The second, "<tt>glutLeaveMainLoop</tt>",
303 causes the event loop to exit nicely; this is preferable to the application's
304 calling "<tt>exit</tt>" from within a GLUT callback.
306 5.1 glutMainLoop</h2>
307 The "<tt>glutMainLoop</tt>" function enters the event loop.
309 <p><tt>void glutMainLoop ( void ) ;</tt>
310 <p><b>Description</b>
311 <p>The "<tt>glutMainLoop</tt>" function causes the program to enter
312 the window event loop. An application should call this function at
313 most once. It will call any application callback functions as required
314 to process mouse clicks, mouse motion, key presses, and so on.
315 <p><b>Changes From GLUT</b>
316 <p>In GLUT, there was absolutely no way for the application programmer
317 to have control return from the "<tt>glutMainLoop</tt>" function to the
318 calling function. <i>Freeglut</i> allows the programmer to force
319 this by setting the "<tt>GLUT_ACTION_ON_WINDOW_CLOSE</tt>" option and invoking
320 the "<tt>glutLeaveMainLoop</tt>" function from one of the callbacks.
321 Stopping the program this way is preferable to simply calling "<tt>exit</tt>"
322 from within a callback because this allows <i>freeglut</i> to free allocated
323 memory and otherwise clean up after itself. (I know I just said this,
324 but I think it is important enough that it bears repeating.)
326 5.2 glutMainLoopEvent</h2>
327 The "<tt>glutMainLoopEvent</tt>" function processes a single iteration
328 in the <i>freeglut</i> event loop.
330 <p><tt>void glutMainLoopEvent ( void ) ;</tt>
331 <p><b>Description</b>
332 <p>The "<tt>glutMainLoopEvent</tt>" function causes <i>freeglut</i>
333 to process one iteration's worth of events in its event loop. This
334 allows the application to control its own event loop and still use the
335 <i>freeglut</i> windowing system.
336 <p><b>Changes From GLUT</b>
337 <p>GLUT does not include this function.
339 5.3 glutLeaveMainLoop</h2>
340 The "<tt>glutLeaveMainLoop</tt>" function causes <i>freeglut</i> to stop
343 <p><tt>void glutLeaveMainLoop ( void ) ;</tt>
344 <p><b>Description</b>
345 <p>The "<tt>glutLeaveMainLoop</tt>" function causes <i>freeglut</i>
346 to stop the event loop. If the "<tt>GLUT_ACTION_ON_WINDOW_CLOSE</tt>"
347 option has been set to "<tt>GLUT_ACTION_CONTINUE_EXECUTION</tt>", control
348 will return to the function which called "<tt>glutMainLoop</tt>"; otherwise
349 the application will exit.
350 <p><b>Changes From GLUT</b>
351 <p>GLUT does not include this function.
353 6.0 <a NAME="Window"></a>Window Functions</h1>
356 6.1 glutCreateWindow</h2>
359 6.2 glutCreateSubwindow</h2>
362 6.3 glutDestroyWindow</h2>
365 6.4 glutSetWindow, glutGetWindow</h2>
368 6.5 glutSetWindowTitle, glutSetIconTitle</h2>
371 6.6 glutReshapeWindow</h2>
374 6.7 glutPositionWindow</h2>
377 6.8 glutShowWindow, glutHideWindow, glutIconifyWindow</h2>
380 6.9 glutPushWindow, glutPopWindow</h2>
383 6.10 glutFullScreen</h2>
386 7.0 <a NAME="Display"></a>Display Functions</h1>
389 7.1 glutPostRedisplay</h2>
392 7.2 glutPostWindowRedisplay</h2>
395 7.3 glutSwapBuffers</h2>
398 8.0 <a NAME="MouseCursor"></a>Mouse Cursor Functions</h1>
401 8.1 glutSetCursor</h2>
404 8.2 glutWarpPointer</h2>
407 9.0 <a NAME="Overlay"></a>Overlay Functions</h1>
410 9.1 glutEstablishOverlay</h2>
413 9.2 glutRemoveOverlay</h2>
416 9.3 glutUseLayer</h2>
419 9.4 glutPostOverlayRedisplay</h2>
422 9.5 glutPostWindowOverlayRedisplay</h2>
425 9.6 glutShowOverlay, glutHideOverlay</h2>
428 10.0 <a NAME="Menu"></a>Menu Functions</h1>
431 10.1 glutCreateMenu</h2>
434 10.2 glutDestroyMenu</h2>
437 10.3 glutGetMenu, glutSetMenu</h2>
440 10.4 glutAddMenuEntry</h2>
443 10.5 glutAddSubMenu</h2>
446 10.6 glutChangeToMenuEntry</h2>
449 10.7 glutChangeToSubMenu</h2>
452 10.8 glutRemoveMenuItem</h2>
455 10.9 glutAttachMenu, glutDetachMenu</h2>
458 11.0 <a NAME="GlobalCallback"></a>Global Callback Registration Functions</h1>
461 11.1 glutTimerFunc</h2>
464 11.2 glutIdleFunc</h2>
465 The "<tt>glutIdleFunc</tt>" function sets the global idle callback. <i>Freeglut</i>
466 calls the idle callback when there are no inputs from the user.
468 <p><tt>void glutIdleFunc ( void (*func) ( void ) ) ;</tt>
469 <p><tt>func </tt>The new global idle callback function
470 <p><b>Description</b>
471 <p>The "<tt>glutIdleFunc</tt>" function specifies the function that
473 will call to perform background processing tasks such as continuous animation
474 when window system events are not being received. If enabled, this
475 function is called continuously from <i>freeglut</i> while no events are
476 received. The callback function has no parameters and returns no
477 value. <i>Freeglut</i> does not change the <i>current window</i>
478 or the <i>current menu</i> before invoking the idle callback; programs
479 with multiple windows or menus must explicitly set the <i>current window</i>
480 and <i>current menu</i> and not rely on its current setting.
481 <br> The amount of computation and rendering done in
482 an idle callback should be minimized to avoid affecting the program's interactive
483 response. In general, no more than a single frame of rendering should
484 be done in a single invocation of an idle callback.
485 <br> Calling "<tt>glutIdleFunc</tt>" with a NULL argument
486 disables the call to an idle callback.
487 <p><b>Changes From GLUT</b>
488 <p>Application programmers should note that if they have specified the
489 "continue execution" action on window closure, <i>freeglut</i> will continue
490 to call the idle callback after the user has closed a window by clicking
491 on the "x" in the window header bar. If the idle callback renders
492 a particular window (this is considered bad form but is frequently done
493 anyway), the programmer should supply a window closure callback for that
494 window which changes or disables the idle callback.
496 12.0 <a NAME="WindowCallback"></a>Window-Specific Callback Registration
500 12.1 glutDisplayFunc</h2>
503 12.2 glutOverlayDisplayFunc</h2>
506 12.3 glutReshapeFunc</h2>
509 12.4 glutCloseFunc</h2>
512 12.5 glutKeyboardFunc</h2>
515 12.6 glutSpecialFunc</h2>
518 12.7 glutKeyboardUpFunc</h2>
521 12.8 glutSpecialUpFunc</h2>
524 12.9 glutMouseFunc</h2>
527 12.10 glutMotionFunc, glutPassiveMotionFunc</h2>
530 12.11 glutVisibilityFunc</h2>
533 12.12 glutEntryFunc</h2>
536 12.13 glutJoystickFunc</h2>
539 12.14 glutSpaceballMotionFunc</h2>
542 12.15 glutSpaceballRotateFunc</h2>
545 12.16 glutSpaceballButtonFunc</h2>
548 12.17 glutButtonBoxFunc</h2>
551 12.18 glutDialsFunc</h2>
554 12.19 glutTabletMotionFunc</h2>
557 12.20 glutTabletButtonFunc</h2>
560 12.21 glutMenuStatusFunc</h2>
563 12.22 glutWindowStatusFunc</h2>
566 13.0 <a NAME="StateSetting"></a>State Setting and Retrieval Functions</h1>
569 13.1 glutSetOption</h2>
572 13.2 glutGet</h2>
575 13.3 glutDeviceGet</h2>
578 13.4 glutGetModifiers</h2>
581 13.5 glutLayerGet</h2>
584 13.6 glutExtensionSupported</h2>
587 14.0 <a NAME="FontRendering"></a>Font Rendering Functions</h1>
588 <i>Freeglut</i> supports two types of font rendering: bitmap fonts,
589 which are rendered using the "<tt>glBitmap</tt>" function call, and stroke
590 fonts, which are rendered as sequences of OpenGL line segments. Because
591 they are rendered as bitmaps, the bitmap fonts tend to render more quickly
592 than stroke fonts, but they are less flexible in terms of scaling and rendering.
593 Bitmap font characters are positioned with calls to the "<tt>glRasterPos*</tt>"
594 functions while stroke font characters use the OpenGL transformations to
596 <p> It should be noted that <i>freeglut</i> fonts are
597 similar but not identical to GLUT fonts. At the moment, <i>freeglut</i>
598 fonts do not support the "`" (backquote) and "|" (vertical line) characters;
599 in their place it renders asterisks.
600 <p> <i>Freeglut</i> supports the following bitmap fonts:
603 <tt>GLUT_BITMAP_8_BY_13</tt> - A variable-width font with every character
604 fitting in a rectangle of 13 pixels high by at most 8 pixels wide.</li>
607 <tt>GLUT_BITMAP_9_BY_15</tt> - A variable-width font with every character
608 fitting in a rectangle of 15 pixels high by at most 9 pixels wide.</li>
611 <tt>GLUT_BITMAP_TIMES_ROMAN_10</tt> - A 10-point variable-width Times Roman
615 <tt>GLUT_BITMAP_TIMES_ROMAN_24</tt> - A 24-point variable-width Times Roman
619 <tt>GLUT_BITMAP_HELVETICA_10</tt> - A 10-point variable-width Helvetica
623 <tt>GLUT_BITMAP_HELVETICA_12</tt> - A 12-point variable-width Helvetica
627 <tt>GLUT_BITMAP_HELVETICA_18</tt> - A 18-point variable-width Helvetica
630 <i>Freeglut</i> calls "<tt>glRasterPos4v</tt>" to advance the cursor by
631 the width of a character and to render carriage returns when appropriate.
632 It does not use any display lists in it rendering in bitmap fonts.
633 <p> <i>Freeglut</i> supports the following stroke fonts:
636 <tt>GLUT_STROKE_ROMAN</tt> - A proportionally-spaced Roman Simplex font</li>
639 <tt>GLUT_STROKE_MONO_ROMAN</tt> - A fixed-width Roman Simplex font</li>
641 <i>Freeglut</i> does not use any display lists in its rendering of stroke
642 fonts. It calls "<tt>glTranslatef</tt>" to advance the cursor by
643 the width of a character and to render carriage returns when appropriate.
645 14.1 glutBitmapCharacter</h2>
646 The "<tt>glutBitmapCharacter</tt>" function renders a single bitmapped
647 character in the <i>current window</i> using the specified font.
649 <p><tt>void glutBitmapCharacter ( void *font, int character ) ;</tt>
650 <p><tt>font </tt>The bitmapped
651 font to use in rendering the character
652 <br><tt>character </tt>The ASCII code of the character to be
654 <p><b>Description</b>
655 <p>The "<tt>glutBitmapCharacter</tt>" function renders the given
656 character in the specified bitmap font. <i>Freeglut</i> automatically
657 sets the necessary pixel unpack storage modes and restores the existing
658 modes when it has finished. Before the first call to "<tt>glutBitMapCharacter</tt>"
659 the application program should call "<tt>glRasterPos*</tt>" to set the
660 position of the character in the window. The "<tt>glutBitmapCharacter</tt>"
661 function advances the cursor position as part of its call to "<tt>glBitmap</tt>"
662 and so the application does not need to call "<tt>glRasterPos*</tt>" again
663 for successive characters on the same line.
664 <p><b>Changes From GLUT</b>
665 <p>Nonexistent characters are rendered as asterisks. The rendering
666 position in <i>freeglut</i> is apparently off from GLUT's position by a
667 few pixels vertically and one or two pixels horizontally.
669 14.2 glutBitmapString</h2>
670 The "<tt>glutBitmapString</tt>" function renders a string of bitmapped
671 characters in the <i>current window</i> using the specified font.
673 <p><tt>void glutBitmapString ( void *font, char *string ) ;</tt>
674 <p><tt>font </tt>The bitmapped font to use
675 in rendering the character string
676 <br><tt>string </tt>String of characters to be rendered
677 <p><b>Description</b>
678 <p>The "<tt>glutBitmapString</tt>" function renders the given character
679 string in the specified bitmap font. <i>Freeglut</i> automatically
680 sets the necessary pixel unpack storage modes and restores the existing
681 modes when it has finished. Before calling "<tt>glutBitMapString</tt>"
682 the application program should call "<tt>glRasterPos*</tt>" to set the
683 position of the string in the window. The "<tt>glutBitmapString</tt>"
684 function handles carriage returns. Nonexistent characters are rendered
686 <p><b>Changes From GLUT</b>
687 <p>GLUT does not include this function.
689 14.3 glutBitmapWidth</h2>
690 The "<tt>glutBitmapWidth</tt>" function returns the width in pixels of
691 a single bitmapped character in the specified font.
693 <p><tt>int glutBitmapWidth ( void *font, int character ) ;</tt>
694 <p><tt>font </tt>The bitmapped
695 font to use in calculating the character width
696 <br><tt>character </tt>The ASCII code of the character
697 <p><b>Description</b>
698 <p>The "<tt>glutBitmapWidth</tt>" function returns the width of the
699 given character in the specified bitmap font. Because the font is
700 bitmapped, the width is an exact integer.
701 <p><b>Changes From GLUT</b>
702 <p>Nonexistent characters return the width of an asterisk.
704 14.4 glutBitmapLength</h2>
705 The "<tt>glutBitmapLength</tt>" function returns the width in pixels of
706 a string of bitmapped characters in the specified font.
708 <p><tt>int glutBitmapLength ( void *font, char *string ) ;</tt>
709 <p><tt>font </tt>The bitmapped font to use in calculating
711 <br><tt>string </tt>String of characters whose width is to be calculated
712 <p><b>Description</b>
713 <p>The "<tt>glutBitmapLength</tt>" function returns the width in
714 pixels of the given character string in the specified bitmap font.
715 Because the font is bitmapped, the width is an exact integer: the
716 return value is identical to the sum of the character widths returned by
717 a series of calls to "<tt>glutBitmapWidth</tt>". The width of nonexistent
718 characters is counted to be the width of an asterisk.
719 <p> If the string contains one or more carriage returns,
721 calculates the widths in pixels of the lines separately and returns the
723 <p><b>Changes From GLUT</b>
724 <p>GLUT does not include this function.
726 14.5 glutBitmapHeight</h2>
727 The "<tt>glutBitmapHeight</tt>" function returns the height in pixels of
730 <p><tt>int glutBitmapHeight ( void *font ) ;</tt>
731 <p><tt>font </tt>The bitmapped
732 font to use in calculating the character height
733 <p><b>Description</b>
734 <p>The "<tt>glutBitmapHeight</tt>" function returns the height of
735 a character in the specified bitmap font. Because the font is bitmapped,
736 the height is an exact integer. The fonts are designed such that
737 all characters have (nominally) the same height.
738 <p><b>Changes From GLUT</b>
739 <p>GLUT does not include this function.
741 14.6 glutStrokeCharacter</h2>
742 The "<tt>glutStrokeCharacter</tt>" function renders a single stroke character
743 in the <i>current window</i> using the specified font.
745 <p><tt>void glutStrokeCharacter ( void *font, int character ) ;</tt>
746 <p><tt>font </tt>The stroke font
747 to use in rendering the character
748 <br><tt>character </tt>The ASCII code of the character to be
750 <p><b>Description</b>
751 <p>The "<tt>glutStrokeCharacter</tt>" function renders the given
752 character in the specified stroke font. Before the first call to
753 "<tt>glutStrokeCharacter</tt>" the application program should call the
754 OpenGL transformation (positioning and scaling) functions to set the position
755 of the character in the window. The "<tt>glutStrokeCharacter</tt>"
756 function advances the cursor position by a call to "<tt>glTranslatef</tt>"
757 and so the application does not need to call the OpenGL positioning functions
758 again for successive characters on the same line.
759 <p><b>Changes From GLUT</b>
760 <p>Nonexistent characters are rendered as asterisks.
762 14.7 glutStrokeString</h2>
763 The "<tt>glutStrokeString</tt>" function renders a string of characters
764 in the <i>current window</i> using the specified stroke font.
766 <p><tt>void glutStrokeString ( void *font, char *string ) ;</tt>
767 <p><tt>font </tt>The stroke font to use in
768 rendering the character string
769 <br><tt>string </tt>String of characters to be rendered
770 <p><b>Description</b>
771 <p>The "<tt>glutStrokeString</tt>" function renders the given character
772 string in the specified stroke font. Before calling "<tt>glutStrokeString</tt>"
773 the application program should call the OpenGL transformation (positioning
774 and scaling) functions to set the position of the string in the window.
775 The "<tt>glutStrokeString</tt>" function handles carriage returns.
776 Nonexistent characters are rendered as asterisks.
777 <p><b>Changes From GLUT</b>
778 <p>GLUT does not include this function.
780 14.8 glutStrokeWidth</h2>
781 The "<tt>glutStrokeWidth</tt>" function returns the width in pixels of
782 a single character in the specified stroke font.
784 <p><tt>int glutStrokeWidth ( void *font, int character ) ;</tt>
785 <p><tt>font </tt>The stroke font
786 to use in calculating the character width
787 <br><tt>character </tt>The ASCII code of the character
788 <p><b>Description</b>
789 <p>The "<tt>glutStrokeWidth</tt>" function returns the width of the
790 given character in the specified stroke font. Because the font is
791 a stroke font, the width is actually a floating-point number; the function
792 rounds it to the nearest integer for the return value.
793 <p><b>Changes From GLUT</b>
794 <p>Nonexistent characters return the width of an asterisk.
796 14.9 glutStrokeLength</h2>
797 The "<tt>glutStrokeLength</tt>" function returns the width in pixels of
798 a string of characters in the specified stroke font.
800 <p><tt>int glutStrokeLength ( void *font, char *string ) ;</tt>
801 <p><tt>font </tt>The stroke font to use in calculating
803 <br><tt>string </tt>String of characters whose width is to be calculated
804 <p><b>Description</b>
805 <p>The "<tt>glutStrokeLength</tt>" function returns the width in
806 pixels of the given character string in the specified stroke font.
807 Because the font is a stroke font, the width of an individual character
808 is a floating-point number. <i>Freeglut</i> adds the floating-point
809 widths and rounds the funal result to return the integer value. Thus
810 the return value may differ from the sum of the character widths returned
811 by a series of calls to "<tt>glutStrokeWidth</tt>". The width of
812 nonexistent characters is counted to be the width of an asterisk.
813 <p> If the string contains one or more carriage returns,
815 calculates the widths in pixels of the lines separately and returns the
817 <p><b>Changes From GLUT</b>
818 <p>GLUT does not include this function.
820 14.10 glutStrokeHeight</h2>
821 The "<tt>glutStrokeHeight</tt>" function returns the height in pixels of
824 <p><tt>GLfloat glutStrokeHeight ( void *font ) ;</tt>
825 <p><tt>font </tt>The stroke font
826 to use in calculating the character height
827 <p><b>Description</b>
828 <p>The "<tt>glutStrokeHeight</tt>" function returns the height of
829 a character in the specified stroke font. The application programmer
830 should note that, unlike the other <i>freeglut</i> font functions, this
831 one returns a floating-point number. The fonts are designed such
832 that all characters have (nominally) the same height.
833 <p><b>Changes From GLUT</b>
834 <p>GLUT does not include this function.
836 15.0 <a NAME="GeometricObject"></a>Geometric Object Rendering Functions</h1>
837 <i>Freeglut</i> includes eighteen routines for generating easily-recognizable
838 3-d geometric objects. These routines are effectively the same ones
839 that are included in the GLUT library, and reflect the functionality available
840 in the <i>aux</i> toolkit described in the <i>OpenGL Programmer's Guide</i>.
841 They are included to allow programmers to create with a single line of
842 code a three-dimensional object which can be used to test a variety of
843 OpenGL functionality. None of the routines generates a display list
844 for the object which it draws. The functions generate normals appropriate
845 for lighting but, except for the teapon functions, do not generate texture
848 15.1 glutWireSphere, glutSolidSphere</h2>
849 The "<tt>glutWireSphere</tt>" and "<tt>glutSolidSphere</tt>" functions
850 draw a wireframe and solid sphere respectively.
852 <p><tt>void glutWireSphere ( GLdouble dRadius, GLint slices, GLint stacks
854 <p><tt>void glutSolidSphere ( GLdouble dRadius, GLint slices, GLint stacks
856 <p><tt>dRadius </tt>The desired radius
858 <p><tt>slices </tt>The desired
859 number of slices (divisions in the longitudinal direction) in the sphere
860 <p><tt>stacks </tt>The desired
861 number of stacks (divisions in the latitudinal direction) in the sphere.
862 The number of points in this direction, including the north and south poles,
864 <p><b>Description</b>
865 <p>The "<tt>glutWireSphere</tt>" and "<tt>glutSolidSphere</tt>" functions
866 render a sphere centered at the origin of the modeling coordinate system.
867 The north and south poles of the sphere are on the positive and negative
868 Z-axes respectively and the prime meridian crosses the positive X-axis.
869 <p><b>Changes From GLUT</b>
870 <p>None that we know of.
872 15.2 glutWireTorus, glutSolidTorus</h2>
873 The "<tt>glutWireTorus</tt>" and "<tt>glutSolidTorus</tt>" functions draw
874 a wireframe and solid torus (donut shape) respectively.
876 <p><tt>void glutWireTorus ( GLdouble dInnerRadius, GLdouble dOuterRadius,
877 GLint nSides, GLint nRings ) ;</tt>
878 <p><tt>void glutSolidTorus ( GLdouble dInnerRadius, GLdouble dOuterRadius,
879 GLint nSides, GLint nRings ) ;</tt>
880 <p><tt>dInnerRadius </tt>The
881 desired inner radius of the torus, from the origin to the circle defining
882 the centers of the outer circles
883 <p><tt>dOuterRadius </tt>The
884 desired outer radius of the torus, from the center of the outer circle
885 to the actual surface of the torus
886 <p><tt>nSides </tt>The desired
887 number of segments in a single outer circle of the torus
888 <p><tt>nRings </tt>The desired
889 number of outer circles around the origin of the torus
890 <p><b>Description</b>
891 <p>The "<tt>glutWireTorus</tt>" and "<tt>glutSolidTorus</tt>" functions
892 render a torus centered at the origin of the modeling coordinate system.
893 The torus is circularly symmetric about the Z-axis and starts at the positive
895 <p><b>Changes From GLUT</b>
896 <p>None that we know of.
898 15.3 glutWireCone, glutSolidCone</h2>
899 The "<tt>glutWireCone</tt>" and "<tt>glutSolidCone</tt>" functions draw
900 a wireframe and solid cone respectively.
902 <p><tt>void glutWireCone ( GLdouble base, GLdouble height, GLint slices,
903 GLint stacks ) ;</tt>
904 <p><tt>void glutSolidCone ( GLdouble base, GLdouble height, GLint slices,
905 GLint stacks ) ;</tt>
906 <p><tt>base </tt>The
907 desired radius of the base of the cone
908 <p><tt>height </tt>The desired
910 <p><tt>slices </tt>The desired
911 number of slices around the base of the cone
912 <p><tt>stacks </tt>The desired
913 number of segments between the base and the tip of the cone (the number
914 of points, including the tip, is <tt>stacks + 1</tt>)
915 <p><b>Description</b>
916 <p>The "<tt>glutWireCone</tt>" and "<tt>glutSolidCone</tt>" functions render
917 a right circular cone with a base centered at the origin and in the X-Y
918 plane and its tip on the positive Z-axis. The wire cone is rendered
919 with triangular elements.
920 <p><b>Changes From GLUT</b>
921 <p>None that we know of.
923 15.4 glutWireCube, glutSolidCube</h2>
924 The "<tt>glutWireCube</tt>" and "<tt>glutSolidCube</tt>" functions draw
925 a wireframe and solid cube respectively.
927 <p><tt>void glutWireCube ( GLdouble dSize ) ;</tt>
928 <p><tt>void glutSolidCube ( GLdouble dSize ) ;</tt>
929 <p><tt>dSize </tt>The desired
930 length of an edge of the cube
931 <p><b>Description</b>
932 <p>The "<tt>glutWireCube</tt>" and "<tt>glutSolidCube</tt>" functions render
933 a cube of the desired size, centered at the origin. Its faces are
934 normal to the coordinate directions.
935 <p><b>Changes From GLUT</b>
936 <p>None that we know of.
938 15.5 glutWireTetrahedron, glutSolidTetrahedron</h2>
939 The "<tt>glutWireTetrahedron</tt>" and "<tt>glutSolidTetrahedron</tt>"
940 functions draw a wireframe and solid tetrahedron (four-sided Platonic solid)
943 <p><tt>void glutWireTetrahedron ( void ) ;</tt>
944 <p><tt>void glutSolidTetrahedron ( void ) ;</tt>
945 <p><b>Description</b>
946 <p>The "<tt>glutWireTetrahedron</tt>" and "<tt>glutSolidTetrahedron</tt>"
947 functions render a tetrahedron whose corners are each a distance of one
948 from the origin. The length of each side is 2/3 sqrt(6). One
949 corner is on the positive X-axis and another is in the X-Y plane with a
950 positive Y-coordinate.
951 <p><b>Changes From GLUT</b>
952 <p>None that we know of.
954 15.6 glutWireOctahedron, glutSolidOctahedron</h2>
955 The "<tt>glutWireOctahedron</tt>" and "<tt>glutSolidOctahedron</tt>" functions
956 draw a wireframe and solid octahedron (eight-sided Platonic solid) respectively.
958 <p><tt>void glutWireOctahedron ( void ) ;</tt>
959 <p><tt>void glutSolidOctahedron ( void ) ;</tt>
960 <p><b>Description</b>
961 <p>The "<tt>glutWireOctahedron</tt>" and "<tt>glutSolidOctahedron</tt>"
962 functions render an octahedron whose corners are each a distance of one
963 from the origin. The length of each side is sqrt(2). The corners
964 are on the positive and negative coordinate axes.
965 <p><b>Changes From GLUT</b>
966 <p>None that we know of.
968 15.7 glutWireDodecahedron, glutSolidDodecahedron</h2>
969 The "<tt>glutWireDodecahedron</tt>" and "<tt>glutSolidDodecahedron</tt>"
970 functions draw a wireframe and solid dodecahedron (twelve-sided Platonic
973 <p><tt>void glutWireDodecahedron ( void ) ;</tt>
974 <p><tt>void glutSolidDodecahedron ( void ) ;</tt>
975 <p><b>Description</b>
976 <p>The "<tt>glutWireDodecahedron</tt>" and "<tt>glutSolidDodecahedron</tt>"
977 functions render a dodecahedron whose corners are each a distance of sqrt(3)
978 from the origin. The length of each side is sqrt(5)-1. There
979 are twenty corners; interestingly enough, eight of them coincide with the
980 corners of a cube with sizes of length 2.
981 <p><b>Changes From GLUT</b>
982 <p>None that we know of.
984 15.8 glutWireIcosahedron, glutSolidIcosahedron</h2>
985 The "<tt>glutWireIcosahedron</tt>" and "<tt>glutSolidIcosahedron</tt>"
986 functions draw a wireframe and solid icosahedron (twenty-sided Platonic
989 <p><tt>void glutWireIcosahedron ( void ) ;</tt>
990 <p><tt>void glutSolidIcosahedron ( void ) ;</tt>
991 <p><b>Description</b>
992 <p>The "<tt>glutWireIcosahedron</tt>" and "<tt>glutSolidIcosahedron</tt>"
993 functions render an icosahedron whose corners are each a unit distance
994 from the origin. The length of each side is slightly greater than
995 one. Two of the corners lie on the positive and negative X-axes.
996 <p><b>Changes From GLUT</b>
997 <p>None that we know of.
999 15.7 glutWireRhombicDodecahedron, glutSolidRhombicDodecahedron</h2>
1000 The "<tt>glutWireRhombicDodecahedron</tt>" and "<tt>glutSolidRhombicDodecahedron</tt>"
1001 functions draw a wireframe and solid rhombic dodecahedron (twelve-sided
1002 semi-regular solid) respectively.
1004 <p><tt>void glutWireRhombicDodecahedron ( void ) ;</tt>
1005 <p><tt>void glutSolidRhombicDodecahedron ( void ) ;</tt>
1006 <p><b>Description</b>
1007 <p>The "<tt>glutWireRhombicDodecahedron</tt>" and "<tt>glutSolidRhombicDodecahedron</tt>"
1008 functions render a rhombic dodecahedron whose corners are at most a distance
1009 of one from the origin. The rhombic dodecahedron has faces which
1010 are identical rhombuses (rhombi?) but which have some vertices at which
1011 three faces meet and some vertices at which four faces meet. The
1012 length of each side is sqrt(3)/2. Vertices at which four faces meet
1013 are found at (0, 0, <u>+</u>1) and (<u>+</u>sqrt(2)/2, <u>+</u>sqrt(2)/2,
1015 <p><b>Changes From GLUT</b>
1016 <p>GLUT does not include these functions.
1018 15.10 glutWireTeapot, glutSolidTeapot</h2>
1019 The "<tt>glutWireTeapot</tt>" and "<tt>glutSolidTeapot</tt>" functions
1020 draw a wireframe and solid teapot respectively.
1022 <p><tt>void glutWireTeapot ( GLdouble dSize ) ;</tt>
1023 <p><tt>void glutSolidTeapot ( GLdouble dSize ) ;</tt>
1024 <p><tt>dSize </tt>The desired
1026 <p><b>Description</b>
1027 <p>The "<tt>glutWireTeapot</tt>" and "<tt>glutSolidTeapot</tt>" functions
1028 render a teapot of the desired size, centered at the origin. This
1029 is the famous OpenGL teapot [add reference].
1030 <p><b>Changes From GLUT</b>
1031 <p>None that we know of.
1033 16.0 <a NAME="GameMode"></a>Game Mode Functions</h1>
1036 16.1 glutGameModeString</h2>
1039 16.2 glutEnterGameMode, glutLeaveGameMode</h2>
1042 16.3 glutGameModeGet</h2>
1045 17.0 <a NAME="VideoResize"></a>Video Resize Functions</h1>
1048 17.1 glutVideoResizeGet</h2>
1051 17.2 glutSetupVideoResizing, glutStopVideoResizing</h2>
1054 17.3 glutVideoResize</h2>
1057 17.4 glutVideoPan</h2>
1060 18.0 <a NAME="ColorMap"></a>Color Map Functions</h1>
1063 18.1 glutSetColor, glutGetColor</h2>
1066 18.2 glutCopyColormap</h2>
1069 19.0 <a NAME="Miscellaneous"></a>Miscellaneous Functions</h1>
1072 19.1 glutIgnoreKeyRepeat, glutSetKeyRepeat</h2>
1075 19.2 glutForceJoystickFunc</h2>
1078 19.3 glutReportErrors</h2>
1081 20.0 <a NAME="UsageNotes"></a>Usage Notes</h1>
1084 21.0 <a NAME="ImplementationNotes"></a>Implementation Notes</h1>
1087 22.0 <a NAME="GLUT_State"></a>GLUT State</h1>
1090 23.0 <a NAME="Freeglut.h_Header"></a>"freeglut.h" Header File</h1>
1093 24.0 <a NAME="References"></a>References</h1>
1096 25.0 <a NAME="Index"></a>Index</h1>