Atlas - SDL_timer.h
Home / ext / SDL / include / SDL3 Lines: 1 | Size: 14683 bytes [Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)][FILE BEGIN]1/* 2 Simple DirectMedia Layer 3 Copyright (C) 1997-2025 Sam Lantinga <[email protected]> 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 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 * 199 * \sa SDL_GetTicksNS 200 */ 201extern 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 */ 213extern 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 */ 232extern 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 */ 245extern 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 */ 263extern 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 */ 281extern 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 */ 299extern 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 */ 306typedef 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 */ 332typedef 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 */ 368extern 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 */ 394typedef 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 */ 430extern 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 */ 445extern 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_ */ 455[FILE END](C) 2025 0x4248 (C) 2025 4248 Media and 4248 Systems, All part of 0x4248 See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.