Mercurial > foo_out_sdl

comparison SDL3/SDL_timer.h @ 1:20d02a178406 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
*: check in everything else yay
author Paper <paper@tflc.us>
date Mon, 05 Jan 2026 02:15:46 -0500
parents
children
comparison
equal deleted inserted replaced
0:e9bb126753e7 1:20d02a178406
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_ */