Mercurial > sdl-ios-xcode
comparison include/SDL_timer.h @ 3407:d3baf5ac4e37
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 } |