diff --git a/.gitattributes b/.gitattributes index 06e7fe1..4dd48a2 100644 --- a/.gitattributes +++ b/.gitattributes @@ -13,6 +13,7 @@ freeglut/freeglut/configure.in svn_keywords=Author+Date+Id+Revision freeglut/freeglut/doc/download.html svn_keywords=Author+Date+Id+Revision freeglut/freeglut/doc/freeglut.html svn_keywords=Author+Date+Id+Revision freeglut/freeglut/doc/freeglut_logo.png -text +freeglut/freeglut/doc/freeglut_user_interface.html svn_keywords=Author+Date+Id+Revision freeglut/freeglut/doc/index.html svn_keywords=Author+Date+Id+Revision freeglut/freeglut/doc/ogl_sm.png -text freeglut/freeglut/doc/progress.html svn_keywords=Author+Date+Id+Revision diff --git a/freeglut/freeglut/doc/freeglut_user_interface.html b/freeglut/freeglut/doc/freeglut_user_interface.html new file mode 100644 index 0000000..c57a4ce --- /dev/null +++ b/freeglut/freeglut/doc/freeglut_user_interface.html @@ -0,0 +1,1116 @@ + + +
+ + + +
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.
+
+
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
+
+
+
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. +
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. +
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.) +
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. +
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. +
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. +
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 supports the following stroke fonts: +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
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. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+