Legacy Document

Inside Macintosh: Processes

Chapter 4 - Vertical Retrace Manager / About the Vertical Retrace Manager

The VBL Task Record

You install a VBL task by passing the Vertical Retrace Manager the address of a VBL task record, which holds information about your VBL task. This information includes the address of the procedure the Vertical Retrace Manager is to execute at interrupt time and the number of interrupts before it should next execute the task. The VBLTask data type defines a VBL task record.

TYPE VBLTask = 
RECORD
   qLink:    QElemPtr;   {next entry in vertical retrace queue}
   qType:    Integer;    {queue type}
   vblAddr:  ProcPtr;    {pointer to task procedure}
   vblCount: Integer;    {interrupts until next execution}
   vblPhase: Integer;    {task phase}
END;

Your application needs to fill in only the qType, vblAddr, vblCount, and vblPhase fields of the VBL task record. The qLink field, which contains a pointer to the next entry in the VBL task's vertical retrace queue, is set by the Vertical Retrace Manager when you install the task by calling VInstall or SlotVInstall. Your application does not need to set up the qLink field.

The Vertical Retrace Manager installs your VBL task record into the appropriate VBL queue. A vertical retrace queue is a standard operating-system queue.

Note

For more information about the structure of operating-system queues, see the chapter "Queue Utilities" in Inside Macintosh: Operating System Utilities. ·

You must set the qType field to ORD(vType) before you install the task. This specifies that the task's queue is a vertical retrace queue and not some other type of operating-system queue.

The vblAddr field holds a pointer to the procedure that the Vertical Retrace Manager is to execute.

When installing a VBL task, you specify, in the vblCount field, the number of interrupts before the routine first executes. The Vertical Retrace Manager lowers this number by 1 during each interrupt. If decrementing vblCount produces a value of 0, the Vertical Retrace Manager executes the procedure specified in the task record's vblAddr field. If you want the procedure to be executed again, that procedure is responsible for resetting the value of the vblCount field to the desired value.

If you do not want the Vertical Retrace Manager to execute the task again, your task should leave the value of vblCount at 0. Setting the vblCount field to 0 is one way of disabling a task. (A more common approach is to remove the task record from its queue by calling VRemove or SlotVRemove, but this should not be done by the VBL task itself.) Note that if you set vblCount to 0 when installing a VBL task, the task will never execute. If you want a task to execute immediately upon installation, set vblCount to 1.

The vblPhase field specifies the task's phase count, indicating which interrupts are to trigger the execution of the VBL task. You can set two VBL tasks installed at the same time and scheduled for execution after the same number of interrupts out of phase with one another--that is, executed during different interrupts--by specifying different phase counts for each task. Unless you add many tasks to a VBL queue at one time, you can usually set vblPhase to 0.