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
parent
9f0eaf1a92
commit
1925fca030
@ -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>
|
||||
@ -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 ← 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