Time Measurement & Profiling

Table of Contents

• High precision measurement
• Low precision measurement
• Timeout values
• Notes

FPL provides a couple of functions for measuring elapsed time, used for profiling, delta time calculations and timeouts.

Note

These functions are meant for delta measurements only. They are not tied to a calendar date and the starting point is undefined (OS start, system start, etc.).
To query the current calendar date and time, see Query Date & Time instead.

High precision measurement

For the most precise time measurement, use fplTimestampQuery() to capture a fplTimestamp.
A fplTimestamp is an opaque value - it only has meaning when compared against another timestamp.

To get the elapsed time between two timestamps, call fplTimestampElapsed() . It returns the delta in seconds as fplSeconds (a 64-bit double).

// Capture the starting timestamp
fplTimestamp start = fplTimestampQuery();
 
// ... do some work ...
 
// Capture the finishing timestamp and compute the delta
fplTimestamp finish = fplTimestampQuery();
fplSeconds elapsed = fplTimestampElapsed(start, finish);
 
fplConsoleFormatOut("Work took %f seconds\n", elapsed);

This is the recommended way to compute frame delta times in a game loop:

fplTimestamp last = fplTimestampQuery();
while (running) {
    fplTimestamp now = fplTimestampQuery();
    fplSeconds deltaTime = fplTimestampElapsed(last, now);
    last = now;
 
    // Update the game using deltaTime
}

Low precision measurement

For simple, less precise measurements you can use fplMillisecondsQuery() .
It returns the current system clock in milliseconds as fplMilliseconds (a 64-bit unsigned integer), counted from some fixed but undefined starting point.

fplMilliseconds start = fplMillisecondsQuery();
 
// ... do some work ...
 
fplMilliseconds elapsed = fplMillisecondsQuery() - start;
fplConsoleFormatOut("Work took %llu milliseconds\n", elapsed);

Timeout values

A number of FPL functions (mutexes, signals, semaphores, etc.) accept a timeout argument expressed as a fplTimeoutValue.
This is a timeout in milliseconds. To wait indefinitely, pass the FPL_TIMEOUT_INFINITE constant.

// Wait at most 500 milliseconds
fplTimeoutValue timeout = 500;
 
// Wait forever
fplTimeoutValue infinite = FPL_TIMEOUT_INFINITE;

Notes

• Use fplTimestampQuery() / fplTimestampElapsed() when precision matters (profiling, frame delta time).
• Use fplMillisecondsQuery() for simple, coarse measurements where high precision is not required.
• A fplTimestamp value is platform-dependent and must never be interpreted directly - only compare it with fplTimestampElapsed() .
• The starting point of both clocks is undefined, so only the difference between two queries is meaningful.