Syncframe

From codeTank

Contents 1 Description 2 Arguments 3 Returns 4 Example 5 Real-World Example 6 See Also

Description

syncframe will attempt to synchronize the program to a certain frequency, by pausing the program if the previous call took place in less time than the specified time frame.

It might sound a little complicated, but it's much easier to understand when you consider a game loop. In a game loop, you might want the frame rate to be fixed at 30 frames per second. To achieve this, you would call syncframe(0.033) inside the main loop (you calculate 0.033 from 1 / 30). When the game loops around, syncframe will check to see if it's taken 0.033 seconds to get called in succession. If it's taken longer than 0.033 seconds, then it returns false, and exits immediately. If it's taken shorter than 0.033 seconds, then it pauses for the remaining amount (so the total time is 0.033 seconds), and returns true.

syncframe was created to perform this high-precision task. If implemented in Lua code, the delays caused by processing the script would interfere with the timing precision. By implementing it in the Brain Damage library, it's ensured to run as precise and efficient as possible, ensuring a more stable frame rate.

Arguments

syncframe takes one argument - the number of seconds it takes per frame. If you want to achieve a certain frames per second, then simply invert that number to get the seconds per frame (seconds_per_frame = 1 / frames_per_second).

Please be aware that seconds_per_frame does not have to be constant. Every time you call syncframe, it checks to see if the previous call happened less than seconds_per_frame seconds ago. If it did, then it delays the difference, and returns true. If it didn't, then it returns false immediately.

The first call to syncframe will measure the difference in relation to the start of the program. Each successive call after that measures the difference in relation to the previous syncframe call.

Please note that syncframe is limited to a millisecond resolution. The smallest value that makes sense would be 0.001, because anything smaller would be simplified to 0 (which would always make syncframe return false).

Returns

syncframe will return true if it is successful at maintaining the frame rate, and false if it fails. More accurately, it returns true if a delay had to be added, and false if no delay was added. You can ignore this value if you want, or you can adjust your main loop in order to speed up or slow down dynamically according to this value.

Example

If you run this code, you will notice that it quickly climbs in the beginning, and then starts to hover around a particular value, until it exits. This shows how syncframe can be used to figure out how much work we can get done to maintain a frame rate (on my 2.8GHz machine, this code settled on around 7500 dummy tables).

Real-World Example

This is how you would use syncframe in a real game:

See Also

• sleep
• window.settimer
• ontimer
• os.clock