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:
- @MAIN
- GOSUB @DOCALCULATIONS
- VSYNC 1
- GCLS
- GOSUB @DRAWGAME
- GOTO @MAIN
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. We call it a "target" framerate because if you are doing too much processing or drawing too many graphics it may simply not be possible to meet the target framerate. 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. More on this below.
To get the best performance out of Petit, it's important to handle synching, drawing, and clearing in the correct order. The order given above is optimal; rearranging the sync, clear, or draw calls will make it harder for Petit to properly draw the image every frame and might cause increased flickering or other strange behaviors. Thanks to SquaredFingers for pointing this out.
The difference between VSYNC and WAIT[]
Thanks to DiscordStew and SquaredFingers, who helped explain the technical details in the comments below. I use a simplified explanation here.
The difference between VSYNC and WAIT is not explained well in the documentation; it is a seemingly subtle difference but can have important implications in the performance of your application.
As a little technical background, the image you see on the screen is actually drawn top-to-bottom every frame. Normally this happens too fast to be noticeable, but we can detect visual anomalies, such as tearing, if the image we are drawing changes before the DS is done drawing it to the screen.
VSYNC waits until the very beginning of the next draw phase, which helps maintain a consistent framerate and prevent visual problems. WAIT, on the other hand, waits for exactly one frame - so if you happen to call WAIT 1 in the middle of drawing a frame, it will wait until the middle of the next frame.
So what does this mean to our applications? While testing the difference between VSYNC and WAIT on an application that does a lot of calculations every frame, I observed some interesting behavior. When I used VSYNC 1 in the main loop, the application would run at a consistent 60fps but wouldn't finish drawing the image every frame, causing flickering and other problems. When I used WAIT 1, the whole image would get drawn every frame, but the actual framerate would change depending on how much work was being done; if it couldn't draw the whole scene in time, the whole app would slow down.
So WAIT X caused a lower effective framerate (with less flickering) than VSYNC X when I was drawing a lot of graphics, but a higher effective framerate than VSYNC when drawing little or nothing. Keep in mind that my test only involved drawing graphics with GLINE; the behavior may be different when sprites, backgrounds, etc are involved. Still, if you are having problems with flickering, it might be worth comparing the results you get from VSYNC with those from WAIT. If these results are consistent, it may be better to use VSYNC if you are more concerned with a consistent framerate, and WAIT if you're more concerned with eliminating flicker and won't mind occasional changes in framerate.