From 880eb0134415bc4b4e5a35be911ffe82d135dd1f Mon Sep 17 00:00:00 2001 From: Don Heyse Date: Tue, 26 Nov 2002 19:56:55 +0000 Subject: [PATCH] Added on behalf of John Fay. git-svn-id: svn+ssh://svn.code.sf.net/p/freeglut/code/trunk/freeglut/freeglut@29 7f0cb862-5218-0410-a997-914c9d46530a --- doc/freeglut_user_interface.html | 1116 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 1116 insertions(+) create mode 100644 doc/freeglut_user_interface.html diff --git a/doc/freeglut_user_interface.html b/doc/freeglut_user_interface.html new file mode 100644 index 0000000..c57a4ce --- /dev/null +++ b/doc/freeglut_user_interface.html @@ -0,0 +1,1116 @@ + + + + + + + FREEGLUT Application Program Interface + + + +
+
+

+The Open-Source

+ +
+

+OpenGL Utility Toolkit

+ +
+

+(freeglut)

+ +
+

+Application Programming Interface

+
+ +
+

+Version 4.0

+ +
+

+The freeglut Programming Consortium

+ +
+

+November, 2002

+ +


OpenGL is a trademark of Silicon Graphics, Inc. X Window System +is a trademark of X Consortium, Inc.  Spaceball is a registered trademark +of Spatial Systems Inc. +
The authors have taken care in preparation of this documentation but +make no expressed or implied warranty of any kind and assumes no responsibility +for errors or omissions. No liability is assumed for incidental or consequential +damages in connection with or arising from the use of information or programs +contained herein. +
  +

+1.0 Contents

+1.0  Contents +

2.0  Introduction +

3.0  Background +

3.1  Design Philosophy +
3.2  Conventions +
3.3  Terminology +
3.4  Differences from GLUT 3.7
+ +


4.0  Initialization Functions +

4.1  glutInit +
4.2  glutInitWindowPosition, glutInitWindowSize +
4.3  glutInitDisplayMode +
4.4  glutInitDisplayString
+ +


5.0  Event Processing Functions +

5.1  glutMainLoop +
5.2  glutMainLoopEvent +
5.3  glutLeaveMainLoop
+ +


6.0  Window Functions +

6.1  glutCreateWindow +
6.2  glutCreateSubwindow +
6.3  glutDestroyWindow +
6.4  glutSetWindow, glutGetWindow +
6.5  glutSetWindowTitle, glutSetIconTitle +
6.6  glutReshapeWindow +
6.7  glutPositionWindow +
6.8  glutShowWindow, glutHideWindow, glutIconifyWindow +
6.9  glutPushWindow, glutPopWindow +
6.10  glutFullScreen
+ +


7.0  Display Functions +

7.1  glutPostRedisplay +
7.2  glutPostWindowRedisplay +
7.3  glutSwapBuffers
+ +


8.0  Mouse Cursor Functions +

8.1  glutSetCursor +
8.2  glutWarpPointer
+ +


9.0  Overlay Functions +

9.1  glutEstablishOverlay +
9.2  glutRemoveOverlay +
9.3  glutUseLayer +
9.4  glutPostOverlayRedisplay +
9.5  glutPostWindowOverlayRedisplay +
9.6  glutShowOverlay, glutHideOverlay
+ +


10.0  Menu Functions +

10.1  glutCreateMenu +
10.2  glutDestroyMenu +
10.3  glutGetMenu, glutSetMenu +
10.4  glutAddMenuEntry +
10.5  glutAddSubMenu +
10.6  glutChangeToMenuEntry +
10.7  glutChangeToSubMenu +
10.8  glutRemoveMenuItem +
10.9  glutAttachMenu, glutDetachMenu
+ +


11.0  Global Callback Registration +Functions +

11.1  glutTimerFunc +
11.2  glutIdleFunc
+ +


12.0  Window-Specific Callback Registration +Functions +

12.1  glutDisplayFunc +
12.2  glutOverlayDisplayFunc +
12.3  glutReshapeFunc +
12.4  glutCloseFunc +
12.5  glutKeyboardFunc +
12.6  glutSpecialFunc +
12.7  glutKeyboardUpFunc +
12.8  glutSpecialUpFunc +
12.9  glutMouseFunc +
12.10  glutMotionFunc, glutPassiveMotionFunc +
12.11  glutVisibilityFunc +
12.12  glutEntryFunc +
12.13  glutJoystickFunc +
12.14  glutSpaceballMotionFunc +
12.15  glutSpaceballRotateFunc +
12.16  glutSpaceballButtonFunc +
12.17  glutButtonBoxFunc +
12.18  glutDialsFunc +
12.19  glutTabletMotionFunc +
12.20  glutTabletButtonFunc +

12.21  glutMenuStatusFunc +
12.22  glutWindowStatusFunc

+ +


13.0  State Setting and Retrieval Functions +

13.1  glutSetOption +
13.2  glutGet +
13.3  glutDeviceGet +
13.4  glutGetModifiers +
13.5  glutLayerGet +
13.6  glutExtensionSupported
+ +


14.0  Font Rendering Functions +

14.1  glutBitmapCharacter +
14.2  glutBitmapString +
14.3  glutBitmapWidth +
14.4  glutBitmapLength +
14.5  glutBitmapHeight +
14.6  glutStrokeCharacter +
14.7  glutStrokeString +
14.8  glutStrokeWidth +
14.9  glutStrokeLength +
14.10  glutStrokeHeight
+ +


15.0  Geometric Object Rendering +Functions +

15.1  glutWireSphere, glutSolidSphere +
15.2  glutWireTorus, glutSolidTorus +
15.3  glutWireCone, glutSolidCone +
15.4  glutWireCube, glutSolidCube +
15.5  glutWireTetrahedron, glutSolidTetrahedron +
15.6  glutWireOctahedron, glutSolidOctahedron +
15.7  glutWireDodecahedron, glutSolidDodecahedron +
15.8  glutWireIcosahedron, glutSolidIcosahedron +
15.9  glutWireRhombicDodecahedron, glutSolidRhombicDodecahedron +
15.10  glutWireTeapot, glutSolidTeapot
+ +


16.0  Game Mode Functions +

16.1  glutGameModeString +
16.2  glutEnterGameMode, glutLeaveGameMode +
16.3  glutGameModeGet
+ +


17.0  Video Resize Functions +

17.1  glutVideoResizeGet +
17.2  glutSetupVideoResizing, glutStopVideoResizing +
17.3  glutVideoResize +
17.4  glutVideoPan
+ +


18.0  Color Map Functions +

18.1  glutSetColor, glutGetColor +
18.2  glutCopyColormap
+ +


19.0  Miscellaneous Functions +

19.1  glutIgnoreKeyRepeat, glutSetKeyRepeat +
19.2  glutForceJoystickFunc +
19.3  glutReportErrors
+ +


20.0  Usage Notes +

21.0  Implementation Notes +

22.0  GLUT State +

23.0  "freeglut.h" Header File +

24.0  References +

25.0  Index +
  +
  +

+2.0 Introduction

+  +

+3.0 Background

+The OpenGL programming world owes a tremendous debt to Mr. Mark J. Kilgard +for writing the OpenGL Utility Toolkit, or GLUT.  The GLUT library +of functions allows an application programmer to create, control, and manipulate +windows independent of what operating system the program is running on.  +By hiding the dependency on the operating system from the application programmer, +he allowed people to write truly portable OpenGL applications. +

    Mr. Kilgard copyrighted his library and gave it a +rather unusual license.  Under his license, people are allowed freely +to copy and distribute the libraries and the source code, but they are +not allowed to modify it.  For a long time this did not matter because +the GLUT library worked so well and because Mr. Kilgard was releasing updates +on a regular basis.  But with the passage of time, people started +wanting some slightly different behaviours in their windowing system.  +When Mr. Kilgard stopped supporting the GLUT library in 1999, having moved +on to bigger and better things, this started to become a problem. +

    In December 1999, Mr. Pawel Olzsta started work on +an open-source clone of the GLUT library.  This open-source clone, +which does not use any of the GLUT source code, has evolved into the present +freeglut +library.  This documentation specifies the application program interface +to the freeglut library. +

+3.1  Design Philosophy

+ +

+3.2  Conventions

+ +

+3.3  Terminology

+ +

+3.4  Differences from GLUT 3.7

+Since the freeglut library was developed in order to update GLUT, +it is natural that there will be some differences between the two.  +Each function in the API notes any differences between the GLUT and the +freeglut +function behaviours.  The important ones are summarized here. +

+3.4.1  glutMainLoop Behaviour

+One of the commonest complaints about the GLUT library was that once an +application called "glutMainLoop", it never got control back.  +There was no way for an application to loop in GLUT for a while, possibly +as a subloop while a specific window was open, and then return to the calling +function.  A new function, "glutMainLoopEvent", has been +added to allow this functionality.  Another function, "glutLeaveMainLoop", +has also been added to allow the application to tell freeglut to clean +up and close down. +

+3.4.2  Action on Window Closure

+Another difficulty with GLUT, especially with multiple-window programs, +is that if the user clicks on the "x" in the window header the application +exits immediately.  The application programmer can now set an option, +"GLUT_ACTION_ON_WINDOW_CLOSE", to specify whether execution should +continue, whether GLUT should return control to the main program, or whether +GLUT should simply exit (the default). +

+3.4.3  String Rendering

+New functions have been added to render full character strings (including +carriage returns) rather than rendering one character at a time.  +More functions return the widths of character strings and the font heights, +in pixels for bitmapped fonts and in OpenGL units for the stroke fonts. +

+3.4.4  Geometry Rendering

+Two functions have been added to render a wireframe and a solid rhombic +dodecahedron. +

+4.0 Initialization Functions

+ +

+4.1  glutInit

+ +

+4.2  glutInitWindowPosition, glutInitWindowSize

+ +

+4.3  glutInitDisplayMode

+ +

+4.4  glutInitDisplayString

+ +

+5.0 Event Processing Functions

+After an application has finished initializing its windows and menus, it +enters an event loop.  Within this loop, freeglut polls the +data entry devices (keyboard, mouse, etc.) and calls the application's +appropriate callbacks. +

In GLUT, control never returned from the event loop (as invoked by the +"glutMainLoop" function) to the calling function.  This prevented +an application from having re-entrant code, in which GLUT could be invoked +from within a callback, and it prevented the application from doing any +post-processing (such as freeing allocated memory) after GLUT had closed +down.  Freeglut allows the application programmer to specify +more direct control over the event loop by means of two new functions.  +The first, "glutMainLoopEvent", processes a single iteration of +the event loop and allows the application to use a different event loop +controller or to contain re-entrant code.  The second, "glutLeaveMainLoop", +causes the event loop to exit nicely; this is preferable to the application's +calling "exit" from within a GLUT callback. +

+5.1  glutMainLoop

+The "glutMainLoop" function enters the event loop. +

Usage +

void glutMainLoop ( void ) ; +

Description +

The  "glutMainLoop" function causes the program to enter +the window event loop.  An application should call this function at +most once.  It will call any application callback functions as required +to process mouse clicks, mouse motion, key presses, and so on. +

Changes From GLUT +

In GLUT, there was absolutely no way for the application programmer +to have control return from the "glutMainLoop" function to the +calling function.  Freeglut allows the programmer to force +this by setting the "GLUT_ACTION_ON_WINDOW_CLOSE" option and invoking +the "glutLeaveMainLoop" function from one of the callbacks.  +Stopping the program this way is preferable to simply calling "exit" +from within a callback because this allows freeglut to free allocated +memory and otherwise clean up after itself.  (I know I just said this, +but I think it is important enough that it bears repeating.) +

+5.2  glutMainLoopEvent

+The "glutMainLoopEvent" function processes a single iteration +in the freeglut event loop. +

Usage +

void glutMainLoopEvent ( void ) ; +

Description +

The  "glutMainLoopEvent" function causes freeglut +to process one iteration's worth of events in its event loop.  This +allows the application to control its own event loop and still use the +freeglut windowing system. +

Changes From GLUT +

GLUT does not include this function. +

+5.3  glutLeaveMainLoop

+The "glutLeaveMainLoop" function causes freeglut to stop +its event loop. +

Usage +

void glutLeaveMainLoop ( void ) ; +

Description +

The  "glutLeaveMainLoop" function causes freeglut +to stop the event loop.  If the "GLUT_ACTION_ON_WINDOW_CLOSE" +option has been set to "GLUT_ACTION_CONTINUE_EXECUTION", control +will return to the function which called "glutMainLoop"; otherwise +the application will exit. +

Changes From GLUT +

GLUT does not include this function. +

+6.0 Window Functions

+ +

+6.1  glutCreateWindow

+ +

+6.2  glutCreateSubwindow

+ +

+6.3  glutDestroyWindow

+ +

+6.4  glutSetWindow, glutGetWindow

+ +

+6.5  glutSetWindowTitle, glutSetIconTitle

+ +

+6.6  glutReshapeWindow

+ +

+6.7  glutPositionWindow

+ +

+6.8  glutShowWindow, glutHideWindow, glutIconifyWindow

+ +

+6.9  glutPushWindow, glutPopWindow

+ +

+6.10  glutFullScreen

+ +

+7.0 Display Functions

+ +

+7.1  glutPostRedisplay

+ +

+7.2  glutPostWindowRedisplay

+ +

+7.3  glutSwapBuffers

+ +

+8.0 Mouse Cursor Functions

+ +

+8.1  glutSetCursor

+ +

+8.2  glutWarpPointer

+ +

+9.0 Overlay Functions

+ +

+9.1  glutEstablishOverlay

+ +

+9.2  glutRemoveOverlay

+ +

+9.3  glutUseLayer

+ +

+9.4  glutPostOverlayRedisplay

+ +

+9.5  glutPostWindowOverlayRedisplay

+ +

+9.6  glutShowOverlay, glutHideOverlay

+ +

+10.0 Menu Functions

+ +

+10.1  glutCreateMenu

+ +

+10.2  glutDestroyMenu

+ +

+10.3  glutGetMenu, glutSetMenu

+ +

+10.4  glutAddMenuEntry

+ +

+10.5  glutAddSubMenu

+ +

+10.6  glutChangeToMenuEntry

+ +

+10.7  glutChangeToSubMenu

+ +

+10.8  glutRemoveMenuItem

+ +

+10.9  glutAttachMenu, glutDetachMenu

+ +

+11.0 Global Callback Registration Functions

+ +

+11.1  glutTimerFunc

+ +

+11.2  glutIdleFunc

+The "glutIdleFunc" function sets the global idle callback. Freeglut +calls the idle callback when there are no inputs from the user. +

Usage +

void glutIdleFunc ( void (*func) ( void ) ) ; +

func    The new global idle callback function +

Description +

The  "glutIdleFunc" function specifies the function that +freeglut +will call to perform background processing tasks such as continuous animation +when window system events are not being received.  If enabled, this +function is called continuously from freeglut while no events are +received.  The callback function has no parameters and returns no +value.  Freeglut does not change the current window +or the current menu before invoking the idle callback; programs +with multiple windows or menus must explicitly set the current window +and current menu and not rely on its current setting. +
    The amount of computation and rendering done in +an idle callback should be minimized to avoid affecting the program's interactive +response.  In general, no more than a single frame of rendering should +be done in a single invocation of an idle callback. +
    Calling "glutIdleFunc" with a NULL argument +disables the call to an idle callback. +

Changes From GLUT +

Application programmers should note that if they have specified the +"continue execution" action on window closure, freeglut will continue +to call the idle callback after the user has closed a window by clicking +on the "x" in the window header bar.  If the idle callback renders +a particular window (this is considered bad form but is frequently done +anyway), the programmer should supply a window closure callback for that +window which changes or disables the idle callback. +

+12.0 Window-Specific Callback Registration +Functions

+ +

+12.1  glutDisplayFunc

+ +

+12.2  glutOverlayDisplayFunc

+ +

+12.3  glutReshapeFunc

+ +

+12.4  glutCloseFunc

+ +

+12.5  glutKeyboardFunc

+ +

+12.6  glutSpecialFunc

+ +

+12.7  glutKeyboardUpFunc

+ +

+12.8  glutSpecialUpFunc

+ +

+12.9  glutMouseFunc

+ +

+12.10  glutMotionFunc, glutPassiveMotionFunc

+ +

+12.11  glutVisibilityFunc

+ +

+12.12  glutEntryFunc

+ +

+12.13  glutJoystickFunc

+ +

+12.14  glutSpaceballMotionFunc

+ +

+12.15  glutSpaceballRotateFunc

+ +

+12.16  glutSpaceballButtonFunc

+ +

+12.17  glutButtonBoxFunc

+ +

+12.18  glutDialsFunc

+ +

+12.19  glutTabletMotionFunc

+ +

+12.20  glutTabletButtonFunc

+ +

+12.21  glutMenuStatusFunc

+ +

+12.22  glutWindowStatusFunc

+ +

+13.0 State Setting and Retrieval Functions

+ +

+13.1  glutSetOption

+ +

+13.2  glutGet

+ +

+13.3  glutDeviceGet

+ +

+13.4  glutGetModifiers

+ +

+13.5  glutLayerGet

+ +

+13.6  glutExtensionSupported

+ +

+14.0 Font Rendering Functions

+Freeglut supports two types of font rendering:  bitmap fonts, +which are rendered using the "glBitmap" function call, and stroke +fonts, which are rendered as sequences of OpenGL line segments.  Because +they are rendered as bitmaps, the bitmap fonts tend to render more quickly +than stroke fonts, but they are less flexible in terms of scaling and rendering.  +Bitmap font characters are positioned with calls to the "glRasterPos*" +functions while stroke font characters use the OpenGL transformations to +position characters. +

    It should be noted that freeglut fonts are +similar but not identical to GLUT fonts.  At the moment, freeglut +fonts do not support the "`" (backquote) and "|" (vertical line) characters; +in their place it renders asterisks. +

    Freeglut supports the following bitmap fonts: +

+Freeglut calls "glRasterPos4v" to advance the cursor by +the width of a character and to render carriage returns when appropriate.  +It does not use any display lists in it rendering in bitmap fonts. +

    Freeglut supports the following stroke fonts: +

+Freeglut does not use any display lists in its rendering of stroke +fonts.  It calls "glTranslatef" to advance the cursor by +the width of a character and to render carriage returns when appropriate. +

+14.1  glutBitmapCharacter

+The "glutBitmapCharacter" function renders a single bitmapped +character in the current window using the specified font. +

Usage +

void glutBitmapCharacter ( void *font, int character ) ; +

font        The bitmapped +font to use in rendering the character +
character   The ASCII code of the character to be +rendered +

Description +

The  "glutBitmapCharacter" function renders the given +character in the specified bitmap font.  Freeglut automatically +sets the necessary pixel unpack storage modes and restores the existing +modes when it has finished.  Before the first call to "glutBitMapCharacter" +the application program should call "glRasterPos*" to set the +position of the character in the window.  The "glutBitmapCharacter" +function advances the cursor position as part of its call to "glBitmap" +and so the application does not need to call "glRasterPos*" again +for successive characters on the same line. +

Changes From GLUT +

Nonexistent characters are rendered as asterisks.  The rendering +position in freeglut is apparently off from GLUT's position by a +few pixels vertically and one or two pixels horizontally. +

+14.2  glutBitmapString

+The "glutBitmapString" function renders a string of bitmapped +characters in the current window using the specified font. +

Usage +

void glutBitmapString ( void *font, char *string ) ; +

font      The bitmapped font to use +in rendering the character string +
string    String of characters to be rendered +

Description +

The  "glutBitmapString" function renders the given character +string in the specified bitmap font.  Freeglut automatically +sets the necessary pixel unpack storage modes and restores the existing +modes when it has finished.  Before calling "glutBitMapString" +the application program should call "glRasterPos*" to set the +position of the string in the window.  The "glutBitmapString" +function handles carriage returns.  Nonexistent characters are rendered +as asterisks. +

Changes From GLUT +

GLUT does not include this function. +

+14.3  glutBitmapWidth

+The "glutBitmapWidth" function returns the width in pixels of +a single bitmapped character in the specified font. +

Usage +

int glutBitmapWidth ( void *font, int character ) ; +

font        The bitmapped +font to use in calculating the character width +
character   The ASCII code of the character +

Description +

The  "glutBitmapWidth" function returns the width of the +given character in the specified bitmap font.  Because the font is +bitmapped, the width is an exact integer. +

Changes From GLUT +

Nonexistent characters return the width of an asterisk. +

+14.4  glutBitmapLength

+The "glutBitmapLength" function returns the width in pixels of +a string of bitmapped characters in the specified font. +

Usage +

int glutBitmapLength ( void *font, char *string ) ; +

font    The bitmapped font to use in calculating +the character width +
string  String of characters whose width is to be calculated +

Description +

The  "glutBitmapLength" function returns the width in +pixels of the given character string in the specified bitmap font.  +Because the font is bitmapped, the width is an exact integer:  the +return value is identical to the sum of the character widths returned by +a series of calls to "glutBitmapWidth".  The width of nonexistent +characters is counted to be the width of an asterisk. +

    If the string contains one or more carriage returns, +freeglut +calculates the widths in pixels of the lines separately and returns the +largest width. +

Changes From GLUT +

GLUT does not include this function. +

+14.5  glutBitmapHeight

+The "glutBitmapHeight" function returns the height in pixels of +the specified font. +

Usage +

int glutBitmapHeight ( void *font ) ; +

font        The bitmapped +font to use in calculating the character height +

Description +

The  "glutBitmapHeight" function returns the height of +a character in the specified bitmap font.  Because the font is bitmapped, +the height is an exact integer.  The fonts are designed such that +all characters have (nominally) the same height. +

Changes From GLUT +

GLUT does not include this function. +

+14.6  glutStrokeCharacter

+The "glutStrokeCharacter" function renders a single stroke character +in the current window using the specified font. +

Usage +

void glutStrokeCharacter ( void *font, int character ) ; +

font        The stroke font +to use in rendering the character +
character   The ASCII code of the character to be +rendered +

Description +

The  "glutStrokeCharacter" function renders the given +character in the specified stroke font.  Before the first call to +"glutStrokeCharacter" the application program should call the +OpenGL transformation (positioning and scaling) functions to set the position +of the character in the window.  The "glutStrokeCharacter" +function advances the cursor position by a call to "glTranslatef" +and so the application does not need to call the OpenGL positioning functions +again for successive characters on the same line. +

Changes From GLUT +

Nonexistent characters are rendered as asterisks. +

+14.7  glutStrokeString

+The "glutStrokeString" function renders a string of characters +in the current window using the specified stroke font. +

Usage +

void glutStrokeString ( void *font, char *string ) ; +

font      The stroke font to use in +rendering the character string +
string    String of characters to be rendered +

Description +

The  "glutStrokeString" function renders the given character +string in the specified stroke font.  Before calling "glutStrokeString" +the application program should call the OpenGL transformation (positioning +and scaling) functions to set the position of the string in the window.  +The "glutStrokeString" function handles carriage returns.  +Nonexistent characters are rendered as asterisks. +

Changes From GLUT +

GLUT does not include this function. +

+14.8  glutStrokeWidth

+The "glutStrokeWidth" function returns the width in pixels of +a single character in the specified stroke font. +

Usage +

int glutStrokeWidth ( void *font, int character ) ; +

font        The stroke font +to use in calculating the character width +
character   The ASCII code of the character +

Description +

The  "glutStrokeWidth" function returns the width of the +given character in the specified stroke font.  Because the font is +a stroke font, the width is actually a floating-point number; the function +rounds it to the nearest integer for the return value. +

Changes From GLUT +

Nonexistent characters return the width of an asterisk. +

+14.9  glutStrokeLength

+The "glutStrokeLength" function returns the width in pixels of +a string of characters in the specified stroke font. +

Usage +

int glutStrokeLength ( void *font, char *string ) ; +

font    The stroke font to use in calculating +the character width +
string  String of characters whose width is to be calculated +

Description +

The  "glutStrokeLength" function returns the width in +pixels of the given character string in the specified stroke font.  +Because the font is a stroke font, the width of an individual character +is a floating-point number.  Freeglut adds the floating-point +widths and rounds the funal result to return the integer value.  Thus +the return value may differ from the sum of the character widths returned +by a series of calls to "glutStrokeWidth".  The width of +nonexistent characters is counted to be the width of an asterisk. +

    If the string contains one or more carriage returns, +freeglut +calculates the widths in pixels of the lines separately and returns the +largest width. +

Changes From GLUT +

GLUT does not include this function. +

+14.10  glutStrokeHeight

+The "glutStrokeHeight" function returns the height in pixels of +the specified font. +

Usage +

GLfloat glutStrokeHeight ( void *font ) ; +

font        The stroke font +to use in calculating the character height +

Description +

The  "glutStrokeHeight" function returns the height of +a character in the specified stroke font.  The application programmer +should note that, unlike the other freeglut font functions, this +one returns a floating-point number.  The fonts are designed such +that all characters have (nominally) the same height. +

Changes From GLUT +

GLUT does not include this function. +

+15.0 Geometric Object Rendering Functions

+Freeglut includes eighteen routines for generating easily-recognizable +3-d geometric objects.  These routines are effectively the same ones +that are included in the GLUT library, and reflect the functionality available +in the aux toolkit described in the OpenGL Programmer's Guide.  +They are included to allow programmers to create with a single line of +code a three-dimensional object which can be used to test a variety of +OpenGL functionality.  None of the routines generates a display list +for the object which it draws.  The functions generate normals appropriate +for lighting but, except for the teapon functions, do not generate texture +coordinates. +

+15.1  glutWireSphere, glutSolidSphere

+The "glutWireSphere" and "glutSolidSphere" functions +draw a wireframe and solid sphere respectively. +

Usage +

void glutWireSphere ( GLdouble dRadius, GLint slices, GLint stacks +) ; +

void glutSolidSphere ( GLdouble dRadius, GLint slices, GLint stacks +) ; +

dRadius       The desired radius +of the sphere +

slices        The desired +number of slices (divisions in the longitudinal direction) in the sphere +

stacks        The desired +number of stacks (divisions in the latitudinal direction) in the sphere.  +The number of points in this direction, including the north and south poles, +is stacks+1 +

Description +

The "glutWireSphere" and "glutSolidSphere" functions +render a sphere centered at the origin of the modeling coordinate system.  +The north and south poles of the sphere are on the positive and negative +Z-axes respectively and the prime meridian crosses the positive X-axis. +

Changes From GLUT +

None that we know of. +

+15.2  glutWireTorus, glutSolidTorus

+The "glutWireTorus" and "glutSolidTorus" functions draw +a wireframe and solid torus (donut shape) respectively. +

Usage +

void glutWireTorus ( GLdouble dInnerRadius, GLdouble dOuterRadius, +GLint nSides, GLint nRings ) ; +

void glutSolidTorus ( GLdouble dInnerRadius, GLdouble dOuterRadius, +GLint nSides, GLint nRings ) ; +

dInnerRadius        The +desired inner radius of the torus, from the origin to the circle defining +the centers of the outer circles +

dOuterRadius        The +desired outer radius of the torus, from the center of the outer circle +to the actual surface of the torus +

nSides        The desired +number of segments in a single outer circle of the torus +

nRings        The desired +number of outer circles around the origin of the torus +

Description +

The "glutWireTorus" and "glutSolidTorus" functions +render a torus centered at the origin of the modeling coordinate system.  +The torus is circularly symmetric about the Z-axis and starts at the positive +X-axis. +

Changes From GLUT +

None that we know of. +

+15.3  glutWireCone, glutSolidCone

+The "glutWireCone" and "glutSolidCone" functions draw +a wireframe and solid cone respectively. +

Usage +

void glutWireCone ( GLdouble base, GLdouble height, GLint slices, +GLint stacks ) ; +

void glutSolidCone ( GLdouble base, GLdouble height, GLint slices, +GLint stacks ) ; +

base          The +desired radius of the base of the cone +

height        The desired +height of the cone +

slices        The desired +number of slices around the base of the cone +

stacks        The desired +number of segments between the base and the tip of the cone (the number +of points, including the tip, is stacks + 1) +

Description +

The "glutWireCone" and "glutSolidCone" functions render +a right circular cone with a base centered at the origin and in the X-Y +plane and its tip on the positive Z-axis.  The wire cone is rendered +with triangular elements. +

Changes From GLUT +

None that we know of. +

+15.4  glutWireCube, glutSolidCube

+The "glutWireCube" and "glutSolidCube" functions draw +a wireframe and solid cube respectively. +

Usage +

void glutWireCube ( GLdouble dSize ) ; +

void glutSolidCube ( GLdouble dSize ) ; +

dSize         The desired +length of an edge of the cube +

Description +

The "glutWireCube" and "glutSolidCube" functions render +a cube of the desired size, centered at the origin.  Its faces are +normal to the coordinate directions. +

Changes From GLUT +

None that we know of. +

+15.5  glutWireTetrahedron, glutSolidTetrahedron

+The "glutWireTetrahedron" and "glutSolidTetrahedron" +functions draw a wireframe and solid tetrahedron (four-sided Platonic solid) +respectively. +

Usage +

void glutWireTetrahedron ( void ) ; +

void glutSolidTetrahedron ( void ) ; +

Description +

The "glutWireTetrahedron" and "glutSolidTetrahedron" +functions render a tetrahedron whose corners are each a distance of one +from the origin.  The length of each side is 2/3 sqrt(6).  One +corner is on the positive X-axis and another is in the X-Y plane with a +positive Y-coordinate. +

Changes From GLUT +

None that we know of. +

+15.6  glutWireOctahedron, glutSolidOctahedron

+The "glutWireOctahedron" and "glutSolidOctahedron" functions +draw a wireframe and solid octahedron (eight-sided Platonic solid) respectively. +

Usage +

void glutWireOctahedron ( void ) ; +

void glutSolidOctahedron ( void ) ; +

Description +

The "glutWireOctahedron" and "glutSolidOctahedron" +functions render an octahedron whose corners are each a distance of one +from the origin.  The length of each side is sqrt(2).  The corners +are on the positive and negative coordinate axes. +

Changes From GLUT +

None that we know of. +

+15.7  glutWireDodecahedron, glutSolidDodecahedron

+The "glutWireDodecahedron" and "glutSolidDodecahedron" +functions draw a wireframe and solid dodecahedron (twelve-sided Platonic +solid) respectively. +

Usage +

void glutWireDodecahedron ( void ) ; +

void glutSolidDodecahedron ( void ) ; +

Description +

The "glutWireDodecahedron" and "glutSolidDodecahedron" +functions render a dodecahedron whose corners are each a distance of sqrt(3) +from the origin.  The length of each side is sqrt(5)-1.  There +are twenty corners; interestingly enough, eight of them coincide with the +corners of a cube with sizes of length 2. +

Changes From GLUT +

None that we know of. +

+15.8  glutWireIcosahedron, glutSolidIcosahedron

+The "glutWireIcosahedron" and "glutSolidIcosahedron" +functions draw a wireframe and solid icosahedron (twenty-sided Platonic +solid) respectively. +

Usage +

void glutWireIcosahedron ( void ) ; +

void glutSolidIcosahedron ( void ) ; +

Description +

The "glutWireIcosahedron" and "glutSolidIcosahedron" +functions render an icosahedron whose corners are each a unit distance +from the origin.  The length of each side is slightly greater than +one.  Two of the corners lie on the positive and negative X-axes. +

Changes From GLUT +

None that we know of. +

+15.7  glutWireRhombicDodecahedron, glutSolidRhombicDodecahedron

+The "glutWireRhombicDodecahedron" and "glutSolidRhombicDodecahedron" +functions draw a wireframe and solid rhombic dodecahedron (twelve-sided +semi-regular solid) respectively. +

Usage +

void glutWireRhombicDodecahedron ( void ) ; +

void glutSolidRhombicDodecahedron ( void ) ; +

Description +

The "glutWireRhombicDodecahedron" and "glutSolidRhombicDodecahedron" +functions render a rhombic dodecahedron whose corners are at most a distance +of one from the origin.  The rhombic dodecahedron has faces which +are identical rhombuses (rhombi?) but which have some vertices at which +three faces meet and some vertices at which four faces meet.  The +length of each side is sqrt(3)/2.  Vertices at which four faces meet +are found at (0, 0, +1) and (+sqrt(2)/2, +sqrt(2)/2, +0). +

Changes From GLUT +

GLUT does not include these functions. +

+15.10  glutWireTeapot, glutSolidTeapot

+The "glutWireTeapot" and "glutSolidTeapot" functions +draw a wireframe and solid teapot respectively. +

Usage +

void glutWireTeapot ( GLdouble dSize ) ; +

void glutSolidTeapot ( GLdouble dSize ) ; +

dSize         The desired +size of the teapot +

Description +

The "glutWireTeapot" and "glutSolidTeapot" functions +render a teapot of the desired size, centered at the origin.  This +is the famous OpenGL teapot [add reference]. +

Changes From GLUT +

None that we know of. +

+16.0 Game Mode Functions

+ +

+16.1  glutGameModeString

+ +

+16.2  glutEnterGameMode, glutLeaveGameMode

+ +

+16.3  glutGameModeGet

+ +

+17.0 Video Resize Functions

+ +

+17.1  glutVideoResizeGet

+ +

+17.2  glutSetupVideoResizing, glutStopVideoResizing

+ +

+17.3  glutVideoResize

+ +

+17.4  glutVideoPan

+ +

+18.0 Color Map Functions

+ +

+18.1  glutSetColor, glutGetColor

+ +

+18.2  glutCopyColormap

+ +

+19.0 Miscellaneous Functions

+ +

+19.1  glutIgnoreKeyRepeat, glutSetKeyRepeat

+ +

+19.2  glutForceJoystickFunc

+ +

+19.3  glutReportErrors

+ +

+20.0 Usage Notes

+ +

+21.0 Implementation Notes

+ +

+22.0 GLUT State

+ +

+23.0 "freeglut.h" Header File

+ +

+24.0 References

+ +

+25.0 Index

+  +

  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  + + -- 1.7.10.4