Legacy Document

Inside Macintosh: Processes

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

Installing a VBL Task

For any particular VBL task, you need to decide whether to install it as a system-based VBL task or as a slot-based VBL task. You need to install a task as a slot-based VBL task only if the execution of the task needs to be synchronized with the retrace rate of a particular external monitor. If the task performs no processing that is likely to affect the appearance of the screen or that depends on the state of an external monitor, it is probably safe to install the task as a system-based VBL task.

WARNING

If you do decide that the execution of some VBL task needs to be synchronized with the retrace rate of a monitor, you should first check that the SlotVInstall function is available in the operating environment. You can do this by calling the TrapAvailable function defined in the chapter "Gestalt Manager" in Inside Macintosh: Operating System Utilities. If you call SlotVInstall and it is not available, your application will crash. ·

If you are uncertain whether to install a task as a system-based or as a slot-based VBL task, you should first install it as a system-based task (by calling VInstall). Then test your application on a modular Macintosh computer with an external monitor whose refresh rate is different from the refresh rate on a compact Macintosh computer (approximately 60.15 Hz). If any screen updating that occurs as a result of processing done by your VBL task has an unacceptable appearance, you probably need to install the task as a slot-based VBL task (by calling SlotVInstall). Remember, however, to check whether SlotVInstall is available before you call it; if it isn't available, call VInstall. You can determine whether SlotVInstall is available by calling the SlotRoutinesAvailable function defined in Listing 4-1.

Listing 4-1 Checking whether you can use slot-based VBL routines

FUNCTION SlotRoutinesAvailable: Boolean;
CONST
   _SlotVInstall = $A06F;
BEGIN
   SlotRoutinesAvailable := TrapAvailable(_SlotVInstall);
END;

If the slot-based routines are available and you want to use them, you need to know the slot number of the video device to whose retrace the VBL task is to be synchronized. Listing 4-2 illustrates a way to find the slot number of the main graphics device. To access the device control entry for the main graphics device, you must first find the device's reference number. Then you can cast the device control entry into type AuxDCEHandle and access the slot number directly. You can use a similar technique to find the slot number of some other graphics device.

Listing 4-2 Determining the slot number of the main graphics device

FUNCTION MainSlotNumber: Integer;
VAR
   mainDeviceRefNum: Integer;    {number of main graphics device}
BEGIN
   mainDeviceRefNum := GetMainDevice^^.gdRefNum;
   MainSlotNumber := 
      AuxDCEHandle(GetDCtlEntry(mainDeviceRefNum))^^.dCtlSlot;
END;

Note

For the sake of simplicity, the remainder of this chapter illustrates how to use the Vertical Retrace Manager to handle system-based VBL tasks only. Virtually all of the techniques shown here, however, can be used in connection with slot-based VBL tasks as well. ·

The InstallVBL function defined in Listing 4-3 shows how to fill in a VBL task record and install it in the system-based VBL queue. It assumes that the task record gMyVBLTask is a global variable of type VBLTask and that you have already defined the procedure DoVBL, the actual VBL task. That procedure is subject to all of the usual limitations on VBL and other interrupt tasks. Also, if DoVBL is to be executed recurrently, it must reset the vblCount field of the task record each time it is executed. The next section, "Accessing a Task Record at Interrupt Time," describes how to do this.

Listing 4-3 Initializing and installing a task record

FUNCTION InstallVBL: OSErr;
CONST
   kInterval = 6;                {frequency in interrupts}
BEGIN
   WITH gMyVBLTask DO            {initialize the VBL task}
      BEGIN
         qType := ORD(vType);    {set queue type}
         vblAddr := @DoVBL;      {set address of VBL task}
         vblCount := kInterval;  {set task frequency}
         vblPhase := 0;          {no phase}
      END;

   InstallVBL := VInstall(@gMyVBLTask);
END;