Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
Time

Data Structures

struct  bj_stopwatch

Functions

uint64_t bj_get_time (void)
void bj_sleep_ms (int milliseconds)
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)
double bj_step_stopwatch (struct bj_stopwatch *stopwatch)
double bj_stopwatch_total (const struct bj_stopwatch *stopwatch)
double bj_stopwatch_elapsed (const struct bj_stopwatch *stopwatch)
double bj_stopwatch_split (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_stopwatch once per frame: it records a new step and returns the seconds since the previous one, in one go.

struct bj_stopwatch sw = {0}; // zero-init is a valid resetable state
/* in the step callback, which bj_run_app paces: *‍/
const double dt = bj_step_stopwatch(&sw); // seconds since last frame
update_world(dt);
render();
bj_dispatch_events();
Structure representing a simple stopwatch.
Definition time.h:153

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_ms 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_ms to pace a frame rate: bj_run_app does that, sleeping off only what is left of each frame (see bj_set_frame_rate).

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 152 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
maze.c, and random.c.

Referenced by main(), and setup().

◆ 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
stopwatchPointer to the stopwatch, or NULL, which does nothing.
See also
bj_step_stopwatch, bj_stopwatch_total, bj_stopwatch_split

◆ 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. Before bj_begin, the clocks start on their first use, from which this time then counts, and bj_begin starts it again from 0. 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)
Deprecated
Renamed to bj_sleep_ms. Removed in 2.0.

◆ bj_sleep_ms()

void bj_sleep_ms ( int milliseconds)

Suspend the current thread for at least the given number of milliseconds.

The actual sleep may be longer than requested, depending on the OS scheduler.

Parameters
millisecondsNumber of milliseconds to sleep. A negative number returns at once.
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)
Deprecated
bj_step_stopwatch now returns the split itself; call that. Removed in 2.0.

◆ bj_step_stopwatch()

double bj_step_stopwatch ( struct bj_stopwatch * stopwatch)

Record a step and return the seconds since the previous step.

Advances the internal step timestamp to now, without touching the reset point, and returns the interval since the step before this one. Call it once per frame to get delta time. A zero-initialised stopwatch resets itself on the first call and returns 0.

Parameters
stopwatchPointer to the stopwatch, or NULL, which gives 0.
Returns
Seconds since the previous step.
See also
bj_stopwatch_split, bj_stopwatch_total
Examples
pong.c, and stopwatch.c.

Referenced by main(), and step().

◆ bj_stopwatch_delay()

double bj_stopwatch_delay ( const struct bj_stopwatch * stopwatch)
Deprecated
Renamed to bj_stopwatch_split. Removed in 2.0.

◆ bj_stopwatch_elapsed()

double bj_stopwatch_elapsed ( const struct bj_stopwatch * stopwatch)
Deprecated
Renamed to bj_stopwatch_total. Removed in 2.0.

◆ bj_stopwatch_split()

double bj_stopwatch_split ( const struct bj_stopwatch * stopwatch)

Return the seconds since the last step, without recording one.

A stopwatch never reset or stepped reads 0. Does not modify the stopwatch; use bj_step_stopwatch to also advance the step point.

Parameters
stopwatchPointer to the stopwatch, or NULL, which gives 0.
Returns
Seconds since the last step.
See also
bj_step_stopwatch, bj_stopwatch_total

◆ bj_stopwatch_total()

double bj_stopwatch_total ( const struct bj_stopwatch * stopwatch)

Return the seconds elapsed since the stopwatch was last reset.

A stopwatch never reset or stepped reads 0. Does not modify the stopwatch.

Parameters
stopwatchPointer to the stopwatch, or NULL, which gives 0.
Returns
Seconds since the last reset.
See also
bj_reset_stopwatch, bj_stopwatch_split
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