VBL Task Animation
Volume Number: 5
Issue Number: 2
Column Tag: C Workshop
Related Info: Vert. Retrace Mgr
By Dick C handler, Ben Lomond, CA
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
Dick C handler is a Software Engineer at Apple Computer. His major interests are
graphics and networks. This is his first article for MacTutor. In this article, Dick
shows us how to do some cute animation of fingers drumming on the desktop!
What is a VBL task? A VBL or Vertical BLanking interrupt occurs when the beam
of the display tube returns to the top of the screen. This happens on a regular interval
(60 times a second). This is a convenient time to take care of recurrent system tasks
such as: increment tickcount, check stack/heap boundries for collision, check and
update cursor for movement, etc.
The information for executing each of these tasks is placed in a structure called
appropriately enough a ‘VBLTask’ and is installed in the vertical retrace queue. Once
this is done the system automatically executes the task at a regular interval.
You can place your own tasks on the queue for the system to execute. VBL tasks
are a marvelous way of doing some types of graphic animation for the following
reasons:
° You don’t have to worry about the speed of your animation on a faster/slower
machine, the VBL will execute at the frequency of ticks you select (barring any
unusually long tasks such as a disk inserted event hogging your time).
° You won’t get the flicker you see on the screen when trying to do moderately fast
animation. This flicker occurs when the screen redraws itself half way through
drawing your graphic.
° Plus once you’ve loaded a task on the queue, you needn’t worry about the task
until you want to remove it.
Like almost everything else in programming, vbl tasks are easy once you’ve done
one (after that its all copy and paste). This example program installs a vbl task which
displays a number of icons sequentially. It could easily be modified to move the icons
(or bitmaps) around the screen creating game graphics.
The main program is fairly straight forward. The only unusual thing you might
find is the declaration of the ‘SetUpA5’ and ‘RestoreA5’ calls. If your task uses any
global variables at all, you must insure that the A5 register contains the address of the
boundary between the application globals and the application parameters. This is
important since you can’t be sure from where the vbl task will be called.
The program basically opens a simple window, installs our vbl task, waits for a
button click then exits after removing the task.
/*********************************************
vblTask.c
* an VBL task animation example
*
* Written by Dick C handler
*
* This program is intentionally kept as
* simple as possible, so that it could be
* easily entered and/or understood.
* Therefore there are no calls made to
* check events nor any menus implemented.
********************************************/
/***** the only includes we’ll need *****/
#include
#include
#include < windows.h>
#include
#include < events.h>
#include
#include
#include
/***** define our own ‘A5’ routines *****/
pascal void SetUpA5a() extern 0x2f0d;
pascal void SetUpA5b() extern 0x2a78;
pascal void SetUpA5c() extern 0x0904;
#define SetUpA5() SetUpA5a(); SetUpA5b(), SetUpA5c()
/* just for readibility
#define NOT !
pascal void RestoreA5() extern 0x2a5f;
/***** Globals *****/
/* location of icons displayed */
Rect iconRec = {30,30,62,62};
/* window rectangle */
Rect boundsRect = {30,30,120,120};
/* tasks VBL record */
VBLTask StatusTask;
/* task routines */
void vblTask(), installTask(), removeTask();
/* time between icons */
long interval;
/***** constants *****/
#define FIRST_ICON 1000
#define LAST_ICON 1005
#define MAX_NUMBER_ICONS (LAST_ICON - FIRST_ICON) +1
#define SECONDS 60
/*********************************************
the main program
********************************************/
int main()
{
WindowRecord editWindowRecord;
WindowPtr editWindowPtr;
InitGraf (&qd.thePort);
InitWindows ();
/*
* open a small, simple (and humble)
* window
*/
editWindowPtr = NewWindow(&editWindowRecord,&boundsRect, “”,
true,
1, (-1), false, nil);
SetPort ( editWindowPtr );
/*
* set the interval time between icons
* and install our task on vbl queue
*/
interval = SECONDS/8;
installTask ( &StatusTask );
/*
* run until the button is clicked
*/
while ( NOT Button() ) ;
/*
* clean up and exit
*/
removeTask ( &StatusTask );
CloseWindow (editWindowPtr);
return 0;
}
The function ‘installTask’ sets up the required parameters for the vbl task.
These parameters are passed via a ‘VBLTask’ record when the task is installed with the
toolbox call ‘VInstall’.
° ‘vblAddr’ is the address of the function we’ve written and want the system to
execute.
° ‘vblCount’ is the count, in ticks, to wait before calling the vblTask for the first
time. We will reset this value everytime the task is executed if we want it to be
reexecuted.
° ‘vblPhase’ allows you an additional offset before calling vblTask for the first
time only. This would be useful if you wanted to install several graphic image
tasks but did not want them to all look in sync.
° ‘qType’ designates the task a vbl task.
The function ‘removeTask’ simply removes the task from the queue with the
toolbox call ‘VRemove’.
/************** NAME: installTask
* INPUT: a pointer to a VBL task record
*
* FUNCTION: installs our vblTask after
* setting the vbl parameters
********************************************/
void installTask( StatusTask )
VBLTask *StatusTaskPtr;
{
StatusTaskPtr->vblAddr = vblTask;
StatusTaskPtr->vblCount = 10;
StatusTaskPtr->vblPhase = 0;
StatusTaskPtr->qType = vType;
VInstall (StatusTaskPtr);
}
/************* NAME: removeTask
* INPUT: a pointer to a VBL task record
*
* FUNCTION: removes our vbl task
*******************************************/
void removeTask ( StatusTask )
VBLTask *StatusTaskPtr;
{
VRemove (StatusTask);
}
‘vblTask’ is our routine which we loaded into the vbl record and installed. The
routine sets up and later restores the A5 register so we can use our own global
varibles. It is important to note that you cannot make any calls to the memory
manager, and you cannot rely on locked handles being valid. These caveats are outlined
in the ‘Vertical Retrace Manager’, Inside Macintosh V 1-3.
‘vblTask’ decides which of our icons to display next and then displays it if it finds
the icon. Notice that we must reset the ‘vblCount’ each time or the task will not be
called again.
/*******************
NAME:vblTask
*
* FUNCTIONS: our actual vbl task which gets
* called every ‘interval’ ticks
********************************************/
void vblTask()
{
static long icons;
Handle tempIcon;
static long timeIcon = FIRST_ICON;
SetUpA5(); /* set up A5 register */
icons = MAX_NUMBER_ICONS;
StatusTask.vblCount = interval; timeIcon++; /*bumpicon */
if( timeIcon > LAST_ICON )
timeIcon = FIRST_ICON;
tempIcon = GetIcon( timeIcon )
if( tempIcon )
PlotIcon( &iconRec, tempIcon );
RestoreA5(); /* preserve A5 register */
}
The only resources you will need are icons to display. I attached six ‘drumming
fingers’ icons [included in the source code disk.-Ed] I used in the program thanks to
graphic artists Irene Welch and Shelley van Bronkhorst. However, you can attach any
number of icons you wish as long as you change the defined constants ‘FIRST_ICON’ and
‘LAST_ICON’.
The program can be compiled and linked with the following commands. You can
either paste in the resources with ResEdit, or derez and rez the resources into the
application.
derez vblTaskResources Types.r SysTypes.r > vblTask.r
Rez Types.r SysTypes.r vblTask.r -o vblTask -a
SetFile -a B vblTask -c MOBY -t APPL
C -g vblTask.c
Link vblTask.c.o ∂
“HD:MPW:CLibraries:”CRuntime.o ∂
“HD:MPW:CLibraries:”CInterface.o ∂
-o vblTask
VBL Animation Problems
David Oster
Berkeley, CA
I am appalled by Dick C handler’s article, “VBL Task Animation” in the February
1989 issue of MacTutor. Yes, his program works, but only because it is a top. Any
real program that tries the technique he describes will fail miserably.
Look, his VBL task calls GetIcon and PlotIcon at VBL interrupt time. In his
application, the main loop just busy waits for the user to press the Button. A real
application would be calling GetNextEvent(), or doing something. For example, each
time the user looks at a menu. When the menu goes away, it slams those bits back and
deallocates the handle.
GetIcon calls GetResource(). What if the VBL task calls it while the Memory
Manager is shuffling the heap to allocate memory for the main loop. Crash city.
PlotIcon calls CopyBits(), which clips against the clipRgn and visRgn of the underlying
grafPort. What if the VBL task calls it while the Memory Manager is shuffling the
heap to allocate memory for the main loop? Crash city.
Even if your program is clean, you do not know what trap patches the user has
installed: Maybe he is using an INIT that overrides some trap your program needs, and
the override will do memory allocation. For example, Dick’s program calls Button()
from its main loop, and many INITs override button, so they will get called while the
mouse is down.
So, you can only do animation at interrupt time if you can guarantee that no user
or system task will allocate memory in the main loop.
Dick’s program doesn’t guarantee this, since it calls Button() from its main
loop, and Button() may have been overriden by an INIT. Since there is so little the
main loop can safely do, you might as well give up on VBL Task animation, and just do
animation in your main loop, busy waiting until TickCount changes to pause between
animation frames.