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.