From 1925fca03062b9602ff86529409c9d2b14b626e0 Mon Sep 17 00:00:00 2001
From: dcnieho
There is considerable confusion about the "right thing to do" concerning
-window size and position. GLUT itself is not consistent between
+window size and position. GLUT itself is not consistent between
Windows and UNIX/X11; since platform independence is a virtue for
freeglut, we decided to break with GLUT's behaviour.
+GLUT was created as a tool to help teach OpenGL programming. To simplify
+development, callbacks were used for handling display, input, and other
+events. But the time it was developed, the purpose, or for some other
+unknown reason, the callbacks lacked any user-provided data argument.
+This has caused considerable difficulties for any significantly advanced
+usage of GLUT, and now freeglut. This has prevented any attempt to
+wrap freeglut in a C++ wrapper, make per-window, per-callback data
+structure, and potentially made it undesirable to modern C developers who
+tend to be well versed in "don't use globals". To combat these
+complaints and issues, many callbacks (with some deprecated
+callbacks excluded) support user-data callbacks provided through additional
+functions provided in freeglut. All callbacks that support user-data
+callbacks are marked as such.
+
+The general rule to follow is to take the freeglut callback function
+and append "Ucall" to the end of the function, add an additional void*
+argument to the end of the argument list of both the freeglut function
+and the callback function. This will pass the user-data to the callback when it's
+invoked.
+ Examples void glutPositionFunc ( void (* func)( int x, int y ) ); void glutKeyboardUpFunc ( void (* func)( unsigned char key, int x, int y ) ); void glutInitErrorFunc ( void (* callback)( const char *fmt, va_list ap) ); These functions have user-data callback functions. Description
The users callback is passed a format string and a variable argument
@@ -943,6 +979,8 @@ The glutShowOverlay and glutHideOverlay functions are not impl
Has user-data callback function. Has user-data callback function. Has user-data callback function.
@@ -998,11 +1040,11 @@ freeglut calls the idle callback when there are no inputs from the user.
Usage void glutIdleFunc ( void (*func)
-( void ) ); void glutIdleFunc ( void (*func ) ( void ) ); funcThe new
-global idle callback function func The new global idle callback function Has user-data callback function. Description
Under UNIX/X11, it is apparently not possible to get the window border
@@ -327,6 +327,40 @@ area--which is NOT the (x,y) position of the window you specified
when you created it.
3.2.2 User-data callbacks
+
+
+void glutPositionFuncUcall ( void (* func)( int x, int y, void* user_data ), void* user_data );
+void glutKeyboardUpFuncUcall ( void (* func)( unsigned char key, int x, int y, void* user_data ), void* user_data );3.3 Terminology
3.4 Differences from GLUT 3.7
@@ -524,6 +558,8 @@ from the library can be handled by the user.
void glutInitWarningFunc ( void (* callback)( const char *fmt, va_list ap) ); 10.1 glutCreateMenu
+10.2 glutDestroyMenu
10.3 glutGetMenu, glutSetMenu
@@ -985,10 +1023,14 @@ stroke font, or an unknown font.
10.11 glutMenuDestroyFunc
+11. Global Callback Registration Functions
11.1 glutTimerFunc
+11.2 glutIdleFunc
Has user-data callback function.
+Has user-data callback function.
+Has user-data callback function.
+Has user-data callback function.
+@@ -1065,6 +1115,8 @@ repositioned/moved programatically or by the user.
void glutPositionFunc ( void (* func)( int x, int y) );
+Has user-data callback function.
+Description
When freeglut calls this callback, it provides the new @@ -1094,6 +1146,8 @@ about to be destroyed.
func The window's new closure callback function
Has user-data callback function.
+Description
@@ -1121,6 +1175,8 @@ alias to glutCloseFunc.
Has user-data callback function.
+
@@ -1145,6 +1201,8 @@ to the window at the time the key is pressed
The y-coordinate of the mouse relative
to the window at the time the key is pressed
Has user-data callback function.
+Description
@@ -1200,6 +1258,8 @@ to the window at the time the key is released
The y-coordinate of the mouse relative
to the window at the time the key is released
Has user-data callback function.
+Description
@@ -1252,6 +1312,8 @@ to the window at the time the key is released
The y-coordinate of the mouse relative
to the window at the time the key is released
Has user-data callback function.
+Description
@@ -1289,8 +1351,12 @@ have them fixed.
Both functions have user-data callback functions.
+Has user-data callback function.
+@@ -1304,6 +1370,8 @@ spins the mouse wheel.
void glutMouseWheelFunc ( void( *callback )( int wheel, int direction, int x, int y ));
+Has user-data callback function.
+Description
If the mouse wheel is spun over your (sub)window, freeglut @@ -1320,8 +1388,12 @@ as mouse buttons.
Has user-data callback function.
+Has user-data callback function.
+@@ -1337,6 +1409,8 @@ provided so that GLUT-based programs can compile and link against
void glutSpaceballMotionFunc ( void (* callback)( int x, int y, int z ) );
+Has user-data callback function.
+Description
The x, y, and z arguments indicate the amount of translation in integer along x, y, and z axis respectively.
@@ -1357,6 +1431,8 @@ provided so that GLUT-based programs can compile and link againstvoid glutSpaceballRotateFunc ( void (* callback)( int rx, int ry, int rz ) );
+Has user-data callback function.
+Description
The rx, ry, and rz arguments indicate the amount of rotation in integer with respect to x, y, and z axis respectively.
@@ -1379,6 +1455,8 @@ The glutSpaceballButtonFunc function sets the window's Spaceball buttonvoid glutSpaceballButtonFunc ( void (* callback)( int button, int updown ) );
+Has user-data callback function.
+Description
The button argument may take one of the following defined @@ -1418,6 +1496,8 @@ The glutDialsFunc function sets the global dials&buttons box callback. void glutButtonBoxFunc ( void (* callback)( int button, int updown ) );
+Has user-data callback function.
+Description
@@ -1442,6 +1522,8 @@ The glutDialsFunc function sets the global dials&buttons box callback.
void glutDialsFunc ( void (* callback)( int dial, int value ) );
+Has user-data callback function.
+Description
@@ -1469,6 +1551,8 @@ that a call to the function will not produce an error.. void glutTabletMotionFunc ( void (* callback)( int x, int y ) );
+Has user-data callback function.
+Description
The glutTabletMotionFunc function @@ -1491,6 +1575,8 @@ that a call to the function will not produce an error..
void glutTabletButtonFunc ( void (* callback)( int button, int updown, int x, int y ) );
+Has user-data callback function.
+Description
@@ -1517,6 +1603,8 @@ these callbacks when the visibility status of a window changes.
void glutWindowStatusFunc ( void( *callback )( int state ));
Both functions have user-data callback functions.
+Description
@@ -2701,6 +2789,8 @@ Currently, under windows, the first (oldest) touch point also controls
the mouse cursor, which triggers the non-multi callbacks as
usual.
+All these functions have user-data callback functions.
+
Limitation: currently on the cursor id is provided. It may be
@@ -2729,9 +2819,11 @@ whether/how to implement it.
glutInitContextFunc ← void
: called when the context
-is initialized or re-initialized (e.g. after a pause)glutAppStatusFunc ← event
: called when the
-application's status changes, with event identifying the state entered.
+application's status changes, with event identifying the state entered. Has
+user-data callback function.
Possible states: