include/SDL_timer.h
changeset 3407 d3baf5ac4e37
parent 2859 99210400e8b9
child 3697 f7b03b6838cb
     1.1 --- a/include/SDL_timer.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL_timer.h	Mon Oct 19 13:31:58 2009 +0000
     1.3 @@ -24,9 +24,9 @@
     1.4  #define _SDL_timer_h
     1.5  
     1.6  /**
     1.7 - * \file SDL_timer.h
     1.8 - *
     1.9 - * Header for the SDL time management routines
    1.10 + *  \file SDL_timer.h
    1.11 + *  
    1.12 + *  Header for the SDL time management routines.
    1.13   */
    1.14  
    1.15  #include "SDL_stdinc.h"
    1.16 @@ -40,81 +40,106 @@
    1.17  /* *INDENT-ON* */
    1.18  #endif
    1.19  
    1.20 -/* This is the OS scheduler timeslice, in milliseconds */
    1.21 +/**
    1.22 + *  This is the OS scheduler timeslice, in milliseconds.
    1.23 + */
    1.24  #define SDL_TIMESLICE		10
    1.25  
    1.26 -/* This is the maximum resolution of the SDL timer on all platforms */
    1.27 -#define TIMER_RESOLUTION	10      /* Experimentally determined */
    1.28 +/**
    1.29 + *  This is the maximum resolution of the SDL timer on all platforms.
    1.30 + */
    1.31 +#define TIMER_RESOLUTION	10      /**< Experimentally determined */
    1.32  
    1.33 -/* Get the number of milliseconds since the SDL library initialization.
    1.34 - * Note that this value wraps if the program runs for more than ~49 days.
    1.35 +/**
    1.36 + *  Get the number of milliseconds since the SDL library initialization.
    1.37 + *  
    1.38 + *  Note that this value wraps if the program runs for more than ~49 days.
    1.39   */
    1.40  extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
    1.41  
    1.42 -/* Wait a specified number of milliseconds before returning */
    1.43 +/**
    1.44 + *  Wait a specified number of milliseconds before returning.
    1.45 + */
    1.46  extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
    1.47  
    1.48 -/* Function prototype for the timer callback function */
    1.49 +/**
    1.50 + *  Function prototype for the timer callback function.
    1.51 + */
    1.52  typedef Uint32(SDLCALL * SDL_TimerCallback) (Uint32 interval);
    1.53  
    1.54 -/* Set a callback to run after the specified number of milliseconds has
    1.55 - * elapsed. The callback function is passed the current timer interval
    1.56 - * and returns the next timer interval.  If the returned value is the 
    1.57 - * same as the one passed in, the periodic alarm continues, otherwise a
    1.58 - * new alarm is scheduled.  If the callback returns 0, the periodic alarm
    1.59 - * is cancelled.
    1.60 - *
    1.61 - * To cancel a currently running timer, call SDL_SetTimer(0, NULL);
    1.62 - *
    1.63 - * The timer callback function may run in a different thread than your
    1.64 - * main code, and so shouldn't call any functions from within itself.
    1.65 - *
    1.66 - * The maximum resolution of this timer is 10 ms, which means that if
    1.67 - * you request a 16 ms timer, your callback will run approximately 20 ms
    1.68 - * later on an unloaded system.  If you wanted to set a flag signaling
    1.69 - * a frame update at 30 frames per second (every 33 ms), you might set a 
    1.70 - * timer for 30 ms:
    1.71 - *   SDL_SetTimer((33/10)*10, flag_update);
    1.72 - *
    1.73 - * If you use this function, you need to pass SDL_INIT_TIMER to SDL_Init().
    1.74 - *
    1.75 - * Under UNIX, you should not use raise or use SIGALRM and this function
    1.76 - * in the same program, as it is implemented using setitimer().  You also
    1.77 - * should not use this function in multi-threaded applications as signals
    1.78 - * to multi-threaded apps have undefined behavior in some implementations.
    1.79 - *
    1.80 - * This function returns 0 if successful, or -1 if there was an error.
    1.81 +/**
    1.82 + *  Set a callback to run after the specified number of milliseconds has
    1.83 + *  elapsed. The callback function is passed the current timer interval
    1.84 + *  and returns the next timer interval.  If the returned value is the 
    1.85 + *  same as the one passed in, the periodic alarm continues, otherwise a
    1.86 + *  new alarm is scheduled.  If the callback returns 0, the periodic alarm
    1.87 + *  is cancelled.
    1.88 + *  
    1.89 + *  To cancel a currently running timer, call 
    1.90 + *  \code SDL_SetTimer(0, NULL); \endcode
    1.91 + *  
    1.92 + *  The timer callback function may run in a different thread than your
    1.93 + *  main code, and so shouldn't call any functions from within itself.
    1.94 + *  
    1.95 + *  The maximum resolution of this timer is 10 ms, which means that if
    1.96 + *  you request a 16 ms timer, your callback will run approximately 20 ms
    1.97 + *  later on an unloaded system.  If you wanted to set a flag signaling
    1.98 + *  a frame update at 30 frames per second (every 33 ms), you might set a 
    1.99 + *  timer for 30 ms:
   1.100 + *  \code
   1.101 + *    SDL_SetTimer((33/10)*10, flag_update);
   1.102 + *  \endcode
   1.103 + *  
   1.104 + *  If you use this function, you need to pass ::SDL_INIT_TIMER to SDL_Init().
   1.105 + *  
   1.106 + *  Under UNIX, you should not use raise or use SIGALRM and this function
   1.107 + *  in the same program, as it is implemented using setitimer().  You also
   1.108 + *  should not use this function in multi-threaded applications as signals
   1.109 + *  to multi-threaded apps have undefined behavior in some implementations.
   1.110 + *  
   1.111 + *  \return 0 if successful, or -1 if there was an error.
   1.112   */
   1.113  extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval,
   1.114                                           SDL_TimerCallback callback);
   1.115  
   1.116 -/* New timer API, supports multiple timers
   1.117 - * Written by Stephane Peter <megastep@lokigames.com>
   1.118 +/**
   1.119 + *  \name Peter timers
   1.120 + *  New timer API, supports multiple timers
   1.121 + *  Written by Stephane Peter <megastep@lokigames.com>
   1.122   */
   1.123 +/*@{*/
   1.124  
   1.125 -/* Function prototype for the new timer callback function.
   1.126 - * The callback function is passed the current timer interval and returns
   1.127 - * the next timer interval.  If the returned value is the same as the one
   1.128 - * passed in, the periodic alarm continues, otherwise a new alarm is
   1.129 - * scheduled.  If the callback returns 0, the periodic alarm is cancelled.
   1.130 +/**
   1.131 + *  Function prototype for the new timer callback function.
   1.132 + *  
   1.133 + *  The callback function is passed the current timer interval and returns
   1.134 + *  the next timer interval.  If the returned value is the same as the one
   1.135 + *  passed in, the periodic alarm continues, otherwise a new alarm is
   1.136 + *  scheduled.  If the callback returns 0, the periodic alarm is cancelled.
   1.137   */
   1.138  typedef Uint32(SDLCALL * SDL_NewTimerCallback) (Uint32 interval, void *param);
   1.139  
   1.140 -/* Definition of the timer ID type */
   1.141 +/**
   1.142 + *  Definition of the timer ID type.
   1.143 + */
   1.144  typedef struct _SDL_TimerID *SDL_TimerID;
   1.145  
   1.146 -/* Add a new timer to the pool of timers already running.
   1.147 -   Returns a timer ID, or NULL when an error occurs.
   1.148 +/**
   1.149 + *  Add a new timer to the pool of timers already running.
   1.150 + *  \return A timer ID, or NULL when an error occurs.
   1.151   */
   1.152  extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval,
   1.153                                                   SDL_NewTimerCallback
   1.154                                                   callback, void *param);
   1.155  
   1.156 -/* Remove one of the multiple timers knowing its ID.
   1.157 - * Returns a boolean value indicating success.
   1.158 +/**
   1.159 + *  Remove one of the multiple timers knowing its ID.
   1.160 + *  \return A boolean value indicating success or failure.
   1.161   */
   1.162  extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t);
   1.163  
   1.164 +/*@}*//*Peter timers*/
   1.165 +
   1.166  /* Ends C function definitions when using C++ */
   1.167  #ifdef __cplusplus
   1.168  /* *INDENT-OFF* */