====== Display Timing Calls ======


----

If you have other task activities that you want to coordinate with the frame display, you can use the timer device to inform the task when a vertical blank occurs. The task can enter a wait state until it receives notice of the vertical blank, or it can continue execution while it waits.

===== Getting a VBL IOReq =====

To use VBL timing calls, a task must first have an IOReq to communicate with the timer. To get one, use this convenience call:

''%%%%''

''%%Item GetVBLIOReq( void )%%''\\


It accepts no arguments, and when it executes, it creates an IOReq for the timer. It returns the item number of that IOReq if successful, or a negative value (an error code) if unsuccessful. Save the item number for use with the VBL timing calls.

===== Waiting for a VBL Frame =====

Once a task has a VBL IOReq, it can call on the timer to wait for a vertical blank. To do so, it uses this call:

''%%%%''

''%%Err WaitVBL( Item ioreq, uint32 numfields )%%''\\


It accepts the item number of the VBL IOReq and the number of vertical blank fields the task should wait for before becoming active again. It returns a zero if successful, and a negative value (an error code) if unsuccessful.

To allow a task to continue execution while the timer processes the IOReq sent to it, use this call:

''%%%%''

''%%Err WaitVBLDefer( Item ioreq, uint32 numfields )%%''\\


It accepts the same arguments as ''%%WaitVBL()%%'', but, when executed, allows the task to continue execution while the IOReq is outstanding. If the task wants to be notified of the timing call's completion, use the ''%%WaitIO()%%'' call.