Updated documentation to mention and discuss user-data callbacks.

git-svn-id: https://svn.code.sf.net/p/freeglut/code/trunk@1819 7f0cb862-5218-0410-a997-914c9d46530a

freeglut/web-src/docs/api.php

@@ -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&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)
+<p><tt>void glutIdleFunc ( void (*func ) ( void ) );</tt> </p>
-( void ) );</tt> </p>
 
-<p><tt>func</tt>The new
+<p><tt>func</tt> The new global idle callback function</p>
-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>
@@ -1337,6 +1409,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></p>
 
+<p>Has user-data callback function.</p>
+
 <p><b>Description</b></p>
 
 <p>The <i>x</i>, <i>y</i>, and <i>z</i> arguments indicate the amount of translation in integer along x, y, and z axis respectively.</p>
@@ -1357,6 +1431,8 @@ provided so that GLUT-based programs can compile and link against
 
 <p><tt>void glutSpaceballRotateFunc ( void (* callback)( int rx, int ry, int rz ) );</tt></p>
 
+<p>Has user-data callback function.</p>
+
 <p><b>Description</b></p>
 
 <p>The <i>rx</i>, <i>ry</i>, and <i>rz</i> arguments indicate the amount of rotation in integer with respect to x, y, and z axis respectively.</p>
@@ -1379,6 +1455,8 @@ The <tt>glutSpaceballButtonFunc</tt> function sets the window's Spaceball button
 <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>The <i>button</i> argument may take one of the following defined
@@ -1418,6 +1496,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>
@@ -1442,6 +1522,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>
@@ -1469,6 +1551,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
@@ -1491,6 +1575,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>
@@ -1517,6 +1603,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>
@@ -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.<br />
 
+All these functions have user-data callback functions.
+
 <br />
 
 Limitation: currently on the cursor id is provided.  It may be
@@ -2729,9 +2819,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>