tecs.platform.time#

Platform clocks, calendar time, blocking delays, and frame timing.

The application calls step once per iteration and passes the result to the world. maxDelta clamps long stalls before simulation sees them. Game code may read now, but it must not call step because that moves the frame baseline.

now is monotonic and is the clock for elapsed time and deadlines. wallNow reads the adjustable realtime clock instead and returns an exact Unix timestamp:

local stamp <const> = assert(tecs.platform.time.wallNow())
local localTime <const> = assert(
    tecs.platform.time.toDateTime(stamp, true)
)
print(
    ("%04d-%02d-%02d %02d:%02d"):format(
        localTime.year,
        localTime.month,
        localTime.day,
        localTime.hour,
        localTime.minute
    )
)

The delay functions block the calling thread. They belong in startup, headless tools, and measurements, not in a frame. delayPrecise may busy wait to approach its requested duration.

SDL's callback timer registration is deliberately absent. SDL invokes those callbacks from a timer thread, which cannot safely enter LuaJIT. Game timers store deadlines against now and dispatch from a system, or use tecs.sequence when they belong to simulated time.

Install a provider to replace measured frame deltas during replay:

local recorded <const>: {number} = {1 / 60, 1 / 60, 1 / 30}
local frame = 0

tecs.platform.time.provider = function(realDt: number): number
    frame = frame + 1
    -- Nil keeps the measurement, so a run past the end of the recording is
    -- live again.
    return recorded[frame]
end

Returning nil keeps the measured delta. Pair this provider with tecs.platform.events.source to replay frame timing and platform events together. now always reads the monotonic platform clock and ignores the replay provider.

Module contents#

Types#

Functions#

Values#

Types#

tecs.platform.time.DateTime record#

Represents a calendar date, time, and UTC offset. Read-only. Exposes the calendar date and time record.

record tecs.platform.time.DateTime
    year: integer
    month: integer
    day: integer
    hour: integer
    minute: integer
    second: integer
    nanosecond: integer
    dayOfWeek: integer
    utcOffset: integer
end

tecs.platform.time.DateTime.year field#

Caller-writable. Sets the calendar year.

tecs.platform.time.DateTime.year: integer

tecs.platform.time.DateTime.month field#

Caller-writable. Sets the month from 1 through 12.

tecs.platform.time.DateTime.month: integer

tecs.platform.time.DateTime.day field#

Caller-writable. Sets the day of the month from 1 through 31, bounded further by the selected month and year.

tecs.platform.time.DateTime.day: integer

tecs.platform.time.DateTime.hour field#

Caller-writable. Sets the hour from 0 through 23.

tecs.platform.time.DateTime.hour: integer

tecs.platform.time.DateTime.minute field#

Caller-writable. Sets the minute from 0 through 59.

tecs.platform.time.DateTime.minute: integer

tecs.platform.time.DateTime.second field#

Caller-writable. Sets the second from 0 through 60. The last value represents a possible leap second.

tecs.platform.time.DateTime.second: integer

tecs.platform.time.DateTime.nanosecond field#

Caller-writable. Sets the fractional second from 0 through 999999999 nanoseconds.

tecs.platform.time.DateTime.nanosecond: integer

tecs.platform.time.DateTime.dayOfWeek field#

Read-only. Reports the weekday from 0 through 6, with Sunday at zero. fromDateTime ignores this field.

tecs.platform.time.DateTime.dayOfWeek: integer

tecs.platform.time.DateTime.utcOffset field#

Caller-writable. Sets seconds east of UTC. A value of zero represents UTC, and toDateTime fills the platform's offset for local time.

tecs.platform.time.DateTime.utcOffset: integer

tecs.platform.time.LocalePreferences record#

Represents the current locale's preferred date and clock layouts. Read-only. Exposes the locale preference record.

record tecs.platform.time.LocalePreferences
    dateFormat: string
    timeFormat: string
end

tecs.platform.time.LocalePreferences.dateFormat field#

Read-only. Reports "yearMonthDay", "dayMonthYear" or "monthDayYear".

tecs.platform.time.LocalePreferences.dateFormat: string

tecs.platform.time.LocalePreferences.timeFormat field#

Read-only. Reports "twentyFourHour" or "twelveHour".

tecs.platform.time.LocalePreferences.timeFormat: string

tecs.platform.time.Timestamp record#

Represents an exact instant on the Unix realtime clock. Read-only. Exposes the exact Unix timestamp record.

record tecs.platform.time.Timestamp
    seconds: integer
    nanosecond: integer
end

tecs.platform.time.Timestamp.seconds field#

Caller-writable. Sets whole seconds since 1970-01-01 00:00:00 UTC. A negative value names an instant before the epoch.

tecs.platform.time.Timestamp.seconds: integer

tecs.platform.time.Timestamp.nanosecond field#

Caller-writable. Sets the normalized remainder within seconds, from zero through 999999999.

tecs.platform.time.Timestamp.nanosecond: integer

tecs.platform.time.WindowsTime record#

Represents the two exact words of a Windows FILETIME value. Read-only. Exposes the Windows FILETIME record.

record tecs.platform.time.WindowsTime
    low: integer
    high: integer
end

tecs.platform.time.WindowsTime.low field#

Caller-writable. Sets the low unsigned 32 bits.

tecs.platform.time.WindowsTime.low: integer

tecs.platform.time.WindowsTime.high field#

Caller-writable. Sets the high unsigned 32 bits.

tecs.platform.time.WindowsTime.high: integer

Functions#

tecs.platform.time.dayOfWeek Static#

Returns the weekday of a calendar date.

function tecs.platform.time.dayOfWeek(
    year: integer, month: integer, day: integer
): integer, string

Arguments#

Returns#

tecs.platform.time.dayOfYear Static#

Returns the zero-based day within a calendar year.

function tecs.platform.time.dayOfYear(
    year: integer, month: integer, day: integer
): integer, string

Arguments#

Returns#

tecs.platform.time.daysInMonth Static#

Returns the number of days in a calendar month.

function tecs.platform.time.daysInMonth(
    year: integer, month: integer
): integer, string

Arguments#

Returns#

tecs.platform.time.delay Static#

Blocks the calling thread for at least a number of milliseconds.

OS scheduling may make the delay longer. Do not call this from a frame.

function tecs.platform.time.delay(milliseconds: integer)

Arguments#

Returns#

None.

tecs.platform.time.delayNanoseconds Static#

Blocks the calling thread for at least a number of nanoseconds.

OS scheduling may make the delay longer. Do not call this from a frame.

function tecs.platform.time.delayNanoseconds(nanoseconds: number)

Arguments#

Returns#

None.

tecs.platform.time.delayPrecise Static#

Blocks while approaching a nanosecond delay as closely as possible.

SDL may busy wait, and OS scheduling may still make the delay longer. Do not call this from a frame.

function tecs.platform.time.delayPrecise(nanoseconds: number)

Arguments#

Returns#

None.

tecs.platform.time.fromDateTime Static#

Converts calendar fields to an exact Unix timestamp.

utcOffset defaults to zero. hour, minute, second, and nanosecond also default to zero. SDL ignores dayOfWeek.

function tecs.platform.time.fromDateTime(
    dateTime: DateTime
): Timestamp, string

Arguments#

Returns#

tecs.platform.time.fromWindowsTime Static#

Converts a Windows FILETIME to an exact Unix timestamp.

SDL clamps a FILETIME outside its roughly 1677 through 2262 range. The resulting nanoseconds are a multiple of 100.

function tecs.platform.time.fromWindowsTime(
    windowsTime: WindowsTime
): Timestamp

Arguments#

Returns#

tecs.platform.time.localePreferences Static#

Reads the current locale's preferred date order and clock layout.

The platform query may be slow and preferences may change outside the process. A caller that needs the result frequently should cache it and refresh deliberately.

function tecs.platform.time.localePreferences(): LocalePreferences, string

Arguments#

None.

Returns#

tecs.platform.time.microsecondsToNanoseconds Static#

Converts whole microseconds to nanoseconds.

function tecs.platform.time.microsecondsToNanoseconds(
    microseconds: integer
): number

Arguments#

Returns#

tecs.platform.time.millisecondsToNanoseconds Static#

Converts whole milliseconds to nanoseconds.

function tecs.platform.time.millisecondsToNanoseconds(
    milliseconds: integer
): number

Arguments#

Returns#

tecs.platform.time.nanosecondsToMicroseconds Static#

Converts nanoseconds to microseconds.

function tecs.platform.time.nanosecondsToMicroseconds(
    nanoseconds: number
): number

Arguments#

Returns#

tecs.platform.time.nanosecondsToMilliseconds Static#

Converts nanoseconds to milliseconds.

function tecs.platform.time.nanosecondsToMilliseconds(
    nanoseconds: number
): number

Arguments#

Returns#

tecs.platform.time.nanosecondsToSeconds Static#

Converts nanoseconds to seconds.

function tecs.platform.time.nanosecondsToSeconds(
    nanoseconds: number
): number

Arguments#

Returns#

tecs.platform.time.now Static#

Reads the monotonic counter in seconds. Not affected by the provider.

function tecs.platform.time.now(): number

Arguments#

None.

Returns#

tecs.platform.time.performanceCounter Static#

Reads the platform's raw high-resolution counter.

Prefer now for intervals. A raw counter may lose low bits when converted from SDL's unsigned 64-bit value to a Lua number.

function tecs.platform.time.performanceCounter(): number

Arguments#

None.

Returns#

tecs.platform.time.performanceFrequency Static#

Reads the frequency of the platform's high-resolution counter.

function tecs.platform.time.performanceFrequency(): number

Arguments#

None.

Returns#

tecs.platform.time.provider Static#

Caller-writable. Installs a replay hook that receives the measured frame delta. Returning a number replaces it; returning nil keeps it.

function tecs.platform.time.provider(realDt: number): number

Arguments#

Returns#

tecs.platform.time.reset Static#

Resets the baseline so the next step measures from now. Called after startup so the first frame's dt excludes load time.

function tecs.platform.time.reset()

Arguments#

None.

Returns#

None.

tecs.platform.time.secondsToNanoseconds Static#

Converts whole seconds to nanoseconds.

function tecs.platform.time.secondsToNanoseconds(
    seconds: integer
): number

Arguments#

Returns#

tecs.platform.time.step Static#

Advances one frame and returns the dt the world should receive.

Clamps to maxDelta, then offers the value to provider.

function tecs.platform.time.step(): number

Arguments#

None.

Returns#

tecs.platform.time.ticksMilliseconds Static#

Reads milliseconds elapsed since SDL initialized.

function tecs.platform.time.ticksMilliseconds(): number

Arguments#

None.

Returns#

tecs.platform.time.ticksNanoseconds Static#

Reads nanoseconds elapsed since SDL initialized.

A Lua number stops distinguishing adjacent nanoseconds after about 104 days, while elapsed differences remain useful at the precision its magnitude permits.

function tecs.platform.time.ticksNanoseconds(): number

Arguments#

None.

Returns#

tecs.platform.time.toDateTime Static#

Converts an exact Unix timestamp to calendar fields.

function tecs.platform.time.toDateTime(
    timestamp: Timestamp, localTime: boolean
): DateTime, string

Arguments#

Returns#

tecs.platform.time.toWindowsTime Static#

Converts an exact Unix timestamp to a Windows FILETIME.

FILETIME counts 100-nanosecond intervals since 1601, so this conversion discards the last two decimal digits of nanosecond.

function tecs.platform.time.toWindowsTime(
    timestamp: Timestamp
): WindowsTime, string

Arguments#

Returns#

tecs.platform.time.wallNow Static#

Reads the adjustable realtime clock.

function tecs.platform.time.wallNow(): Timestamp, string

Arguments#

None.

Returns#

Values#

tecs.platform.time.maxDelta variable#

Caller-writable. Sets the longest frame delta in seconds that step returns.

tecs.platform.time.maxDelta: number

tecs.platform.time.microsecondsPerSecond variable#

Read-only. Reports the number of microseconds in one second.

tecs.platform.time.microsecondsPerSecond: integer

tecs.platform.time.millisecondsPerSecond variable#

Read-only. Reports the number of milliseconds in one second.

tecs.platform.time.millisecondsPerSecond: integer

tecs.platform.time.nanosecondsPerMicrosecond variable#

Read-only. Reports the number of nanoseconds in one microsecond.

tecs.platform.time.nanosecondsPerMicrosecond: integer

tecs.platform.time.nanosecondsPerMillisecond variable#

Read-only. Reports the number of nanoseconds in one millisecond.

tecs.platform.time.nanosecondsPerMillisecond: integer

tecs.platform.time.nanosecondsPerSecond variable#

Read-only. Reports the number of nanoseconds in one second.

tecs.platform.time.nanosecondsPerSecond: integer

tecs.platform.time.nominal variable#

Caller-writable. Sets the nominal frame delta in seconds. The application initializes it from the target frame rate.

tecs.platform.time.nominal: number