|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
|
|
|
4
|
|
|
5 This software is provided 'as-is', without any express or implied
|
|
|
6 warranty. In no event will the authors be held liable for any damages
|
|
|
7 arising from the use of this software.
|
|
|
8
|
|
|
9 Permission is granted to anyone to use this software for any purpose,
|
|
|
10 including commercial applications, and to alter it and redistribute it
|
|
|
11 freely, subject to the following restrictions:
|
|
|
12
|
|
|
13 1. The origin of this software must not be misrepresented; you must not
|
|
|
14 claim that you wrote the original software. If you use this software
|
|
|
15 in a product, an acknowledgment in the product documentation would be
|
|
|
16 appreciated but is not required.
|
|
|
17 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
18 misrepresented as being the original software.
|
|
|
19 3. This notice may not be removed or altered from any source distribution.
|
|
|
20 */
|
|
|
21
|
|
|
22 #ifndef SDL_timer_h_
|
|
|
23 #define SDL_timer_h_
|
|
|
24
|
|
|
25 /**
|
|
|
26 * # CategoryTimer
|
|
|
27 *
|
|
|
28 * SDL provides time management functionality. It is useful for dealing with
|
|
|
29 * (usually) small durations of time.
|
|
|
30 *
|
|
|
31 * This is not to be confused with _calendar time_ management, which is
|
|
|
32 * provided by [CategoryTime](CategoryTime).
|
|
|
33 *
|
|
|
34 * This category covers measuring time elapsed (SDL_GetTicks(),
|
|
|
35 * SDL_GetPerformanceCounter()), putting a thread to sleep for a certain
|
|
|
36 * amount of time (SDL_Delay(), SDL_DelayNS(), SDL_DelayPrecise()), and firing
|
|
|
37 * a callback function after a certain amount of time has elapsed
|
|
|
38 * (SDL_AddTimer(), etc).
|
|
|
39 *
|
|
|
40 * There are also useful macros to convert between time units, like
|
|
|
41 * SDL_SECONDS_TO_NS() and such.
|
|
|
42 */
|
|
|
43
|
|
|
44 #include <SDL3/SDL_stdinc.h>
|
|
|
45 #include <SDL3/SDL_error.h>
|
|
|
46
|
|
|
47 #include <SDL3/SDL_begin_code.h>
|
|
|
48 /* Set up for C function definitions, even when using C++ */
|
|
|
49 #ifdef __cplusplus
|
|
|
50 extern "C" {
|
|
|
51 #endif
|
|
|
52
|
|
|
53 /* SDL time constants */
|
|
|
54
|
|
|
55 /**
|
|
|
56 * Number of milliseconds in a second.
|
|
|
57 *
|
|
|
58 * This is always 1000.
|
|
|
59 *
|
|
|
60 * \since This macro is available since SDL 3.2.0.
|
|
|
61 */
|
|
|
62 #define SDL_MS_PER_SECOND 1000
|
|
|
63
|
|
|
64 /**
|
|
|
65 * Number of microseconds in a second.
|
|
|
66 *
|
|
|
67 * This is always 1000000.
|
|
|
68 *
|
|
|
69 * \since This macro is available since SDL 3.2.0.
|
|
|
70 */
|
|
|
71 #define SDL_US_PER_SECOND 1000000
|
|
|
72
|
|
|
73 /**
|
|
|
74 * Number of nanoseconds in a second.
|
|
|
75 *
|
|
|
76 * This is always 1000000000.
|
|
|
77 *
|
|
|
78 * \since This macro is available since SDL 3.2.0.
|
|
|
79 */
|
|
|
80 #define SDL_NS_PER_SECOND 1000000000LL
|
|
|
81
|
|
|
82 /**
|
|
|
83 * Number of nanoseconds in a millisecond.
|
|
|
84 *
|
|
|
85 * This is always 1000000.
|
|
|
86 *
|
|
|
87 * \since This macro is available since SDL 3.2.0.
|
|
|
88 */
|
|
|
89 #define SDL_NS_PER_MS 1000000
|
|
|
90
|
|
|
91 /**
|
|
|
92 * Number of nanoseconds in a microsecond.
|
|
|
93 *
|
|
|
94 * This is always 1000.
|
|
|
95 *
|
|
|
96 * \since This macro is available since SDL 3.2.0.
|
|
|
97 */
|
|
|
98 #define SDL_NS_PER_US 1000
|
|
|
99
|
|
|
100 /**
|
|
|
101 * Convert seconds to nanoseconds.
|
|
|
102 *
|
|
|
103 * This only converts whole numbers, not fractional seconds.
|
|
|
104 *
|
|
|
105 * \param S the number of seconds to convert.
|
|
|
106 * \returns S, expressed in nanoseconds.
|
|
|
107 *
|
|
|
108 * \threadsafety It is safe to call this macro from any thread.
|
|
|
109 *
|
|
|
110 * \since This macro is available since SDL 3.2.0.
|
|
|
111 */
|
|
|
112 #define SDL_SECONDS_TO_NS(S) (((Uint64)(S)) * SDL_NS_PER_SECOND)
|
|
|
113
|
|
|
114 /**
|
|
|
115 * Convert nanoseconds to seconds.
|
|
|
116 *
|
|
|
117 * This performs a division, so the results can be dramatically different if
|
|
|
118 * `NS` is an integer or floating point value.
|
|
|
119 *
|
|
|
120 * \param NS the number of nanoseconds to convert.
|
|
|
121 * \returns NS, expressed in seconds.
|
|
|
122 *
|
|
|
123 * \threadsafety It is safe to call this macro from any thread.
|
|
|
124 *
|
|
|
125 * \since This macro is available since SDL 3.2.0.
|
|
|
126 */
|
|
|
127 #define SDL_NS_TO_SECONDS(NS) ((NS) / SDL_NS_PER_SECOND)
|
|
|
128
|
|
|
129 /**
|
|
|
130 * Convert milliseconds to nanoseconds.
|
|
|
131 *
|
|
|
132 * This only converts whole numbers, not fractional milliseconds.
|
|
|
133 *
|
|
|
134 * \param MS the number of milliseconds to convert.
|
|
|
135 * \returns MS, expressed in nanoseconds.
|
|
|
136 *
|
|
|
137 * \threadsafety It is safe to call this macro from any thread.
|
|
|
138 *
|
|
|
139 * \since This macro is available since SDL 3.2.0.
|
|
|
140 */
|
|
|
141 #define SDL_MS_TO_NS(MS) (((Uint64)(MS)) * SDL_NS_PER_MS)
|
|
|
142
|
|
|
143 /**
|
|
|
144 * Convert nanoseconds to milliseconds.
|
|
|
145 *
|
|
|
146 * This performs a division, so the results can be dramatically different if
|
|
|
147 * `NS` is an integer or floating point value.
|
|
|
148 *
|
|
|
149 * \param NS the number of nanoseconds to convert.
|
|
|
150 * \returns NS, expressed in milliseconds.
|
|
|
151 *
|
|
|
152 * \threadsafety It is safe to call this macro from any thread.
|
|
|
153 *
|
|
|
154 * \since This macro is available since SDL 3.2.0.
|
|
|
155 */
|
|
|
156 #define SDL_NS_TO_MS(NS) ((NS) / SDL_NS_PER_MS)
|
|
|
157
|
|
|
158 /**
|
|
|
159 * Convert microseconds to nanoseconds.
|
|
|
160 *
|
|
|
161 * This only converts whole numbers, not fractional microseconds.
|
|
|
162 *
|
|
|
163 * \param US the number of microseconds to convert.
|
|
|
164 * \returns US, expressed in nanoseconds.
|
|
|
165 *
|
|
|
166 * \threadsafety It is safe to call this macro from any thread.
|
|
|
167 *
|
|
|
168 * \since This macro is available since SDL 3.2.0.
|
|
|
169 */
|
|
|
170 #define SDL_US_TO_NS(US) (((Uint64)(US)) * SDL_NS_PER_US)
|
|
|
171
|
|
|
172 /**
|
|
|
173 * Convert nanoseconds to microseconds.
|
|
|
174 *
|
|
|
175 * This performs a division, so the results can be dramatically different if
|
|
|
176 * `NS` is an integer or floating point value.
|
|
|
177 *
|
|
|
178 * \param NS the number of nanoseconds to convert.
|
|
|
179 * \returns NS, expressed in microseconds.
|
|
|
180 *
|
|
|
181 * \threadsafety It is safe to call this macro from any thread.
|
|
|
182 *
|
|
|
183 * \since This macro is available since SDL 3.2.0.
|
|
|
184 */
|
|
|
185 #define SDL_NS_TO_US(NS) ((NS) / SDL_NS_PER_US)
|
|
|
186
|
|
|
187 /**
|
|
|
188 * Get the number of milliseconds that have elapsed since the SDL library
|
|
|
189 * initialization.
|
|
|
190 *
|
|
|
191 * \returns an unsigned 64‑bit integer that represents the number of
|
|
|
192 * milliseconds that have elapsed since the SDL library was
|
|
|
193 * initialized (typically via a call to SDL_Init).
|
|
|
194 *
|
|
|
195 * \threadsafety It is safe to call this function from any thread.
|
|
|
196 *
|
|
|
197 * \since This function is available since SDL 3.2.0.
|
|
|
198 *
|
|
|
199 * \sa SDL_GetTicksNS
|
|
|
200 */
|
|
|
201 extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void);
|
|
|
202
|
|
|
203 /**
|
|
|
204 * Get the number of nanoseconds since SDL library initialization.
|
|
|
205 *
|
|
|
206 * \returns an unsigned 64-bit value representing the number of nanoseconds
|
|
|
207 * since the SDL library initialized.
|
|
|
208 *
|
|
|
209 * \threadsafety It is safe to call this function from any thread.
|
|
|
210 *
|
|
|
211 * \since This function is available since SDL 3.2.0.
|
|
|
212 */
|
|
|
213 extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void);
|
|
|
214
|
|
|
215 /**
|
|
|
216 * Get the current value of the high resolution counter.
|
|
|
217 *
|
|
|
218 * This function is typically used for profiling.
|
|
|
219 *
|
|
|
220 * The counter values are only meaningful relative to each other. Differences
|
|
|
221 * between values can be converted to times by using
|
|
|
222 * SDL_GetPerformanceFrequency().
|
|
|
223 *
|
|
|
224 * \returns the current counter value.
|
|
|
225 *
|
|
|
226 * \threadsafety It is safe to call this function from any thread.
|
|
|
227 *
|
|
|
228 * \since This function is available since SDL 3.2.0.
|
|
|
229 *
|
|
|
230 * \sa SDL_GetPerformanceFrequency
|
|
|
231 */
|
|
|
232 extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void);
|
|
|
233
|
|
|
234 /**
|
|
|
235 * Get the count per second of the high resolution counter.
|
|
|
236 *
|
|
|
237 * \returns a platform-specific count per second.
|
|
|
238 *
|
|
|
239 * \threadsafety It is safe to call this function from any thread.
|
|
|
240 *
|
|
|
241 * \since This function is available since SDL 3.2.0.
|
|
|
242 *
|
|
|
243 * \sa SDL_GetPerformanceCounter
|
|
|
244 */
|
|
|
245 extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void);
|
|
|
246
|
|
|
247 /**
|
|
|
248 * Wait a specified number of milliseconds before returning.
|
|
|
249 *
|
|
|
250 * This function waits a specified number of milliseconds before returning. It
|
|
|
251 * waits at least the specified time, but possibly longer due to OS
|
|
|
252 * scheduling.
|
|
|
253 *
|
|
|
254 * \param ms the number of milliseconds to delay.
|
|
|
255 *
|
|
|
256 * \threadsafety It is safe to call this function from any thread.
|
|
|
257 *
|
|
|
258 * \since This function is available since SDL 3.2.0.
|
|
|
259 *
|
|
|
260 * \sa SDL_DelayNS
|
|
|
261 * \sa SDL_DelayPrecise
|
|
|
262 */
|
|
|
263 extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
|
|
|
264
|
|
|
265 /**
|
|
|
266 * Wait a specified number of nanoseconds before returning.
|
|
|
267 *
|
|
|
268 * This function waits a specified number of nanoseconds before returning. It
|
|
|
269 * waits at least the specified time, but possibly longer due to OS
|
|
|
270 * scheduling.
|
|
|
271 *
|
|
|
272 * \param ns the number of nanoseconds to delay.
|
|
|
273 *
|
|
|
274 * \threadsafety It is safe to call this function from any thread.
|
|
|
275 *
|
|
|
276 * \since This function is available since SDL 3.2.0.
|
|
|
277 *
|
|
|
278 * \sa SDL_Delay
|
|
|
279 * \sa SDL_DelayPrecise
|
|
|
280 */
|
|
|
281 extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns);
|
|
|
282
|
|
|
283 /**
|
|
|
284 * Wait a specified number of nanoseconds before returning.
|
|
|
285 *
|
|
|
286 * This function waits a specified number of nanoseconds before returning. It
|
|
|
287 * will attempt to wait as close to the requested time as possible, busy
|
|
|
288 * waiting if necessary, but could return later due to OS scheduling.
|
|
|
289 *
|
|
|
290 * \param ns the number of nanoseconds to delay.
|
|
|
291 *
|
|
|
292 * \threadsafety It is safe to call this function from any thread.
|
|
|
293 *
|
|
|
294 * \since This function is available since SDL 3.2.0.
|
|
|
295 *
|
|
|
296 * \sa SDL_Delay
|
|
|
297 * \sa SDL_DelayNS
|
|
|
298 */
|
|
|
299 extern SDL_DECLSPEC void SDLCALL SDL_DelayPrecise(Uint64 ns);
|
|
|
300
|
|
|
301 /**
|
|
|
302 * Definition of the timer ID type.
|
|
|
303 *
|
|
|
304 * \since This datatype is available since SDL 3.2.0.
|
|
|
305 */
|
|
|
306 typedef Uint32 SDL_TimerID;
|
|
|
307
|
|
|
308 /**
|
|
|
309 * Function prototype for the millisecond timer callback function.
|
|
|
310 *
|
|
|
311 * The callback function is passed the current timer interval and returns the
|
|
|
312 * next timer interval, in milliseconds. If the returned value is the same as
|
|
|
313 * the one passed in, the periodic alarm continues, otherwise a new alarm is
|
|
|
314 * scheduled. If the callback returns 0, the periodic alarm is canceled and
|
|
|
315 * will be removed.
|
|
|
316 *
|
|
|
317 * \param userdata an arbitrary pointer provided by the app through
|
|
|
318 * SDL_AddTimer, for its own use.
|
|
|
319 * \param timerID the current timer being processed.
|
|
|
320 * \param interval the current callback time interval.
|
|
|
321 * \returns the new callback time interval, or 0 to disable further runs of
|
|
|
322 * the callback.
|
|
|
323 *
|
|
|
324 * \threadsafety SDL may call this callback at any time from a background
|
|
|
325 * thread; the application is responsible for locking resources
|
|
|
326 * the callback touches that need to be protected.
|
|
|
327 *
|
|
|
328 * \since This datatype is available since SDL 3.2.0.
|
|
|
329 *
|
|
|
330 * \sa SDL_AddTimer
|
|
|
331 */
|
|
|
332 typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, Uint32 interval);
|
|
|
333
|
|
|
334 /**
|
|
|
335 * Call a callback function at a future time.
|
|
|
336 *
|
|
|
337 * The callback function is passed the current timer interval and the user
|
|
|
338 * supplied parameter from the SDL_AddTimer() call and should return the next
|
|
|
339 * timer interval. If the value returned from the callback is 0, the timer is
|
|
|
340 * canceled and will be removed.
|
|
|
341 *
|
|
|
342 * The callback is run on a separate thread, and for short timeouts can
|
|
|
343 * potentially be called before this function returns.
|
|
|
344 *
|
|
|
345 * Timers take into account the amount of time it took to execute the
|
|
|
346 * callback. For example, if the callback took 250 ms to execute and returned
|
|
|
347 * 1000 (ms), the timer would only wait another 750 ms before its next
|
|
|
348 * iteration.
|
|
|
349 *
|
|
|
350 * Timing may be inexact due to OS scheduling. Be sure to note the current
|
|
|
351 * time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your
|
|
|
352 * callback needs to adjust for variances.
|
|
|
353 *
|
|
|
354 * \param interval the timer delay, in milliseconds, passed to `callback`.
|
|
|
355 * \param callback the SDL_TimerCallback function to call when the specified
|
|
|
356 * `interval` elapses.
|
|
|
357 * \param userdata a pointer that is passed to `callback`.
|
|
|
358 * \returns a timer ID or 0 on failure; call SDL_GetError() for more
|
|
|
359 * information.
|
|
|
360 *
|
|
|
361 * \threadsafety It is safe to call this function from any thread.
|
|
|
362 *
|
|
|
363 * \since This function is available since SDL 3.2.0.
|
|
|
364 *
|
|
|
365 * \sa SDL_AddTimerNS
|
|
|
366 * \sa SDL_RemoveTimer
|
|
|
367 */
|
|
|
368 extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_TimerCallback callback, void *userdata);
|
|
|
369
|
|
|
370 /**
|
|
|
371 * Function prototype for the nanosecond timer callback function.
|
|
|
372 *
|
|
|
373 * The callback function is passed the current timer interval and returns the
|
|
|
374 * next timer interval, in nanoseconds. If the returned value is the same as
|
|
|
375 * the one passed in, the periodic alarm continues, otherwise a new alarm is
|
|
|
376 * scheduled. If the callback returns 0, the periodic alarm is canceled and
|
|
|
377 * will be removed.
|
|
|
378 *
|
|
|
379 * \param userdata an arbitrary pointer provided by the app through
|
|
|
380 * SDL_AddTimer, for its own use.
|
|
|
381 * \param timerID the current timer being processed.
|
|
|
382 * \param interval the current callback time interval.
|
|
|
383 * \returns the new callback time interval, or 0 to disable further runs of
|
|
|
384 * the callback.
|
|
|
385 *
|
|
|
386 * \threadsafety SDL may call this callback at any time from a background
|
|
|
387 * thread; the application is responsible for locking resources
|
|
|
388 * the callback touches that need to be protected.
|
|
|
389 *
|
|
|
390 * \since This datatype is available since SDL 3.2.0.
|
|
|
391 *
|
|
|
392 * \sa SDL_AddTimerNS
|
|
|
393 */
|
|
|
394 typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerID, Uint64 interval);
|
|
|
395
|
|
|
396 /**
|
|
|
397 * Call a callback function at a future time.
|
|
|
398 *
|
|
|
399 * The callback function is passed the current timer interval and the user
|
|
|
400 * supplied parameter from the SDL_AddTimerNS() call and should return the
|
|
|
401 * next timer interval. If the value returned from the callback is 0, the
|
|
|
402 * timer is canceled and will be removed.
|
|
|
403 *
|
|
|
404 * The callback is run on a separate thread, and for short timeouts can
|
|
|
405 * potentially be called before this function returns.
|
|
|
406 *
|
|
|
407 * Timers take into account the amount of time it took to execute the
|
|
|
408 * callback. For example, if the callback took 250 ns to execute and returned
|
|
|
409 * 1000 (ns), the timer would only wait another 750 ns before its next
|
|
|
410 * iteration.
|
|
|
411 *
|
|
|
412 * Timing may be inexact due to OS scheduling. Be sure to note the current
|
|
|
413 * time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your
|
|
|
414 * callback needs to adjust for variances.
|
|
|
415 *
|
|
|
416 * \param interval the timer delay, in nanoseconds, passed to `callback`.
|
|
|
417 * \param callback the SDL_TimerCallback function to call when the specified
|
|
|
418 * `interval` elapses.
|
|
|
419 * \param userdata a pointer that is passed to `callback`.
|
|
|
420 * \returns a timer ID or 0 on failure; call SDL_GetError() for more
|
|
|
421 * information.
|
|
|
422 *
|
|
|
423 * \threadsafety It is safe to call this function from any thread.
|
|
|
424 *
|
|
|
425 * \since This function is available since SDL 3.2.0.
|
|
|
426 *
|
|
|
427 * \sa SDL_AddTimer
|
|
|
428 * \sa SDL_RemoveTimer
|
|
|
429 */
|
|
|
430 extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTimerCallback callback, void *userdata);
|
|
|
431
|
|
|
432 /**
|
|
|
433 * Remove a timer created with SDL_AddTimer().
|
|
|
434 *
|
|
|
435 * \param id the ID of the timer to remove.
|
|
|
436 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
437 * information.
|
|
|
438 *
|
|
|
439 * \threadsafety It is safe to call this function from any thread.
|
|
|
440 *
|
|
|
441 * \since This function is available since SDL 3.2.0.
|
|
|
442 *
|
|
|
443 * \sa SDL_AddTimer
|
|
|
444 */
|
|
|
445 extern SDL_DECLSPEC bool SDLCALL SDL_RemoveTimer(SDL_TimerID id);
|
|
|
446
|
|
|
447
|
|
|
448 /* Ends C function definitions when using C++ */
|
|
|
449 #ifdef __cplusplus
|
|
|
450 }
|
|
|
451 #endif
|
|
|
452 #include <SDL3/SDL_close_code.h>
|
|
|
453
|
|
|
454 #endif /* SDL_timer_h_ */
|
