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 elasped
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
50extern "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 */
199extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void);
200
201/**
202 * Get the number of nanoseconds since SDL library initialization.
203 *
204 * \returns an unsigned 64-bit value representing the number of nanoseconds
205 * since the SDL library initialized.
206 *
207 * \threadsafety It is safe to call this function from any thread.
208 *
209 * \since This function is available since SDL 3.2.0.
210 */
211extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void);
212
213/**
214 * Get the current value of the high resolution counter.
215 *
216 * This function is typically used for profiling.
217 *
218 * The counter values are only meaningful relative to each other. Differences
219 * between values can be converted to times by using
220 * SDL_GetPerformanceFrequency().
221 *
222 * \returns the current counter value.
223 *
224 * \threadsafety It is safe to call this function from any thread.
225 *
226 * \since This function is available since SDL 3.2.0.
227 *
228 * \sa SDL_GetPerformanceFrequency
229 */
230extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void);
231
232/**
233 * Get the count per second of the high resolution counter.
234 *
235 * \returns a platform-specific count per second.
236 *
237 * \threadsafety It is safe to call this function from any thread.
238 *
239 * \since This function is available since SDL 3.2.0.
240 *
241 * \sa SDL_GetPerformanceCounter
242 */
243extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void);
244
245/**
246 * Wait a specified number of milliseconds before returning.
247 *
248 * This function waits a specified number of milliseconds before returning. It
249 * waits at least the specified time, but possibly longer due to OS
250 * scheduling.
251 *
252 * \param ms the number of milliseconds to delay.
253 *
254 * \threadsafety It is safe to call this function from any thread.
255 *
256 * \since This function is available since SDL 3.2.0.
257 *
258 * \sa SDL_DelayNS
259 * \sa SDL_DelayPrecise
260 */
261extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
262
263/**
264 * Wait a specified number of nanoseconds before returning.
265 *
266 * This function waits a specified number of nanoseconds before returning. It
267 * waits at least the specified time, but possibly longer due to OS
268 * scheduling.
269 *
270 * \param ns the number of nanoseconds to delay.
271 *
272 * \threadsafety It is safe to call this function from any thread.
273 *
274 * \since This function is available since SDL 3.2.0.
275 *
276 * \sa SDL_Delay
277 * \sa SDL_DelayPrecise
278 */
279extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns);
280
281/**
282 * Wait a specified number of nanoseconds before returning.
283 *
284 * This function waits a specified number of nanoseconds before returning. It
285 * will attempt to wait as close to the requested time as possible, busy
286 * waiting if necessary, but could return later due to OS scheduling.
287 *
288 * \param ns the number of nanoseconds to delay.
289 *
290 * \threadsafety It is safe to call this function from any thread.
291 *
292 * \since This function is available since SDL 3.2.0.
293 *
294 * \sa SDL_Delay
295 * \sa SDL_DelayNS
296 */
297extern SDL_DECLSPEC void SDLCALL SDL_DelayPrecise(Uint64 ns);
298
299/**
300 * Definition of the timer ID type.
301 *
302 * \since This datatype is available since SDL 3.2.0.
303 */
304typedef Uint32 SDL_TimerID;
305
306/**
307 * Function prototype for the millisecond timer callback function.
308 *
309 * The callback function is passed the current timer interval and returns the
310 * next timer interval, in milliseconds. If the returned value is the same as
311 * the one passed in, the periodic alarm continues, otherwise a new alarm is
312 * scheduled. If the callback returns 0, the periodic alarm is canceled and
313 * will be removed.
314 *
315 * \param userdata an arbitrary pointer provided by the app through
316 * SDL_AddTimer, for its own use.
317 * \param timerID the current timer being processed.
318 * \param interval the current callback time interval.
319 * \returns the new callback time interval, or 0 to disable further runs of
320 * the callback.
321 *
322 * \threadsafety SDL may call this callback at any time from a background
323 * thread; the application is responsible for locking resources
324 * the callback touches that need to be protected.
325 *
326 * \since This datatype is available since SDL 3.2.0.
327 *
328 * \sa SDL_AddTimer
329 */
330typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, Uint32 interval);
331
332/**
333 * Call a callback function at a future time.
334 *
335 * The callback function is passed the current timer interval and the user
336 * supplied parameter from the SDL_AddTimer() call and should return the next
337 * timer interval. If the value returned from the callback is 0, the timer is
338 * canceled and will be removed.
339 *
340 * The callback is run on a separate thread, and for short timeouts can
341 * potentially be called before this function returns.
342 *
343 * Timers take into account the amount of time it took to execute the
344 * callback. For example, if the callback took 250 ms to execute and returned
345 * 1000 (ms), the timer would only wait another 750 ms before its next
346 * iteration.
347 *
348 * Timing may be inexact due to OS scheduling. Be sure to note the current
349 * time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your
350 * callback needs to adjust for variances.
351 *
352 * \param interval the timer delay, in milliseconds, passed to `callback`.
353 * \param callback the SDL_TimerCallback function to call when the specified
354 * `interval` elapses.
355 * \param userdata a pointer that is passed to `callback`.
356 * \returns a timer ID or 0 on failure; call SDL_GetError() for more
357 * information.
358 *
359 * \threadsafety It is safe to call this function from any thread.
360 *
361 * \since This function is available since SDL 3.2.0.
362 *
363 * \sa SDL_AddTimerNS
364 * \sa SDL_RemoveTimer
365 */
366extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_TimerCallback callback, void *userdata);
367
368/**
369 * Function prototype for the nanosecond timer callback function.
370 *
371 * The callback function is passed the current timer interval and returns the
372 * next timer interval, in nanoseconds. If the returned value is the same as
373 * the one passed in, the periodic alarm continues, otherwise a new alarm is
374 * scheduled. If the callback returns 0, the periodic alarm is canceled and
375 * will be removed.
376 *
377 * \param userdata an arbitrary pointer provided by the app through
378 * SDL_AddTimer, for its own use.
379 * \param timerID the current timer being processed.
380 * \param interval the current callback time interval.
381 * \returns the new callback time interval, or 0 to disable further runs of
382 * the callback.
383 *
384 * \threadsafety SDL may call this callback at any time from a background
385 * thread; the application is responsible for locking resources
386 * the callback touches that need to be protected.
387 *
388 * \since This datatype is available since SDL 3.2.0.
389 *
390 * \sa SDL_AddTimerNS
391 */
392typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerID, Uint64 interval);
393
394/**
395 * Call a callback function at a future time.
396 *
397 * The callback function is passed the current timer interval and the user
398 * supplied parameter from the SDL_AddTimerNS() call and should return the
399 * next timer interval. If the value returned from the callback is 0, the
400 * timer is canceled and will be removed.
401 *
402 * The callback is run on a separate thread, and for short timeouts can
403 * potentially be called before this function returns.
404 *
405 * Timers take into account the amount of time it took to execute the
406 * callback. For example, if the callback took 250 ns to execute and returned
407 * 1000 (ns), the timer would only wait another 750 ns before its next
408 * iteration.
409 *
410 * Timing may be inexact due to OS scheduling. Be sure to note the current
411 * time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your
412 * callback needs to adjust for variances.
413 *
414 * \param interval the timer delay, in nanoseconds, passed to `callback`.
415 * \param callback the SDL_TimerCallback function to call when the specified
416 * `interval` elapses.
417 * \param userdata a pointer that is passed to `callback`.
418 * \returns a timer ID or 0 on failure; call SDL_GetError() for more
419 * information.
420 *
421 * \threadsafety It is safe to call this function from any thread.
422 *
423 * \since This function is available since SDL 3.2.0.
424 *
425 * \sa SDL_AddTimer
426 * \sa SDL_RemoveTimer
427 */
428extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTimerCallback callback, void *userdata);
429
430/**
431 * Remove a timer created with SDL_AddTimer().
432 *
433 * \param id the ID of the timer to remove.
434 * \returns true on success or false on failure; call SDL_GetError() for more
435 * information.
436 *
437 * \threadsafety It is safe to call this function from any thread.
438 *
439 * \since This function is available since SDL 3.2.0.
440 *
441 * \sa SDL_AddTimer
442 */
443extern SDL_DECLSPEC bool SDLCALL SDL_RemoveTimer(SDL_TimerID id);
444
445
446/* Ends C function definitions when using C++ */
447#ifdef __cplusplus
448}
449#endif
450#include <SDL3/SDL_close_code.h>
451
452#endif /* SDL_timer_h_ */
453