Updated documentation to mention and discuss user-data callbacks.

This commit is contained in:
Rcmaniac25 2016-02-04 21:14:40 -05:00
parent 666b80843a
commit 682d4d096a

View File

@ -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&nbsp;&nbsp;&nbsp;( void (* callback)( const char *fmt, va_list ap) );</tt><br/>
<tt>void glutInitWarningFunc&nbsp;( 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 &larr; 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 &larr; 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) &rarr; GLUT_APPSTATUS_PAUSE</li>