SDL provides time management functionality. More...

Typedefs
using	SDL::TimerID = SDL_TimerID
	Definition of the timer ID type.

using	SDL::TimerCallback = SDL_NSTimerCallback
	Function prototype for the nanosecond timer callback function.

using	SDL::TimerCB = std::function< std::chrono::nanoseconds(TimerID, std::chrono::nanoseconds)>
	Function prototype for the nanosecond timer callback function.

Functions
std::chrono::nanoseconds	SDL::GetTicks ()
	Get the time elapsed 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 (std::chrono::nanoseconds duration)
	Wait a specified duration before returning.

void	SDL::DelayPrecise (std::chrono::nanoseconds duration)
	Wait a specified duration before returning.

TimerID	SDL::AddTimer (std::chrono::nanoseconds interval, TimerCallback 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

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 (SDL_Delay(), SDL_DelayNS(), SDL_DelayPrecise()), and firing a callback function after a certain amount of time has elapsed (AddTimer(), etc).

Typedef Documentation

◆ TimerCallback

using SDL::TimerCallback = typedef SDL_NSTimerCallback

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

◆ TimerCB

using SDL::TimerCB = typedef std::function<std::chrono::nanoseconds(TimerID, std::chrono::nanoseconds)>

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

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.

Category:: Listener callback

See also: listener-callback; AddTimer(TimerCB)

◆ TimerID

using SDL::TimerID = typedef SDL_TimerID

Since: This datatype is available since SDL 3.2.0.

Function Documentation

◆ AddTimer() [1/2]

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

inline

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 GetTicks() 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: RemoveTimer

◆ AddTimer() [2/2]

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

inline

The callback function is passed the current timer interval and the user supplied parameter from the AddTimerNS() 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; RemoveTimer()

◆ Delay()

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

inline

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.

◆ DelayPrecise()

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

inline

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(); DelayNS()

◆ FromPosix()

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

staticconstexpr

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

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 SDL_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

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

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.

◆ RemoveTimer()

void SDL::RemoveTimer ( TimerID id )

inline

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()

constexpr Sint64 SDL::Time::ToPosix ( ) const

constexpr

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.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ TimerCallback

◆ TimerCB

◆ TimerID

Function Documentation

◆ AddTimer() [1/2]

◆ AddTimer() [2/2]

◆ Delay()

◆ DelayPrecise()

◆ FromPosix()

◆ GetPerformanceCounter()

◆ GetPerformanceFrequency()

◆ GetTicks()

◆ RemoveTimer()

◆ ToPosix()