Time

Data Structures
struct	bj_stopwatch

Functions
uint64_t	bj_get_time (void)
void	bj_sleep (int milliseconds)
double	bj_run_time (void)
uint64_t	bj_time_counter (void)
uint64_t	bj_time_frequency (void)
void	bj_reset_stopwatch (struct bj_stopwatch *stopwatch)
void	bj_step_stopwatch (struct bj_stopwatch *stopwatch)
double	bj_stopwatch_elapsed (const struct bj_stopwatch *stopwatch)
double	bj_stopwatch_delay (const struct bj_stopwatch *stopwatch)
double	bj_step_delay_stopwatch (struct bj_stopwatch *stopwatch)

Detailed Description

Three kinds of time: what time is it, how long since X, and please pause for a bit.

Programs need to talk about time in three different ways, and Banjo gives you a small helper for each.

"What time is it now?": bj_get_time returns the number of seconds since 1970-01-01 (the so-called Unix epoch). This is fine for stamping log lines or saving "last opened" timestamps, but it can jump backwards (e.g. if the user adjusts their system clock) and so it's not the right tool for measuring intervals.

"How long since X?": for that, use a monotonic counter that only ever moves forward. Two options:

• bj_run_time gives you seconds (as a double) since bj_begin was called. Easy and good enough for most game work.
• bj_time_counter returns platform-dependent integer ticks; divide by bj_time_frequency (ticks per second) to get seconds. Use this when you need sub-millisecond resolution.

For the very common pattern "how much time elapsed since I last asked?" (what game programmers call delta time) Banjo gives you bj_stopwatch. It's a tiny struct that remembers two timestamps: the reset point and the last step. Call bj_step_delay_stopwatch once per frame and it returns the seconds since the previous call and updates its internal "last step" timestamp in one go:

struct bj_stopwatch sw = {0};   // zero-init is a valid resetable state
while (!bj_should_close_window(window)) {
    const double dt = bj_step_delay_stopwatch(&sw);  // seconds since last frame
    update_world(dt);
    render();
    bj_dispatch_events();
    bj_sleep(15);
}

This dt is what your physics and animation code should multiply velocities by, that way the game runs at the same speed whether each frame takes 1 ms or 30 ms. The pong.c capstone tutorial walks through this pattern.

"Please pause for a bit": bj_sleep takes a number of milliseconds and returns when at least that much real time has passed. The "at least" matters: the OS may sleep you longer than requested. Don't use bj_sleep to precisely pace a frame rate (you'll get jitter); use it to yield the CPU between frames of an otherwise-tight loop so you stop pegging a core for no reason.

See also

stopwatch.c and time.c for runnable demos.

---

Data Structure Documentation

bj_stopwatch

struct bj_stopwatch

Structure representing a simple stopwatch.

A stopwatch records the time it was last reset and the time of the last step. It computes elapsed time since reset, and delay since the last step. A zero-initialised stopwatch is valid and will auto-reset on first use.

Examples

pong.c, and stopwatch.c.

Definition at line 149 of file time.h.

Data Fields
uint64_t	last_tick	Time of last step/checkpoint.
uint64_t	start_counter	Time when stopwatch was last reset.

Function Documentation

bj_get_time()

uint64_t bj_get_time

(

void

)

Get the current system time in seconds since the Unix epoch.

The returned value is the number of whole seconds elapsed since 1970-01-01 00:00:00 UTC (Unix epoch). This is the standard "wall-clock" system time.

Returns

Seconds since Unix epoch

Examples

random.c.

Referenced by main().

bj_reset_stopwatch()

void bj_reset_stopwatch

(

struct bj_stopwatch *

stopwatch

)

Resets the stopwatch to the current time.

Records the current time as both the reset point and last step. Clears any prior timing information.

Parameters

stopwatch

Pointer to the stopwatch.

See also

bj_step_stopwatch, bj_stopwatch_elapsed, bj_stopwatch_delay

bj_run_time()

double bj_run_time

(

void

)

Gets the current time in seconds since Banjo initialisation.

This function returns the time in seconds since bj_begin was called. It is suitable for general-purpose timing, but not for high-resolution use.

Returns

The current time in seconds.

See also

bj_time_counter, bj_time_frequency

Examples

audio_pcm.c, shaders.c, and time.c.

Referenced by main(), on_draw(), and step().

bj_sleep()

void bj_sleep

(

int

milliseconds

)

Suspends the current thread for a specified duration.

This function puts the current thread to sleep for at least the specified number of milliseconds. The actual sleep duration may be longer depending on the system.

Parameters

milliseconds

Number of milliseconds to sleep.

See also

bj_get_time, bj_time_counter, bj_time_frequency

Examples

net_tcp_nonblocking.c, net_udp_broadcast_send.c, stopwatch.c, and time.c.

Referenced by main().

bj_step_delay_stopwatch()

double bj_step_delay_stopwatch

(

struct bj_stopwatch *

stopwatch

)

Steps the stopwatch and returns the delay since the previous step.

Equivalent to calling bj_stopwatch_delay followed by bj_step_stopwatch, but more efficient and concise.

Parameters

stopwatch

Pointer to the stopwatch.

Returns

Time in seconds since the previous step.

See also

bj_step_stopwatch, bj_stopwatch_delay

Examples

pong.c.

Referenced by step().

bj_step_stopwatch()

void bj_step_stopwatch

(

struct bj_stopwatch *

stopwatch

)

Records a step/checkpoint in time.

Updates the internal step timestamp. This does not affect the reset time, but is used to measure time deltas via bj_stopwatch_delay or bj_step_delay_stopwatch.

Parameters

stopwatch

Pointer to the stopwatch.

See also

bj_step_delay_stopwatch

Examples

stopwatch.c.

Referenced by main().

bj_stopwatch_delay()

double bj_stopwatch_delay

(

const struct bj_stopwatch *

stopwatch

)

Returns the time in seconds since the last step.

If the stopwatch has never been used, it will be reset automatically on first use. This function does not modify the stopwatch state.

Parameters

stopwatch

Pointer to the stopwatch.

Returns

Time in seconds since the last step.

See also

bj_step_stopwatch

Examples

stopwatch.c.

Referenced by main().

bj_stopwatch_elapsed()

double bj_stopwatch_elapsed

(

const struct bj_stopwatch *

stopwatch

)

Returns the elapsed time in seconds since the stopwatch was reset.

If the stopwatch has never been explicitly reset, it will be reset automatically on first use.

Parameters

stopwatch

Pointer to the stopwatch.

Returns

Elapsed time in seconds.

See also

bj_reset_stopwatch

Examples

stopwatch.c.

Referenced by main().

bj_time_counter()

uint64_t bj_time_counter

(

void

)

Returns the current high-resolution time counter.

This value is in platform-dependent ticks and is suitable for precise timing and performance measurements. To convert ticks to seconds, divide by the result of bj_time_frequency.

Returns

The current time counter in ticks.

See also

bj_get_time, bj_time_frequency

bj_time_frequency()

uint64_t bj_time_frequency

(

void

)

Returns the frequency of the high-resolution counter.

This is the number of ticks per second returned by bj_time_counter. Use this to convert tick counts to seconds.

Returns

Ticks per second (frequency).

See also

bj_time_counter