Blitz3D+ Command Reference

VWait [frames]

Parameters

frames (optional) - number of frames to wait; 1 (default). The runtime always waits for a single vertical blank, so this value has no effect.

Description

Waits for the monitor's next vertical blank.

A vertical blank is the brief moment between the display finishing one refresh and starting the next. Swapping what is on screen during that gap is what stops a frame tearing in half. VWait parks your program until that moment arrives.

The difference between this and letting Flip wait is which side does the waiting. Flip True asks the graphics card to hold the frame until the blank; VWait stops your own code. Some drivers and desktop compositors let the user force vertical sync off, which quietly disables Flip's wait - so the traditional belt-and-braces pattern is "VWait : Flip False", which paces the loop from your side regardless of the driver setting.

Note that the frames value is accepted for compatibility but ignored: each call waits for exactly one blank. To wait longer, call it more than once.

Do not combine VWait with a CreateTimer loop; the two pacing mechanisms will fight and you will get uneven frames. Pick whichever suits the game.

See also: Flip, CreateTimer, WaitTimer, Delay, ScanLine.

Example

; VWait Example
; -------------

Graphics 640,480,0,2
SetBuffer BackBuffer()

; VWait makes the CPU wait for the monitor's next vertical blank, so
; the loop runs once per screen refresh. It is often paired with
; "Flip False": VWait does the waiting, then Flip False shows the
; frame immediately without waiting again.

use_vwait=1

While Not KeyDown(1)

    Cls

    ; Space toggles VWait on and off
    If KeyHit(57) Then use_vwait=1-use_vwait

    ; One step per loop: without VWait the loop is unthrottled
    ; and the square streaks across the screen
    x=(x+4) Mod 640
    Rect x,220,40,40,True

    Text 0,0,"Space: toggle VWait   Esc: exit"
    If use_vwait Then
        Text 0,20,"VWait ON: one loop per screen refresh"
    Else
        Text 0,20,"VWait OFF: loop runs unthrottled"
    EndIf

    ; The documented command: wait for the vertical blank
    If use_vwait Then VWait

    Flip False

Wend

End

Index