Mercurial > sdl-ios-xcode

comparison include/SDL_timer.h @ 3407:d3baf5ac4e37

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Partial fix for bug #859 Header file update from Ken for improved doxygen output
author Sam Lantinga <slouken@libsdl.org>
date Mon, 19 Oct 2009 13:31:58 +0000
parents 99210400e8b9
children f7b03b6838cb
comparison
equal deleted inserted replaced
3406:8ae607392409 3407:d3baf5ac4e37
22 22
23 #ifndef _SDL_timer_h 23 #ifndef _SDL_timer_h
24 #define _SDL_timer_h 24 #define _SDL_timer_h
25 25
26 /** 26 /**
27 * \file SDL_timer.h 27 * \file SDL_timer.h
28 * 28 *
29 * Header for the SDL time management routines 29 * Header for the SDL time management routines.
30 */ 30 */
31 31
32 #include "SDL_stdinc.h" 32 #include "SDL_stdinc.h"
33 #include "SDL_error.h" 33 #include "SDL_error.h"
34 34
38 /* *INDENT-OFF* */ 38 /* *INDENT-OFF* */
39 extern "C" { 39 extern "C" {
40 /* *INDENT-ON* */ 40 /* *INDENT-ON* */
41 #endif 41 #endif
42 42
43 /* This is the OS scheduler timeslice, in milliseconds */ 43 /**
44 * This is the OS scheduler timeslice, in milliseconds.
45 */
44 #define SDL_TIMESLICE 10 46 #define SDL_TIMESLICE 10
45 47
46 /* This is the maximum resolution of the SDL timer on all platforms */ 48 /**
47 #define TIMER_RESOLUTION 10 /* Experimentally determined */ 49 * This is the maximum resolution of the SDL timer on all platforms.
50 */
51 #define TIMER_RESOLUTION 10 /**< Experimentally determined */
48 52
49 /* Get the number of milliseconds since the SDL library initialization. 53 /**
50 * Note that this value wraps if the program runs for more than ~49 days. 54 * Get the number of milliseconds since the SDL library initialization.
55 *
56 * Note that this value wraps if the program runs for more than ~49 days.
51 */ 57 */
52 extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void); 58 extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
53 59
54 /* Wait a specified number of milliseconds before returning */ 60 /**
61 * Wait a specified number of milliseconds before returning.
62 */
55 extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); 63 extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
56 64
57 /* Function prototype for the timer callback function */ 65 /**
66 * Function prototype for the timer callback function.
67 */
58 typedef Uint32(SDLCALL * SDL_TimerCallback) (Uint32 interval); 68 typedef Uint32(SDLCALL * SDL_TimerCallback) (Uint32 interval);
59 69
60 /* Set a callback to run after the specified number of milliseconds has 70 /**
61 * elapsed. The callback function is passed the current timer interval 71 * Set a callback to run after the specified number of milliseconds has
62 * and returns the next timer interval. If the returned value is the 72 * elapsed. The callback function is passed the current timer interval
63 * same as the one passed in, the periodic alarm continues, otherwise a 73 * and returns the next timer interval. If the returned value is the
64 * new alarm is scheduled. If the callback returns 0, the periodic alarm 74 * same as the one passed in, the periodic alarm continues, otherwise a
65 * is cancelled. 75 * new alarm is scheduled. If the callback returns 0, the periodic alarm
66 * 76 * is cancelled.
67 * To cancel a currently running timer, call SDL_SetTimer(0, NULL); 77 *
68 * 78 * To cancel a currently running timer, call
69 * The timer callback function may run in a different thread than your 79 * \code SDL_SetTimer(0, NULL); \endcode
70 * main code, and so shouldn't call any functions from within itself. 80 *
71 * 81 * The timer callback function may run in a different thread than your
72 * The maximum resolution of this timer is 10 ms, which means that if 82 * main code, and so shouldn't call any functions from within itself.
73 * you request a 16 ms timer, your callback will run approximately 20 ms 83 *
74 * later on an unloaded system. If you wanted to set a flag signaling 84 * The maximum resolution of this timer is 10 ms, which means that if
75 * a frame update at 30 frames per second (every 33 ms), you might set a 85 * you request a 16 ms timer, your callback will run approximately 20 ms
76 * timer for 30 ms: 86 * later on an unloaded system. If you wanted to set a flag signaling
77 * SDL_SetTimer((33/10)*10, flag_update); 87 * a frame update at 30 frames per second (every 33 ms), you might set a
78 * 88 * timer for 30 ms:
79 * If you use this function, you need to pass SDL_INIT_TIMER to SDL_Init(). 89 * \code
80 * 90 * SDL_SetTimer((33/10)*10, flag_update);
81 * Under UNIX, you should not use raise or use SIGALRM and this function 91 * \endcode
82 * in the same program, as it is implemented using setitimer(). You also 92 *
83 * should not use this function in multi-threaded applications as signals 93 * If you use this function, you need to pass ::SDL_INIT_TIMER to SDL_Init().
84 * to multi-threaded apps have undefined behavior in some implementations. 94 *
85 * 95 * Under UNIX, you should not use raise or use SIGALRM and this function
86 * This function returns 0 if successful, or -1 if there was an error. 96 * in the same program, as it is implemented using setitimer(). You also
97 * should not use this function in multi-threaded applications as signals
98 * to multi-threaded apps have undefined behavior in some implementations.
99 *
100 * \return 0 if successful, or -1 if there was an error.
87 */ 101 */
88 extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval, 102 extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval,
89 SDL_TimerCallback callback); 103 SDL_TimerCallback callback);
90 104
91 /* New timer API, supports multiple timers 105 /**
92 * Written by Stephane Peter <megastep@lokigames.com> 106 * \name Peter timers
107 * New timer API, supports multiple timers
108 * Written by Stephane Peter <megastep@lokigames.com>
93 */ 109 */
110 /*@{*/
94 111
95 /* Function prototype for the new timer callback function. 112 /**
96 * The callback function is passed the current timer interval and returns 113 * Function prototype for the new timer callback function.
97 * the next timer interval. If the returned value is the same as the one 114 *
98 * passed in, the periodic alarm continues, otherwise a new alarm is 115 * The callback function is passed the current timer interval and returns
99 * scheduled. If the callback returns 0, the periodic alarm is cancelled. 116 * the next timer interval. If the returned value is the same as the one
117 * passed in, the periodic alarm continues, otherwise a new alarm is
118 * scheduled. If the callback returns 0, the periodic alarm is cancelled.
100 */ 119 */
101 typedef Uint32(SDLCALL * SDL_NewTimerCallback) (Uint32 interval, void *param); 120 typedef Uint32(SDLCALL * SDL_NewTimerCallback) (Uint32 interval, void *param);
102 121
103 /* Definition of the timer ID type */ 122 /**
123 * Definition of the timer ID type.
124 */
104 typedef struct _SDL_TimerID *SDL_TimerID; 125 typedef struct _SDL_TimerID *SDL_TimerID;
105 126
106 /* Add a new timer to the pool of timers already running. 127 /**
107 Returns a timer ID, or NULL when an error occurs. 128 * Add a new timer to the pool of timers already running.
129 * \return A timer ID, or NULL when an error occurs.
108 */ 130 */
109 extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, 131 extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval,
110 SDL_NewTimerCallback 132 SDL_NewTimerCallback
111 callback, void *param); 133 callback, void *param);
112 134
113 /* Remove one of the multiple timers knowing its ID. 135 /**
114 * Returns a boolean value indicating success. 136 * Remove one of the multiple timers knowing its ID.
137 * \return A boolean value indicating success or failure.
115 */ 138 */
116 extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t); 139 extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t);
140
141 /*@}*//*Peter timers*/
117 142
118 /* Ends C function definitions when using C++ */ 143 /* Ends C function definitions when using C++ */
119 #ifdef __cplusplus 144 #ifdef __cplusplus
120 /* *INDENT-OFF* */ 145 /* *INDENT-OFF* */
121 } 146 }