|
Banjo API 1.1.0-alpha
Low-level C99 game development API
|
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) |
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:
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.
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).
stopwatch.c and time.c for runnable demos. | 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.
| Data Fields | ||
|---|---|---|
| uint64_t | last_tick | Time of last step/checkpoint. |
| uint64_t | start_counter | Time when stopwatch was last reset. |
| 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.
| 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.
| stopwatch | Pointer to the stopwatch, or NULL, which does nothing. |
| 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.
| void bj_sleep | ( | int | milliseconds | ) |
| 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.
| milliseconds | Number of milliseconds to sleep. A negative number returns at once. |
Referenced by main().
| double bj_step_delay_stopwatch | ( | struct bj_stopwatch * | 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.
| stopwatch | Pointer to the stopwatch, or NULL, which gives 0. |
| double bj_stopwatch_delay | ( | const struct bj_stopwatch * | stopwatch | ) |
| double bj_stopwatch_elapsed | ( | const struct bj_stopwatch * | stopwatch | ) |
| 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.
| stopwatch | Pointer to the stopwatch, or NULL, which gives 0. |
| 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.
| stopwatch | Pointer to the stopwatch, or NULL, which gives 0. |
Referenced by main().
| 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.
| 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.