VSYNC vs WAIT

VSYNC and WAIT are both commands that can be used to control the framerate of a Petit application, or add pauses. Although similar, they have subtly different purposes.

Both commands are followed by an integer that represents a delay in frames. A frame is 1/60th of a second, so VSYNC 1/WAIT 1 would represent a delay of 1/60th of a second, while VSYNC 60/WAIT 60 would represent a delay of 1 second.

Usage
There are two primary use-cases for VSYNC or WAIT. The first is to simply introduce a pause in an application; for example, if the player dies, you might want to freeze the screen for a half second before their character falls offscreen. You could use WAIT 30 to add this delay.

Either command can also be used in a main loop, which is a continuously running loop in a real-time application. In the main loop, VSYNC or WAIT would be used to control the framerate of the application. For example:

When we say VSYNC X or WAIT X in our main loop, Petit tries to maintain a framerate of 60/x frames per second. In the above example, the target framerate would be 60fps. VSYNC 2 would give a target framerate of 30fps, and so on. Reducing your target framerate gives Petit more time to draw each frame, which may be necessary if your application has a lot going on each frame.

The difference between VSYNC and WAIT
The difference between VSYNC and WAIT is how Petit behaves if it is not done drawing the current frame before the next frame starts.

VSYNC prioritizes consistent speed - if it isn't done drawing all of your graphics before the next frame starts, it will discard whatever was left and go on to the next frame. This means that if your target framerate is too high for your application, the graphics will flicker and some may periodically disappear and reappear depending on whether there is time to draw them before the next frame. However, your application will maintain a fairly constant effective framerate. Simply put, if your target FPS is 60, Petit will try its best to run 60fps whether or not it finishes drawing the graphics every frame.

WAIT prioritizes drawing everything - Petit will try to match your target framerate when it can, but if you are doing too much, your effective framerate will be reduced. What this means is that your graphics will probably always all be drawn, but your application will slow down if you are trying to draw more graphics than you can draw in the target framerate. WAIT can still experience minor flickering but nowhere near as much as VSYNC.

Keep in mind that the speed that your graphics are drawn depends not only on how many graphics are drawn, but how complex your code is. If you are doing very complex calculations every frame this can also reduce how much you have time to draw every frame. The order that your code executes can also be a factor - you might see if your game runs more smoothly if you draw your graphics before or after doing other calculations.

Which command is the correct one depends on your application. If you want to keep a smooth framerate and don't mind some flickering, VSYNC is probably the better choice. If you want to make sure the whole scene gets drawn every frame and don't care if the framerate drops here and there, WAIT is probably the better choice.