include/SDL_timer.h
changeset 5111 481dabb098ef
parent 3697 f7b03b6838cb
child 5262 b530ef003506
     1.1 --- a/include/SDL_timer.h	Thu Jan 27 10:40:17 2011 -0800
     1.2 +++ b/include/SDL_timer.h	Thu Jan 27 14:45:06 2011 -0800
     1.3 @@ -41,104 +41,50 @@
     1.4  #endif
     1.5  
     1.6  /**
     1.7 - *  This is the OS scheduler timeslice, in milliseconds.
     1.8 - */
     1.9 -#define SDL_TIMESLICE		10
    1.10 -
    1.11 -/**
    1.12 - *  This is the maximum resolution of the SDL timer on all platforms.
    1.13 - */
    1.14 -#define TIMER_RESOLUTION	10      /**< Experimentally determined */
    1.15 -
    1.16 -/**
    1.17 - *  Get the number of milliseconds since the SDL library initialization.
    1.18 + * \brief Get the number of milliseconds since the SDL library initialization.
    1.19   *  
    1.20 - *  Note that this value wraps if the program runs for more than ~49 days.
    1.21 + * \note This value wraps if the program runs for more than ~49 days.
    1.22   */
    1.23  extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
    1.24  
    1.25  /**
    1.26 - *  Wait a specified number of milliseconds before returning.
    1.27 + * \brief Wait a specified number of milliseconds before returning.
    1.28   */
    1.29  extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
    1.30  
    1.31  /**
    1.32   *  Function prototype for the timer callback function.
    1.33 - */
    1.34 -typedef Uint32(SDLCALL * SDL_TimerCallback) (Uint32 interval);
    1.35 -
    1.36 -/**
    1.37 - *  Set a callback to run after the specified number of milliseconds has
    1.38 - *  elapsed. The callback function is passed the current timer interval
    1.39 - *  and returns the next timer interval.  If the returned value is the 
    1.40 - *  same as the one passed in, the periodic alarm continues, otherwise a
    1.41 - *  new alarm is scheduled.  If the callback returns 0, the periodic alarm
    1.42 - *  is cancelled.
    1.43 - *  
    1.44 - *  To cancel a currently running timer, call 
    1.45 - *  \code SDL_SetTimer(0, NULL); \endcode
    1.46 - *  
    1.47 - *  The timer callback function may run in a different thread than your
    1.48 - *  main code, and so shouldn't call any functions from within itself.
    1.49 - *  
    1.50 - *  The maximum resolution of this timer is 10 ms, which means that if
    1.51 - *  you request a 16 ms timer, your callback will run approximately 20 ms
    1.52 - *  later on an unloaded system.  If you wanted to set a flag signaling
    1.53 - *  a frame update at 30 frames per second (every 33 ms), you might set a 
    1.54 - *  timer for 30 ms:
    1.55 - *  \code
    1.56 - *    SDL_SetTimer((33/10)*10, flag_update);
    1.57 - *  \endcode
    1.58 - *  
    1.59 - *  If you use this function, you need to pass ::SDL_INIT_TIMER to SDL_Init().
    1.60 - *  
    1.61 - *  Under UNIX, you should not use raise or use SIGALRM and this function
    1.62 - *  in the same program, as it is implemented using setitimer().  You also
    1.63 - *  should not use this function in multi-threaded applications as signals
    1.64 - *  to multi-threaded apps have undefined behavior in some implementations.
    1.65 - *  
    1.66 - *  \return 0 if successful, or -1 if there was an error.
    1.67 - */
    1.68 -extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval,
    1.69 -                                         SDL_TimerCallback callback);
    1.70 -
    1.71 -/**
    1.72 - *  \name Peter timers
    1.73 - *  New timer API, supports multiple timers
    1.74 - *  Written by Stephane Peter <megastep@lokigames.com>
    1.75 - */
    1.76 -/*@{*/
    1.77 -
    1.78 -/**
    1.79 - *  Function prototype for the new timer callback function.
    1.80   *  
    1.81   *  The callback function is passed the current timer interval and returns
    1.82   *  the next timer interval.  If the returned value is the same as the one
    1.83   *  passed in, the periodic alarm continues, otherwise a new alarm is
    1.84   *  scheduled.  If the callback returns 0, the periodic alarm is cancelled.
    1.85   */
    1.86 -typedef Uint32(SDLCALL * SDL_NewTimerCallback) (Uint32 interval, void *param);
    1.87 +typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param);
    1.88  
    1.89  /**
    1.90 - *  Definition of the timer ID type.
    1.91 + * Definition of the timer ID type.
    1.92   */
    1.93 -typedef struct _SDL_TimerID *SDL_TimerID;
    1.94 +typedef int SDL_TimerID;
    1.95  
    1.96  /**
    1.97 - *  Add a new timer to the pool of timers already running.
    1.98 - *  \return A timer ID, or NULL when an error occurs.
    1.99 + * \brief Add a new timer to the pool of timers already running.
   1.100 + *
   1.101 + * \return A timer ID, or NULL when an error occurs.
   1.102   */
   1.103  extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval,
   1.104 -                                                 SDL_NewTimerCallback
   1.105 -                                                 callback, void *param);
   1.106 +                                                 SDL_TimerCallback callback,
   1.107 +                                                 void *param);
   1.108  
   1.109  /**
   1.110 - *  Remove one of the multiple timers knowing its ID.
   1.111 - *  \return A boolean value indicating success or failure.
   1.112 + * \brief Remove a timer knowing its ID.
   1.113 + *
   1.114 + * \return A boolean value indicating success or failure.
   1.115 + *
   1.116 + * \warning It is not safe to remove a timer multiple times.
   1.117   */
   1.118  extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t);
   1.119  
   1.120 -/*@}*//*Peter timers*/
   1.121  
   1.122  /* Ends C function definitions when using C++ */
   1.123  #ifdef __cplusplus