sdl3_sys/generated/
timer.rs

1//! SDL provides time management functionality. It is useful for dealing with
2//! (usually) small durations of time.
3//!
4//! This is not to be confused with _calendar time_ management, which is
5//! provided by [CategoryTime](CategoryTime).
6//!
7//! This category covers measuring time elapsed ([`SDL_GetTicks()`],
8//! [`SDL_GetPerformanceCounter()`]), putting a thread to sleep for a certain
9//! amount of time ([`SDL_Delay()`], [`SDL_DelayNS()`], [`SDL_DelayPrecise()`]), and firing
10//! a callback function after a certain amount of time has elasped
11//! ([`SDL_AddTimer()`], etc).
12//!
13//! There are also useful macros to convert between time units, like
14//! [`SDL_SECONDS_TO_NS()`] and such.
15
16use super::stdinc::*;
17
18use super::error::*;
19
20/// Number of milliseconds in a second.
21///
22/// This is always 1000.
23///
24/// ### Availability
25/// This macro is available since SDL 3.2.0.
26pub const SDL_MS_PER_SECOND: ::core::primitive::i32 = 1000;
27
28/// Number of microseconds in a second.
29///
30/// This is always 1000000.
31///
32/// ### Availability
33/// This macro is available since SDL 3.2.0.
34pub const SDL_US_PER_SECOND: ::core::primitive::i32 = 1000000;
35
36/// Number of nanoseconds in a second.
37///
38/// This is always 1000000000.
39///
40/// ### Availability
41/// This macro is available since SDL 3.2.0.
42pub const SDL_NS_PER_SECOND: ::core::primitive::i64 = 1000000000_i64;
43
44/// Number of nanoseconds in a millisecond.
45///
46/// This is always 1000000.
47///
48/// ### Availability
49/// This macro is available since SDL 3.2.0.
50pub const SDL_NS_PER_MS: ::core::primitive::i32 = 1000000;
51
52/// Number of nanoseconds in a microsecond.
53///
54/// This is always 1000.
55///
56/// ### Availability
57/// This macro is available since SDL 3.2.0.
58pub const SDL_NS_PER_US: ::core::primitive::i32 = 1000;
59
60/// Convert seconds to nanoseconds.
61///
62/// This only converts whole numbers, not fractional seconds.
63///
64/// ### Parameters
65/// - `S`: the number of seconds to convert.
66///
67/// ### Return value
68/// Returns S, expressed in nanoseconds.
69///
70/// ### Thread safety
71/// It is safe to call this macro from any thread.
72///
73/// ### Availability
74/// This macro is available since SDL 3.2.0.
75#[inline(always)]
76pub const fn SDL_SECONDS_TO_NS(S: Uint64) -> Uint64 {
77    (S * (SDL_NS_PER_SECOND as Uint64))
78}
79
80/// Convert nanoseconds to seconds.
81///
82/// This performs a division, so the results can be dramatically different if
83/// `NS` is an integer or floating point value.
84///
85/// ### Parameters
86/// - `NS`: the number of nanoseconds to convert.
87///
88/// ### Return value
89/// Returns NS, expressed in seconds.
90///
91/// ### Thread safety
92/// It is safe to call this macro from any thread.
93///
94/// ### Availability
95/// This macro is available since SDL 3.2.0.
96#[inline(always)]
97pub const fn SDL_NS_TO_SECONDS(NS: Uint64) -> Uint64 {
98    (NS / (SDL_NS_PER_SECOND as Uint64))
99}
100
101/// Convert milliseconds to nanoseconds.
102///
103/// This only converts whole numbers, not fractional milliseconds.
104///
105/// ### Parameters
106/// - `MS`: the number of milliseconds to convert.
107///
108/// ### Return value
109/// Returns MS, expressed in nanoseconds.
110///
111/// ### Thread safety
112/// It is safe to call this macro from any thread.
113///
114/// ### Availability
115/// This macro is available since SDL 3.2.0.
116#[inline(always)]
117pub const fn SDL_MS_TO_NS(MS: Uint64) -> Uint64 {
118    (MS * (SDL_NS_PER_MS as Uint64))
119}
120
121/// Convert nanoseconds to milliseconds.
122///
123/// This performs a division, so the results can be dramatically different if
124/// `NS` is an integer or floating point value.
125///
126/// ### Parameters
127/// - `NS`: the number of nanoseconds to convert.
128///
129/// ### Return value
130/// Returns NS, expressed in milliseconds.
131///
132/// ### Thread safety
133/// It is safe to call this macro from any thread.
134///
135/// ### Availability
136/// This macro is available since SDL 3.2.0.
137#[inline(always)]
138pub const fn SDL_NS_TO_MS(NS: Uint64) -> Uint64 {
139    (NS / (SDL_NS_PER_MS as Uint64))
140}
141
142/// Convert microseconds to nanoseconds.
143///
144/// This only converts whole numbers, not fractional microseconds.
145///
146/// ### Parameters
147/// - `US`: the number of microseconds to convert.
148///
149/// ### Return value
150/// Returns US, expressed in nanoseconds.
151///
152/// ### Thread safety
153/// It is safe to call this macro from any thread.
154///
155/// ### Availability
156/// This macro is available since SDL 3.2.0.
157#[inline(always)]
158pub const fn SDL_US_TO_NS(US: Uint64) -> Uint64 {
159    (US * (SDL_NS_PER_US as Uint64))
160}
161
162/// Convert nanoseconds to microseconds.
163///
164/// This performs a division, so the results can be dramatically different if
165/// `NS` is an integer or floating point value.
166///
167/// ### Parameters
168/// - `NS`: the number of nanoseconds to convert.
169///
170/// ### Return value
171/// Returns NS, expressed in microseconds.
172///
173/// ### Thread safety
174/// It is safe to call this macro from any thread.
175///
176/// ### Availability
177/// This macro is available since SDL 3.2.0.
178#[inline(always)]
179pub const fn SDL_NS_TO_US(NS: Uint64) -> Uint64 {
180    (NS / (SDL_NS_PER_US as Uint64))
181}
182
183extern "C" {
184    /// Get the number of milliseconds since SDL library initialization.
185    ///
186    /// ### Return value
187    /// Returns an unsigned 64-bit value representing the number of milliseconds
188    ///   since the SDL library initialized.
189    ///
190    /// ### Thread safety
191    /// It is safe to call this function from any thread.
192    ///
193    /// ### Availability
194    /// This function is available since SDL 3.2.0.
195    pub fn SDL_GetTicks() -> Uint64;
196}
197
198extern "C" {
199    /// Get the number of nanoseconds since SDL library initialization.
200    ///
201    /// ### Return value
202    /// Returns an unsigned 64-bit value representing the number of nanoseconds
203    ///   since the SDL library initialized.
204    ///
205    /// ### Thread safety
206    /// It is safe to call this function from any thread.
207    ///
208    /// ### Availability
209    /// This function is available since SDL 3.2.0.
210    pub fn SDL_GetTicksNS() -> Uint64;
211}
212
213extern "C" {
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    /// ### Return value
223    /// Returns the current counter value.
224    ///
225    /// ### Thread safety
226    /// It is safe to call this function from any thread.
227    ///
228    /// ### Availability
229    /// This function is available since SDL 3.2.0.
230    ///
231    /// ### See also
232    /// - [`SDL_GetPerformanceFrequency`]
233    pub fn SDL_GetPerformanceCounter() -> Uint64;
234}
235
236extern "C" {
237    /// Get the count per second of the high resolution counter.
238    ///
239    /// ### Return value
240    /// Returns a platform-specific count per second.
241    ///
242    /// ### Thread safety
243    /// It is safe to call this function from any thread.
244    ///
245    /// ### Availability
246    /// This function is available since SDL 3.2.0.
247    ///
248    /// ### See also
249    /// - [`SDL_GetPerformanceCounter`]
250    pub fn SDL_GetPerformanceFrequency() -> Uint64;
251}
252
253extern "C" {
254    /// Wait a specified number of milliseconds before returning.
255    ///
256    /// This function waits a specified number of milliseconds before returning. It
257    /// waits at least the specified time, but possibly longer due to OS
258    /// scheduling.
259    ///
260    /// ### Parameters
261    /// - `ms`: the number of milliseconds to delay.
262    ///
263    /// ### Thread safety
264    /// It is safe to call this function from any thread.
265    ///
266    /// ### Availability
267    /// This function is available since SDL 3.2.0.
268    ///
269    /// ### See also
270    /// - [`SDL_DelayNS`]
271    /// - [`SDL_DelayPrecise`]
272    pub fn SDL_Delay(ms: Uint32);
273}
274
275extern "C" {
276    /// Wait a specified number of nanoseconds before returning.
277    ///
278    /// This function waits a specified number of nanoseconds before returning. It
279    /// waits at least the specified time, but possibly longer due to OS
280    /// scheduling.
281    ///
282    /// ### Parameters
283    /// - `ns`: the number of nanoseconds to delay.
284    ///
285    /// ### Thread safety
286    /// It is safe to call this function from any thread.
287    ///
288    /// ### Availability
289    /// This function is available since SDL 3.2.0.
290    ///
291    /// ### See also
292    /// - [`SDL_Delay`]
293    /// - [`SDL_DelayPrecise`]
294    pub fn SDL_DelayNS(ns: Uint64);
295}
296
297extern "C" {
298    /// Wait a specified number of nanoseconds before returning.
299    ///
300    /// This function waits a specified number of nanoseconds before returning. It
301    /// will attempt to wait as close to the requested time as possible, busy
302    /// waiting if necessary, but could return later due to OS scheduling.
303    ///
304    /// ### Parameters
305    /// - `ns`: the number of nanoseconds to delay.
306    ///
307    /// ### Thread safety
308    /// It is safe to call this function from any thread.
309    ///
310    /// ### Availability
311    /// This function is available since SDL 3.2.0.
312    ///
313    /// ### See also
314    /// - [`SDL_Delay`]
315    /// - [`SDL_DelayNS`]
316    pub fn SDL_DelayPrecise(ns: Uint64);
317}
318
319/// Definition of the timer ID type.
320///
321/// ### Availability
322/// This datatype is available since SDL 3.2.0.
323pub type SDL_TimerID = Uint32;
324
325/// Function prototype for the millisecond timer callback function.
326///
327/// The callback function is passed the current timer interval and returns the
328/// next timer interval, in milliseconds. If the returned value is the same as
329/// the one passed in, the periodic alarm continues, otherwise a new alarm is
330/// scheduled. If the callback returns 0, the periodic alarm is canceled and
331/// will be removed.
332///
333/// ### Parameters
334/// - `userdata`: an arbitrary pointer provided by the app through
335///   [`SDL_AddTimer`], for its own use.
336/// - `timerID`: the current timer being processed.
337/// - `interval`: the current callback time interval.
338///
339/// ### Return value
340/// Returns the new callback time interval, or 0 to disable further runs of
341///   the callback.
342///
343/// ### Thread safety
344/// SDL may call this callback at any time from a background
345///   thread; the application is responsible for locking resources
346///   the callback touches that need to be protected.
347///
348/// ### Availability
349/// This datatype is available since SDL 3.2.0.
350///
351/// ### See also
352/// - [`SDL_AddTimer`]
353pub type SDL_TimerCallback = ::core::option::Option<
354    unsafe extern "C" fn(
355        userdata: *mut ::core::ffi::c_void,
356        timerID: SDL_TimerID,
357        interval: Uint32,
358    ) -> Uint32,
359>;
360
361extern "C" {
362    /// Call a callback function at a future time.
363    ///
364    /// The callback function is passed the current timer interval and the user
365    /// supplied parameter from the [`SDL_AddTimer()`] call and should return the next
366    /// timer interval. If the value returned from the callback is 0, the timer is
367    /// canceled and will be removed.
368    ///
369    /// The callback is run on a separate thread, and for short timeouts can
370    /// potentially be called before this function returns.
371    ///
372    /// Timers take into account the amount of time it took to execute the
373    /// callback. For example, if the callback took 250 ms to execute and returned
374    /// 1000 (ms), the timer would only wait another 750 ms before its next
375    /// iteration.
376    ///
377    /// Timing may be inexact due to OS scheduling. Be sure to note the current
378    /// time with [`SDL_GetTicksNS()`] or [`SDL_GetPerformanceCounter()`] in case your
379    /// callback needs to adjust for variances.
380    ///
381    /// ### Parameters
382    /// - `interval`: the timer delay, in milliseconds, passed to `callback`.
383    /// - `callback`: the [`SDL_TimerCallback`] function to call when the specified
384    ///   `interval` elapses.
385    /// - `userdata`: a pointer that is passed to `callback`.
386    ///
387    /// ### Return value
388    /// Returns a timer ID or 0 on failure; call [`SDL_GetError()`] for more
389    ///   information.
390    ///
391    /// ### Thread safety
392    /// It is safe to call this function from any thread.
393    ///
394    /// ### Availability
395    /// This function is available since SDL 3.2.0.
396    ///
397    /// ### See also
398    /// - [`SDL_AddTimerNS`]
399    /// - [`SDL_RemoveTimer`]
400    pub fn SDL_AddTimer(
401        interval: Uint32,
402        callback: SDL_TimerCallback,
403        userdata: *mut ::core::ffi::c_void,
404    ) -> SDL_TimerID;
405}
406
407/// Function prototype for the nanosecond timer callback function.
408///
409/// The callback function is passed the current timer interval and returns the
410/// next timer interval, in nanoseconds. If the returned value is the same as
411/// the one passed in, the periodic alarm continues, otherwise a new alarm is
412/// scheduled. If the callback returns 0, the periodic alarm is canceled and
413/// will be removed.
414///
415/// ### Parameters
416/// - `userdata`: an arbitrary pointer provided by the app through
417///   [`SDL_AddTimer`], for its own use.
418/// - `timerID`: the current timer being processed.
419/// - `interval`: the current callback time interval.
420///
421/// ### Return value
422/// Returns the new callback time interval, or 0 to disable further runs of
423///   the callback.
424///
425/// ### Thread safety
426/// SDL may call this callback at any time from a background
427///   thread; the application is responsible for locking resources
428///   the callback touches that need to be protected.
429///
430/// ### Availability
431/// This datatype is available since SDL 3.2.0.
432///
433/// ### See also
434/// - [`SDL_AddTimerNS`]
435pub type SDL_NSTimerCallback = ::core::option::Option<
436    unsafe extern "C" fn(
437        userdata: *mut ::core::ffi::c_void,
438        timerID: SDL_TimerID,
439        interval: Uint64,
440    ) -> Uint64,
441>;
442
443extern "C" {
444    /// Call a callback function at a future time.
445    ///
446    /// The callback function is passed the current timer interval and the user
447    /// supplied parameter from the [`SDL_AddTimerNS()`] call and should return the
448    /// next timer interval. If the value returned from the callback is 0, the
449    /// timer is canceled and will be removed.
450    ///
451    /// The callback is run on a separate thread, and for short timeouts can
452    /// potentially be called before this function returns.
453    ///
454    /// Timers take into account the amount of time it took to execute the
455    /// callback. For example, if the callback took 250 ns to execute and returned
456    /// 1000 (ns), the timer would only wait another 750 ns before its next
457    /// iteration.
458    ///
459    /// Timing may be inexact due to OS scheduling. Be sure to note the current
460    /// time with [`SDL_GetTicksNS()`] or [`SDL_GetPerformanceCounter()`] in case your
461    /// callback needs to adjust for variances.
462    ///
463    /// ### Parameters
464    /// - `interval`: the timer delay, in nanoseconds, passed to `callback`.
465    /// - `callback`: the [`SDL_TimerCallback`] function to call when the specified
466    ///   `interval` elapses.
467    /// - `userdata`: a pointer that is passed to `callback`.
468    ///
469    /// ### Return value
470    /// Returns a timer ID or 0 on failure; call [`SDL_GetError()`] for more
471    ///   information.
472    ///
473    /// ### Thread safety
474    /// It is safe to call this function from any thread.
475    ///
476    /// ### Availability
477    /// This function is available since SDL 3.2.0.
478    ///
479    /// ### See also
480    /// - [`SDL_AddTimer`]
481    /// - [`SDL_RemoveTimer`]
482    pub fn SDL_AddTimerNS(
483        interval: Uint64,
484        callback: SDL_NSTimerCallback,
485        userdata: *mut ::core::ffi::c_void,
486    ) -> SDL_TimerID;
487}
488
489extern "C" {
490    /// Remove a timer created with [`SDL_AddTimer()`].
491    ///
492    /// ### Parameters
493    /// - `id`: the ID of the timer to remove.
494    ///
495    /// ### Return value
496    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
497    ///   information.
498    ///
499    /// ### Thread safety
500    /// It is safe to call this function from any thread.
501    ///
502    /// ### Availability
503    /// This function is available since SDL 3.2.0.
504    ///
505    /// ### See also
506    /// - [`SDL_AddTimer`]
507    pub fn SDL_RemoveTimer(id: SDL_TimerID) -> ::core::primitive::bool;
508}
509
510#[cfg(doc)]
511use crate::everything::*;
sdl3_sys/generated/timer.rs

sdl3_sys/generated/
timer.rs
