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
This commit is contained in:
dcnieho 2017-06-30 23:22:12 +00:00
parent 9f0eaf1a92
commit 1925fca030

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> when you created it.</ul>
</p> </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.3 Terminology</h2>
<h2>3.4 Differences from GLUT 3.7</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/> <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> <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><b>Description</b></p>
<p> <p>
The users callback is passed a format string and a variable argument 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> <h2>10.1 glutCreateMenu</h2>
<p>Has user-data callback function.</p>
<h2>10.2 glutDestroyMenu</h2> <h2>10.2 glutDestroyMenu</h2>
<h2>10.3 glutGetMenu, glutSetMenu</h2> <h2>10.3 glutGetMenu, glutSetMenu</h2>
@ -985,10 +1023,14 @@ stroke font, or an unknown font.
<h2>10.11 glutMenuDestroyFunc</h2> <h2>10.11 glutMenuDestroyFunc</h2>
<p>Has user-data callback function.</p>
<h1>11. <a name="GlobalCallback"></a>Global Callback Registration Functions</h1> <h1>11. <a name="GlobalCallback"></a>Global Callback Registration Functions</h1>
<h2>11.1 glutTimerFunc</h2> <h2>11.1 glutTimerFunc</h2>
<p>Has user-data callback function.</p>
<h2>11.2 glutIdleFunc</h2> <h2>11.2 glutIdleFunc</h2>
<p> <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><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> <p><b>Description</b></p>
@ -1042,16 +1084,24 @@ the idle callback. </p>
<h2>11.3 glutMenuStatusFunc</h2> <h2>11.3 glutMenuStatusFunc</h2>
<p>Has user-data callback function.</p>
<h2>11.4 glutMenuStateFunc</h2> <h2>11.4 glutMenuStateFunc</h2>
<h1>12. <a name="WindowCallback"></a>Window-Specific Callback Registration Functions</h1> <h1>12. <a name="WindowCallback"></a>Window-Specific Callback Registration Functions</h1>
<h2>12.1 glutDisplayFunc</h2> <h2>12.1 glutDisplayFunc</h2>
<p>Has user-data callback function.</p>
<h2>12.2 glutOverlayDisplayFunc</h2> <h2>12.2 glutOverlayDisplayFunc</h2>
<p>Has user-data callback function.</p>
<h2>12.3 glutReshapeFunc</h2> <h2>12.3 glutReshapeFunc</h2>
<p>Has user-data callback function.</p>
<h2>12.4 glutPositionFunc</h2> <h2>12.4 glutPositionFunc</h2>
<p> <p>
@ -1065,6 +1115,8 @@ repositioned/moved programatically or by the user.
<p><tt>void glutPositionFunc ( void <p><tt>void glutPositionFunc ( void
(* func)( int x, int y) );</tt></p> (* func)( int x, int y) );</tt></p>
<p>Has user-data callback function.</p>
<p><b>Description</b></p> <p><b>Description</b></p>
<p>When <i>freeglut</i> calls this callback, it provides the new <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><tt>func</tt> The window's new closure callback function <br/>
</p> </p>
<p>Has user-data callback function.</p>
<p><b>Description</b></p> <p><b>Description</b></p>
<p> <p>
@ -1121,6 +1175,8 @@ alias to <tt>glutCloseFunc</tt>.
<h2>12.6 glutKeyboardFunc</h2> <h2>12.6 glutKeyboardFunc</h2>
<p>Has user-data callback function.</p>
<h2>12.7 glutSpecialFunc</h2> <h2>12.7 glutSpecialFunc</h2>
<p> <p>
@ -1145,6 +1201,8 @@ to the window at the time the key is pressed <br/>
</tt>The y-coordinate of the mouse relative </tt>The y-coordinate of the mouse relative
to the window at the time the key is pressed </p> to the window at the time the key is pressed </p>
<p>Has user-data callback function.</p>
<p><b>Description</b></p> <p><b>Description</b></p>
<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 </tt>The y-coordinate of the mouse relative
to the window at the time the key is released </p> to the window at the time the key is released </p>
<p>Has user-data callback function.</p>
<p><b>Description</b></p> <p><b>Description</b></p>
<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 </tt>The y-coordinate of the mouse relative
to the window at the time the key is released </p> to the window at the time the key is released </p>
<p>Has user-data callback function.</p>
<p><b>Description</b></p> <p><b>Description</b></p>
<p> <p>
@ -1289,8 +1351,12 @@ have them fixed.
<h2>12.10 glutMotionFunc, glutPassiveMotionFunc</h2> <h2>12.10 glutMotionFunc, glutPassiveMotionFunc</h2>
<p>Both functions have user-data callback functions.</p>
<h2>12.11 glutMouseFunc</h2> <h2>12.11 glutMouseFunc</h2>
<p>Has user-data callback function.</p>
<h2>12.12 glutMouseWheelFunc</h2> <h2>12.12 glutMouseWheelFunc</h2>
<p> <p>
@ -1304,6 +1370,8 @@ spins the mouse wheel.
<p><tt>void glutMouseWheelFunc ( void( *callback )( int wheel, int <p><tt>void glutMouseWheelFunc ( void( *callback )( int wheel, int
direction, int x, int y ));</tt></p> direction, int x, int y ));</tt></p>
<p>Has user-data callback function.</p>
<p><b>Description</b></p> <p><b>Description</b></p>
<p>If the mouse wheel is spun over your (sub)window, <i>freeglut</i> <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> <h2>12.13 glutEntryFunc</h2>
<p>Has user-data callback function.</p>
<h2>12.14 glutJoystickFunc</h2> <h2>12.14 glutJoystickFunc</h2>
<p>Has user-data callback function.</p>
<h2>12.15 glutSpaceballMotionFunc</h2> <h2>12.15 glutSpaceballMotionFunc</h2>
<p> <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><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><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> <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><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><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> <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 <p><tt>void glutSpaceballButtonFunc ( void
(* callback)( int button, int updown )</tt><tt> );</tt></p> (* callback)( int button, int updown )</tt><tt> );</tt></p>
<p>Has user-data callback function.</p>
<p><b>Description</b></p> <p><b>Description</b></p>
<p>The <i>button</i> argument may take one of the following defined <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> <tt>void glutButtonBoxFunc ( void (* callback)( int button, int updown ) );</tt>
</p> </p>
<p>Has user-data callback function.</p>
<p><b>Description</b></p> <p><b>Description</b></p>
<p> <p>
@ -1442,6 +1522,8 @@ The <tt>glutDialsFunc</tt> function sets the global dials&buttons box callback.
<p><tt>void glutDialsFunc ( void (* callback)( <p><tt>void glutDialsFunc ( void (* callback)(
int dial, int value )</tt><tt> );</tt></p> int dial, int value )</tt><tt> );</tt></p>
<p>Has user-data callback function.</p>
<p><b>Description</b></p> <p><b>Description</b></p>
<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> <tt>void glutTabletMotionFunc ( void (* callback)( int x, int y ) );</tt>
</p> </p>
<p>Has user-data callback function.</p>
<p><b>Description</b></p> <p><b>Description</b></p>
<p>The <tt>glutTabletMotionFunc</tt> function <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 <p><tt>void glutTabletButtonFunc ( void
(* callback)( int button, int updown, int x, int y )</tt><tt> );</tt></p> (* 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><b>Description</b></p>
<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> <br><tt>void glutWindowStatusFunc ( void( *callback )( int state ));</tt>
</p> </p>
<p>Both functions have user-data callback functions.</p>
<p><b>Description</b></p> <p><b>Description</b></p>
<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 the mouse cursor, which triggers the non-multi callbacks as
usual.<br /> usual.<br />
All these functions have user-data callback functions.
<br /> <br />
Limitation: currently on the cursor id is provided. It may be Limitation: currently on the cursor id is provided. It may be
@ -2729,9 +2819,11 @@ whether/how to implement it.</p>
<ul> <ul>
<li><code>glutInitContextFunc &larr; void</code> : called when the context <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 <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: Possible states:
<ul> <ul>
<li>application goes on a pause (or a stop) &rarr; GLUT_APPSTATUS_PAUSE</li> <li>application goes on a pause (or a stop) &rarr; GLUT_APPSTATUS_PAUSE</li>