Updated documentation to mention and discuss user-data callbacks.
This commit is contained in:
Rcmaniac25
parent
666b80843a
commit
682d4d096a
@ -301,7 +301,7 @@ and their compatibility with GLUT, are made explicit.
|
||||
|
||||
<p>
|
||||
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
|
||||
<i>freeglut</i>, we decided to break with GLUT's behaviour. <br>
|
||||
Under UNIX/X11, it is apparently not possible to get the window border
|
||||
@ -327,6 +327,40 @@ area--which is <u>NOT</u> the (x,y) position of the window you specified
|
||||
when you created it.</ul>
|
||||
</p>
|
||||
|
||||
<h3>3.2.2 User-data callbacks</h3>
|
||||
|
||||
<p>
|
||||
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 <i>freeglut</i>. This has prevented any attempt to
|
||||
wrap <i>freeglut</i> 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 <i>issues</i>, many callbacks (with some deprecated
|
||||
callbacks excluded) support user-data callbacks provided through additional
|
||||
functions provided in <i>freeglut</i>. All callbacks that support user-data
|
||||
callbacks are marked as such.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The general rule to follow is to take the <i>freeglut</i> callback function
|
||||
and append "Ucall" to the end of the function, add an additional <tt>void*</tt>
|
||||
argument to the end of the argument list of both the <i>freeglut</i> function
|
||||
and the callback function. This will pass the user-data to the callback when it's
|
||||
invoked.
|
||||
</p>
|
||||
|
||||
<p><b>Examples</b></p>
|
||||
|
||||
<p><tt>void glutPositionFunc ( void (* func)( int x, int y ) );</tt><br>
|
||||
<tt>void glutPositionFuncUcall ( void (* func)( int x, int y, void* user_data ), void* user_data );</tt></p>
|
||||
|
||||
<p><tt>void glutKeyboardUpFunc ( void (* func)( unsigned char key, int x, int y ) );</tt><br>
|
||||
<tt>void glutKeyboardUpFuncUcall ( void (* func)( unsigned char key, int x, int y, void* user_data ), void* user_data );</tt></p>
|
||||
|
||||
<h2>3.3 Terminology</h2>
|
||||
|
||||
<h2>3.4 Differences from GLUT 3.7</h2>
|
||||
@ -524,6 +558,8 @@ from the library can be handled by the user.
|
||||
<p><tt>void glutInitErrorFunc ( void (* callback)( const char *fmt, va_list ap) );</tt><br/>
|
||||
<tt>void glutInitWarningFunc ( void (* callback)( const char *fmt, va_list ap) );</tt> </p>
|
||||
|
||||
<p>These functions have user-data callback functions.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
<p>
|
||||
The users callback is passed a format string and a variable argument
|
||||
@ -943,6 +979,8 @@ The <tt>glutShowOverlay</tt> and <tt>glutHideOverlay</tt> functions are not impl
|
||||
|
||||
<h2>10.1 glutCreateMenu</h2>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<h2>10.2 glutDestroyMenu</h2>
|
||||
|
||||
<h2>10.3 glutGetMenu, glutSetMenu</h2>
|
||||
@ -985,10 +1023,14 @@ stroke font, or an unknown font.
|
||||
|
||||
<h2>10.11 glutMenuDestroyFunc</h2>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<h1>11. <a name="GlobalCallback"></a>Global Callback Registration Functions</h1>
|
||||
|
||||
<h2>11.1 glutTimerFunc</h2>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<h2>11.2 glutIdleFunc</h2>
|
||||
|
||||
<p>
|
||||
@ -998,11 +1040,11 @@ Freeglut</i> calls the idle callback when there are no inputs from the user.
|
||||
|
||||
<p><b>Usage</b></p>
|
||||
|
||||
<p><tt>void glutIdleFunc ( void (*func)
|
||||
( void ) );</tt> </p>
|
||||
<p><tt>void glutIdleFunc ( void (*func ) ( void ) );</tt> </p>
|
||||
|
||||
<p><tt>func</tt>The new
|
||||
global idle callback function </p>
|
||||
<p><tt>func</tt> The new global idle callback function</p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
@ -1042,16 +1084,24 @@ the idle callback. </p>
|
||||
|
||||
<h2>11.3 glutMenuStatusFunc</h2>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<h2>11.4 glutMenuStateFunc</h2>
|
||||
|
||||
<h1>12. <a name="WindowCallback"></a>Window-Specific Callback Registration Functions</h1>
|
||||
|
||||
<h2>12.1 glutDisplayFunc</h2>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<h2>12.2 glutOverlayDisplayFunc</h2>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<h2>12.3 glutReshapeFunc</h2>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<h2>12.4 glutPositionFunc</h2>
|
||||
|
||||
<p>
|
||||
@ -1065,6 +1115,8 @@ repositioned/moved programatically or by the user.
|
||||
<p><tt>void glutPositionFunc ( void
|
||||
(* func)( int x, int y) );</tt></p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>When <i>FreeGLUT</i> calls this callback, it provides the new
|
||||
@ -1094,6 +1146,8 @@ about to be destroyed.
|
||||
<p><tt>func</tt> The window's new closure callback function <br/>
|
||||
</p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>
|
||||
@ -1121,6 +1175,8 @@ alias to <tt>glutCloseFunc</tt>.
|
||||
|
||||
<h2>12.6 glutKeyboardFunc</h2>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<h2>12.7 glutSpecialFunc</h2>
|
||||
|
||||
<p>
|
||||
@ -1145,6 +1201,8 @@ to the window at the time the key is pressed <br/>
|
||||
</tt>The y-coordinate of the mouse relative
|
||||
to the window at the time the key is pressed </p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>
|
||||
@ -1200,6 +1258,8 @@ to the window at the time the key is released <br/>
|
||||
</tt>The y-coordinate of the mouse relative
|
||||
to the window at the time the key is released </p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>
|
||||
@ -1252,6 +1312,8 @@ to the window at the time the key is released <br/>
|
||||
</tt>The y-coordinate of the mouse relative
|
||||
to the window at the time the key is released </p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>
|
||||
@ -1289,8 +1351,12 @@ have them fixed.
|
||||
|
||||
<h2>12.10 glutMotionFunc, glutPassiveMotionFunc</h2>
|
||||
|
||||
<p>Both functions have user-data callback functions.</p>
|
||||
|
||||
<h2>12.11 glutMouseFunc</h2>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<h2>12.12 glutMouseWheelFunc</h2>
|
||||
|
||||
<p>
|
||||
@ -1304,6 +1370,8 @@ spins the mouse wheel.
|
||||
<p><tt>void glutMouseWheelFunc ( void( *callback )( int wheel, int
|
||||
direction, int x, int y ));</tt></p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>If the mouse wheel is spun over your (sub)window, <i>FreeGLUT</i>
|
||||
@ -1320,8 +1388,12 @@ as mouse buttons.
|
||||
|
||||
<h2>12.13 glutEntryFunc</h2>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<h2>12.14 glutJoystickFunc</h2>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<h2>12.15 glutSpaceballMotionFunc</h2>
|
||||
|
||||
<p>
|
||||
@ -1336,6 +1408,8 @@ provided so that GLUT-based programs can compile and link against
|
||||
<p><tt>void glutSpaceballMotionFunc ( void
|
||||
(* callback)( int x, int y, int z )</tt><tt> );</tt></p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>TODO</p>
|
||||
@ -1354,6 +1428,8 @@ provided so that GLUT-based programs can compile and link against
|
||||
<p><tt>void glutSpaceballRotateFunc ( void
|
||||
(* callback)( int x, int y, int z )</tt><tt> );</tt></p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>TODO</p>
|
||||
@ -1372,6 +1448,8 @@ provided so that GLUT-based programs can compile and link against
|
||||
<p><tt>void glutSpaceballButtonFunc ( void
|
||||
(* callback)( int button, int updown )</tt><tt> );</tt></p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>TODO</p>
|
||||
@ -1388,6 +1466,8 @@ The <tt>glutDialsFunc</tt> function sets the global dials&buttons box callback.
|
||||
<tt>void glutButtonBoxFunc ( void (* callback)( int button, int updown ) );</tt>
|
||||
</p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>
|
||||
@ -1412,6 +1492,8 @@ The <tt>glutDialsFunc</tt> function sets the global dials&buttons box callback.
|
||||
<p><tt>void glutDialsFunc ( void (* callback)(
|
||||
int dial, int value )</tt><tt> );</tt></p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>
|
||||
@ -1439,6 +1521,8 @@ that a call to the function will not produce an error..
|
||||
<tt>void glutTabletMotionFunc ( void (* callback)( int x, int y ) );</tt>
|
||||
</p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>The <tt>glutTabletMotionFunc</tt> function
|
||||
@ -1461,6 +1545,8 @@ that a call to the function will not produce an error..
|
||||
<p><tt>void glutTabletButtonFunc ( void
|
||||
(* callback)( int button, int updown, int x, int y )</tt><tt> );</tt></p>
|
||||
|
||||
<p>Has user-data callback function.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>
|
||||
@ -1487,6 +1573,8 @@ these callbacks when the visibility status of a window changes.
|
||||
<br><tt>void glutWindowStatusFunc ( void( *callback )( int state ));</tt>
|
||||
</p>
|
||||
|
||||
<p>Both functions have user-data callback functions.</p>
|
||||
|
||||
<p><b>Description</b></p>
|
||||
|
||||
<p>
|
||||
@ -2671,6 +2759,8 @@ Currently, under windows, the first (oldest) touch point also controls
|
||||
the mouse cursor, which triggers the non-multi callbacks as
|
||||
usual.<br />
|
||||
|
||||
All these functions have user-data callback functions.
|
||||
|
||||
<br />
|
||||
|
||||
Limitation: currently on the cursor id is provided. It may be
|
||||
@ -2699,9 +2789,11 @@ whether/how to implement it.</p>
|
||||
|
||||
<ul>
|
||||
<li><code>glutInitContextFunc ← void</code> : called when the context
|
||||
is initialized or re-initialized (e.g. after a pause)</li>
|
||||
is initialized or re-initialized (e.g. after a pause). Has user-data callback
|
||||
function.</li>
|
||||
<li><code>glutAppStatusFunc ← event</code> : 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:
|
||||
<ul>
|
||||
<li>application goes on a pause (or a stop) → GLUT_APPSTATUS_PAUSE</li>
|
||||
|
||||
Reference in New Issue
Block a user