SDL provides time management functionality. More...

Classes
struct	SDL::TimerCB
	Function prototype for the nanosecond timer callback function. More...

Typedefs
using	SDL::TimerID = SDL_TimerID
	Definition of the timer ID type.
using	SDL::MSTimerCallback
	Function prototype for the millisecond timer callback function.
using	SDL::NSTimerCallback
	Function prototype for the nanosecond timer callback function.

Functions
std::chrono::nanoseconds	SDL::GetTicks ()
	Get the time elapsed since SDL library initialization.
Uint64	SDL::GetTicksMS ()
	Get the number of milliseconds that have elapsed since the SDL library initialization.
Uint64	SDL::GetTicksNS ()
	Get the number of nanoseconds since SDL library initialization.
Uint64	SDL::GetPerformanceCounter ()
	Get the current value of the high resolution counter.
Uint64	SDL::GetPerformanceFrequency ()
	Get the count per second of the high resolution counter.
void	SDL::Delay (Uint32 ms)
	Wait a specified number of milliseconds before returning.
void	SDL::Delay (std::chrono::nanoseconds duration)
	Wait a specified duration before returning.
void	SDL::DelayNS (Uint64 ns)
	Wait a specified number of nanoseconds before returning.
void	SDL::DelayPrecise (Uint64 ns)
	Wait a specified number of nanoseconds before returning.
void	SDL::DelayPrecise (std::chrono::nanoseconds duration)
	Wait a specified duration before returning.
TimerID	SDL::AddTimer (std::chrono::milliseconds interval, MSTimerCallback callback, void *userdata)
	Call a callback function at a future time.
TimerID	SDL::AddTimer (std::chrono::nanoseconds interval, NSTimerCallback callback, void *userdata)
	Call a callback function at a future time.
TimerID	SDL::AddTimer (std::chrono::nanoseconds interval, TimerCB callback)
	Call a callback function at a future time.
void	SDL::RemoveTimer (TimerID id)
	Remove a timer created with AddTimer().
static constexpr Time	SDL::Time::FromPosix (Sint64 time)
	Convert seconds to nanoseconds.
constexpr Sint64	SDL::Time::ToPosix () const
	Convert nanoseconds to seconds.

Detailed Description

SDL provides time management functionality.

It is useful for dealing with (usually) small durations of time.

This is not to be confused with calendar time management, which is provided by CategoryTime.

This category covers measuring time elapsed (GetTicks(), GetPerformanceCounter()), putting a thread to sleep for a certain amount of time (Delay(), DelayNS(), DelayPrecise()), and firing a callback function after a certain amount of time has elapsed (AddTimer(), etc).

Typedef Documentation

◆ MSTimerCallback

using SDL::MSTimerCallback

Initial value:

Uint32(SDLCALL*)(void* userdata,
                                        TimerID timerID,
                                        Uint32 interval)

Function prototype for the millisecond timer callback function.

The callback function is passed the current timer interval and returns the next timer interval, in milliseconds. If the returned value is the same as the one passed in, the periodic alarm continues, otherwise a new alarm is scheduled. If the callback returns 0, the periodic alarm is canceled and will be removed.

Parameters

userdata	an arbitrary pointer provided by the app through AddTimer, for its own use.
timerID	the current timer being processed.
interval	the current callback time interval.

Returns: the new callback time interval, or 0 to disable further runs of the callback.

Thread safety:: SDL may call this callback at any time from a background thread; the application is responsible for locking resources the callback touches that need to be protected.

Since: This datatype is available since SDL 3.2.0.

See also: AddTimer

◆ NSTimerCallback

using SDL::NSTimerCallback

Initial value:

Uint64(SDLCALL*)(void* userdata,
                                        TimerID timerID,
                                        Uint64 interval)

Function prototype for the nanosecond timer callback function.

The callback function is passed the current timer interval and returns the next timer interval, in nanoseconds. If the returned value is the same as the one passed in, the periodic alarm continues, otherwise a new alarm is scheduled. If the callback returns 0, the periodic alarm is canceled and will be removed.

Parameters

userdata	an arbitrary pointer provided by the app through AddTimer, for its own use.
timerID	the current timer being processed.
interval	the current callback time interval.

Returns: the new callback time interval, or 0 to disable further runs of the callback.

Thread safety:: SDL may call this callback at any time from a background thread; the application is responsible for locking resources the callback touches that need to be protected.

Since: This datatype is available since SDL 3.2.0.

See also: AddTimer

◆ TimerID

using SDL::TimerID = SDL_TimerID

Definition of the timer ID type.

Since: This datatype is available since SDL 3.2.0.

Function Documentation

◆ AddTimer() [1/3]

TimerID SDL::AddTimer	(	std::chrono::milliseconds	interval,
		MSTimerCallback	callback,
		void *	userdata )

inline

Call a callback function at a future time.

The callback function is passed the current timer interval and the user supplied parameter from the AddTimer() call and should return the next timer interval. If the value returned from the callback is 0, the timer is canceled and will be removed.

The callback is run on a separate thread, and for short timeouts can potentially be called before this function returns.

Timers take into account the amount of time it took to execute the callback. For example, if the callback took 250 ms to execute and returned 1000 (ms), the timer would only wait another 750 ms before its next iteration.

Timing may be inexact due to OS scheduling. Be sure to note the current time with GetTicksNS() or GetPerformanceCounter() in case your callback needs to adjust for variances.

Parameters

interval	the timer delay, in std::chrono::nanoseconds, passed to callback.
callback	the NSTimerCallback function to call when the specified interval elapses.
userdata	a pointer that is passed to callback.

Returns: a timer ID or 0 on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AddTimer(std::chrono::nanoseconds, NSTimerCallback, void*); AddTimer(std::chrono::nanoseconds, TimerCB); RemoveTimer

◆ AddTimer() [2/3]

TimerID SDL::AddTimer	(	std::chrono::nanoseconds	interval,
		NSTimerCallback	callback,
		void *	userdata )

inline

Call a callback function at a future time.

The callback function is passed the current timer interval and the user supplied parameter from the AddTimer() call and should return the next timer interval. If the value returned from the callback is 0, the timer is canceled and will be removed.

The callback is run on a separate thread, and for short timeouts can potentially be called before this function returns.

Timers take into account the amount of time it took to execute the callback. For example, if the callback took 250 ns to execute and returned 1000 (ns), the timer would only wait another 750 ns before its next iteration.

Timing may be inexact due to OS scheduling. Be sure to note the current time with GetTicksNS() or GetPerformanceCounter() in case your callback needs to adjust for variances.

Parameters

interval	the timer delay, in std::chrono::nanoseconds, passed to callback.
callback	the NSTimerCallback function to call when the specified interval elapses.
userdata	a pointer that is passed to callback.

Returns: a timer ID.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AddTimer(std::chrono::milliseconds, MSTimerCallback, void*); AddTimer(std::chrono::nanoseconds, TimerCB); RemoveTimer

◆ AddTimer() [3/3]

TimerID SDL::AddTimer	(	std::chrono::nanoseconds	interval,
		TimerCB	callback )

inline

Call a callback function at a future time.

The callback function is passed the current timer interval and the user supplied parameter from the AddTimer() call and should return the next timer interval. If the value returned from the callback is 0, the timer is canceled and will be removed.

The callback is run on a separate thread, and for short timeouts can potentially be called before this function returns.

Timers take into account the amount of time it took to execute the callback. For example, if the callback took 250 ns to execute and returned 1000 (ns), the timer would only wait another 750 ns before its next iteration.

Timing may be inexact due to OS scheduling. Be sure to note the current time with GetTicksNS() or GetPerformanceCounter() in case your callback needs to adjust for variances.

Parameters

interval	the timer delay, in std::chrono::nanoseconds, passed to callback.
callback	the TimerCB function to call when the specified interval elapses.

Returns: a timer ID.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

Category:: Listener callback

See also: listener-callback; AddTimer(std::chrono::milliseconds, MSTimerCallback, void*); AddTimer(std::chrono::nanoseconds, NSTimerCallback, void*); RemoveTimer()

◆ Delay() [1/2]

void SDL::Delay ( std::chrono::nanoseconds duration )

inline

Wait a specified duration before returning.

This function waits a specified duration before returning. It waits at least the specified time, but possibly longer due to OS scheduling.

Parameters

duration the duration to delay, with max precision in ns.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: DelayNS; DelayPrecise(std::chrono::nanoseconds)

◆ Delay() [2/2]

void SDL::Delay ( Uint32 ms )

inline

Wait a specified number of milliseconds before returning.

This function waits a specified number of milliseconds before returning. It waits at least the specified time, but possibly longer due to OS scheduling.

Parameters

ms	the number of milliseconds to delay.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Delay(std::chrono::nanoseconds); DelayNS; DelayPrecise

◆ DelayNS()

void SDL::DelayNS ( Uint64 ns )

inline

Wait a specified number of nanoseconds before returning.

This function waits a specified number of nanoseconds before returning. It waits at least the specified time, but possibly longer due to OS scheduling.

Parameters

ns	the number of nanoseconds to delay.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Delay; DelayPrecise(std::chrono::nanoseconds)

◆ DelayPrecise() [1/2]

void SDL::DelayPrecise ( std::chrono::nanoseconds duration )

inline

Wait a specified duration before returning.

This function waits a specified duration before returning. It will attempt to wait as close to the requested time as possible, busy waiting if necessary, but could return later due to OS scheduling.

Parameters

duration the duration to delay.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Delay(Uint32); Delay(std::chrono::nanoseconds); DelayNS; DelayPrecise(Uint64)

◆ DelayPrecise() [2/2]

void SDL::DelayPrecise ( Uint64 ns )

inline

Wait a specified number of nanoseconds before returning.

This function waits a specified number of nanoseconds before returning. It will attempt to wait as close to the requested time as possible, busy waiting if necessary, but could return later due to OS scheduling.

Parameters

ns	the number of nanoseconds to delay.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Delay; DelayNS; DelayPrecise(std::chrono::nanoseconds)

◆ FromPosix()

Time SDL::Time::FromPosix ( Sint64 time )

staticconstexpr

Convert seconds to nanoseconds.

This only converts whole numbers, not fractional seconds.

Parameters

time	the number of seconds to convert.

Returns: the converted Time.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetPerformanceCounter()

Uint64 SDL::GetPerformanceCounter ( )

inline

Get the current value of the high resolution counter.

This function is typically used for profiling.

The counter values are only meaningful relative to each other. Differences between values can be converted to times by using GetPerformanceFrequency().

Returns: the current counter value.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetPerformanceFrequency

◆ GetPerformanceFrequency()

Uint64 SDL::GetPerformanceFrequency ( )

inline

Get the count per second of the high resolution counter.

Returns: a platform-specific count per second.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetPerformanceCounter

◆ GetTicks()

std::chrono::nanoseconds SDL::GetTicks ( )

inline

Get the time elapsed since SDL library initialization.

Returns: a std::chrono::nanoseconds value representing the number of nanoseconds since the SDL library initialized.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetTicksMS; GetTicksNS

◆ GetTicksMS()

Uint64 SDL::GetTicksMS ( )

inline

Get the number of milliseconds that have elapsed since the SDL library initialization.

Returns: an unsigned 64‑bit integer that represents the number of milliseconds that have elapsed since the SDL library was initialized (typically via a call to Init).

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetTicksNS

◆ GetTicksNS()

Uint64 SDL::GetTicksNS ( )

inline

Get the number of nanoseconds since SDL library initialization.

Returns: an unsigned 64-bit value representing the number of nanoseconds since the SDL library initialized.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ RemoveTimer()

void SDL::RemoveTimer ( TimerID id )

inline

Remove a timer created with AddTimer().

Parameters

id	the ID of the timer to remove.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AddTimer

◆ ToPosix()

Sint64 SDL::Time::ToPosix ( ) const

constexpr

Convert nanoseconds to seconds.

This only converts whole numbers, not fractional seconds.

Returns: Posix time (in seconds).

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ MSTimerCallback

◆ NSTimerCallback

◆ TimerID

Function Documentation

◆ AddTimer() [1/3]

◆ AddTimer() [2/3]

◆ AddTimer() [3/3]

◆ Delay() [1/2]

◆ Delay() [2/2]

◆ DelayNS()

◆ DelayPrecise() [1/2]

◆ DelayPrecise() [2/2]

◆ FromPosix()

◆ GetPerformanceCounter()

◆ GetPerformanceFrequency()

◆ GetTicks()

◆ GetTicksMS()

◆ GetTicksNS()

◆ RemoveTimer()

◆ ToPosix()