Bitmapper
Volume Number: 9
Issue Number: 9
Column Tag: Getting Started
Flicker-Free Bitmap animation 
You too can do those really cool graphics that are smooooth
By Dave Mark, MacTech Magazine Regular Contributing Author
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
Lately, I’ve been getting lots of mail asking about Macintosh animation. Since that
was the topic of my presentation at the MacTech Magazine Live! session at this past
MacWorld, I thought the time might be right for a series of articles discussing this
deep, dark, Macintosh programming mystery. This column (which started life in an old
issue of SPLAsh magazine, just in case it looks a little familiar) starts with the basics,
covering black and white animation using quickdraw BitMaps. In later columns, once
we cover color quickdraw, we’ll revisit this topic, expanding the techniques to include
PixMap animation.
What the Heck is Bitmap Animation?
If you’ve ever written an arcade game, you’ve probably tried your hand at bitmap
animation, where a bitmap image appears to move over a stationary background. Your
Mac’s cursor is a perfect example. As the cursor moves around the screen, it appears
to float over the background without flickering. Take a look at this sequence of
pictures:
(a) (b) (c)
Figure (a) shows an arrow cursor partially obscuring my hard drive icon. Once
the cursor moves, it leaves an area of the hard drive icon undrawn (b). Before this
hole gets noticed, the System fills it back up with its previous contents (c).
Most programs deal with repainting the screen by responding to updateEvts
generated by the Window Manager. When an area of a window that was previously
obscured needs to be redrawn, the Window Manager adds the newly revealed area to the
window’s update region and generates an updateEvt for the window.
The problem with this approach is that update events take time. It takes time for
the Window Manager to calculate the update region and it takes time to post an event.
More importantly, it takes time for your program to respond to an update event. If
your program is busy responding to another event, the update event might sit in the
queue for a while, leaving the window undrawn until you get around to fixing it.
When you’ve got a rocket ship shooting across a planet’s surface, you don’t want
to leave any holes in the planet, waiting for your program to respond to an update
event. You want to fill in the holes in real time, just like the System does when it
handles your cursor.
The Off-Screen Bitmap Solution
The solution to this problem lies in the use of off-screen bitmaps. An off-screen
bitmap is a bitmap that is drawn in memory, but does not appear on screen. In this
month’s program, we’ll create three off-screen bitmaps. One of these will act as a
master image, which we’ll constantly copy to a window that does appear on the screen.
The second bitmap will hold a background image and the third will hold the foreground
image. Our goal is to make the foreground image track the cursor, appearing to float on
top of the background image.
Here’s a snapshot of our program in action:
The floating hand is our foreground image. The framed gray pattern is the
background image. As you move the mouse, the hand appears to float over the gray
background, just like a cursor. Here’s how this works.
The Basic Approach
We’ll start by creating the off-screen bitmaps for the foreground and
background. Next, we create the master bitmap, which we’ll use to mix our foreground
and background. In a loop, we copy the background to the mixer, then copy the
foreground to the mixer, on top of the background. Still inside the loop, we copy the
mixed image to the window. This loop continues until we click the mouse button.
Even though we are constantly updating the image in the window, there is a
minimum of flicker. Why? Well, it helps to understand what causes flicker in the first
place. Imagine if you tried to simulate the floating image by constantly drawing the
background, then the foreground, images in an endless loop. For example, here’s a
sequence using a black background and a white triangular foreground:
(a) (b) (c)
Figure (a) shows the triangle on the black background. Figure (b) shows the
screen when you draw the background again. Finally, (c) shows the screen after you
redrew the foreground again. The point here is that using this approach, every other
image will be completely black. The foreground image will flicker in and out of view.
To convince yourself, write a program that draws a pair of PICTs in a window, in
an endless loop. First draw one PICT, then the other, one on top of the other. Without
off-screen bitmaps, you can minimize flicker, but there’s no way to avoid it
altogether.
OK, let’s get on with the program. Create a folder named BitMapper inside your
Development folder. Open up ResEdit and create a new resource file named
BitMapper.π.rsrc inside the BitMapper folder.
Next, create two PICT resources, numbered 128 and 129. PICT 128 will be the
background image, so make it larger than PICT 129, which will serve as the
foreground image. If you’ve got a graphics program like MacPaint or Canvas, create
your background by drawing a nice frame, then pasting another image inside it. Copy
the whole thing to the clipboard, then paste it inside ResEdit.
For the foreground, you’ll want something relatively small. Use whatever image
you like, but be sure to make it resource ID 129. Note that both images should be black
and white only, and not color or gray-scale. You can use a color image, but all colored
pixels will be translated to black, so things might not come out as you planned them to.
Once your PICT images are in place, quit ResEdit, making sure you save your
changes. Now launch THINK C and create a new project named BitMapper.π in the
BitMapper folder. Select New from the File menu and, when the new source code
window appears, type in this source code:
/* 1 */
#define kMoveToFront (WindowPtr)-1L
const short kBackgroundPictID = 128;
const short kForegroundPictID = 129;
/***************/
/* Functions */
/***************/
void ToolboxInit( void );
WindowPtr WindowInit( void );
PicHandle LoadPicture( short resID );
GrafPtr CreateBitMap( const Rect *rPtr );
/****************** main ***************************/
void main( void )
{
Rect r;
GrafPtr backPortPtr, forePortPtr, mixerPortPtr;
WindowPtr window;
PicHandle backPict, forePict;
Point p;
ToolboxInit();
window = WindowInit();
backPict = LoadPicture( kBackgroundPictID );
r = (**backPict).picFrame;
OffsetRect( &r, -r.left, -r.top );
/* Leaves backPortPtr as current port */
backPortPtr = CreateBitMap( &r );
DrawPicture( backPict, &r );
/* Leaves mixerPortPtr as current port */
mixerPortPtr = CreateBitMap( &r );
forePict = LoadPicture( kForegroundPictID );
r = (**forePict).picFrame;
OffsetRect( &r, -r.left, -r.top );
/* Leaves forePortPtr as current port */
forePortPtr = CreateBitMap( &r );
DrawPicture( forePict, &r );
HideCursor();
while ( !Button() )
{
CopyBits( &(backPortPtr->portBits),
&(mixerPortPtr->portBits),
&(backPortPtr->portBits.bounds),
&(mixerPortPtr->portBits.bounds), srcCopy, nil );
GetMouse( &p );
SetPort( window );
GlobalToLocal( &p );
r = forePortPtr->portBits.bounds;
OffsetRect( &r, p.h, p.v );
CopyBits( &(forePortPtr->portBits),
&(mixerPortPtr->portBits),
&(forePortPtr->portBits.bounds), &r,
srcOr, nil );
CopyBits( &(mixerPortPtr->portBits), &( window->portBits),
&(mixerPortPtr->portBits.bounds),
&( window->portRect), srcCopy, nil );
}
}
/****************** ToolboxInit *********************/
void ToolboxInit( void )
{
InitGraf( &thePort );
InitFonts();
InitWindows();
InitMenus();
TEInit();
InitDialogs( nil );
InitCursor();
}
/****************** WindowInit ***********************/
WindowPtr WindowInit( void )
{
WindowPtr window;
PicHandle pic;
Rect r;
pic = LoadPicture( kBackgroundPictID );
r = (**pic).picFrame;
OffsetRect( &r, 20 - r.left, 50 - r.top );
window = NewWindow( nil, &r, "\pBitMapper", true,
noGrowDocProc, kMoveToFront, false, 0L );
return( window );
}
/****************** LoadPicture *********************/
PicHandle LoadPicture( short resID )
{
PicHandle picture;
picture = GetPicture( resID );
if ( picture == nil )
{
SysBeep( 10 ); /* Couldn't load the PICT resource!!! */
ExitToShell();
}
}
/****************** CreateBitMap *********************/
GrafPtr CreateBitMap( const Rect *rPtr )
{
short i;
BitMap *bPtr;
GrafPtr g;
g = (GrafPtr)NewPtr( sizeof(GrafPort) );
if ( g == nil )
SysBeep(20);
bPtr = (BitMap *)NewPtr( sizeof( BitMap ) );
if ( bPtr == nil )
SysBeep( 20 );
bPtr->bounds = *rPtr;
bPtr->rowBytes = (rPtr->right - rPtr->left + 7) /8;
i = rPtr->bottom - rPtr->top;
bPtr->baseAddr = NewPtr( bPtr->rowBytes * i );
if ( bPtr->baseAddr == nil )
SysBeep( 20 );
OpenPort( g );
SetPortBits( bPtr );
return( g );
}
Once your source code is typed in, save it under the name BitMapper.c, then add
the code to the project by selecting Add from the Source menu. Run BitMapper by
selecting Run from the Project menu. Once your code compiles, a window should appear
with your background PICT drawn in it. The window will be the exact size of the
background PICT.
As you move the mouse, the foreground PICT should appear, following the mouse’s
movement. Click the mouse to exit the program.
Walking Through the BitMapper Source Code
BitMapper starts off with a few constant definitions.
/* 2 */
#define kMoveToFront (WindowPtr)-1L
const short kBackgroundPictID = 128;
const short kForegroundPictID = 129;
These are followed by BitMapper’s function prototypes.
/* 3 */
/***************/
/* Functions */
/***************/
void ToolboxInit( void );
WindowPtr WindowInit( void );
PicHandle LoadPicture( short resID );
GrafPtr CreateBitMap( const Rect *rPtr );
main() starts off by initializing the Toolbox.
/* 4 */
/****************** main ***************************/
void main( void )
{
Rect r;
GrafPtr backPortPtr, forePortPtr, mixerPortPtr;
WindowPtr window;
PicHandle backPict, forePict;
Point p;
ToolboxInit();
Next, a window is created. The WindowPtr is returned and stored in the variable
window.
/* 5 */
window = WindowInit();
Next, the background PICT is loaded from the resource fork. The frame of the
PICT (its bounding rectangle) is normalized, so its top and left are both 0.
/* 6 */
backPict = LoadPicture( kBackgroundPictID );
r = (**backPict).picFrame;
OffsetRect( &r, -r.left, -r.top );
This normalized Rect is passed on to CreateBitMap(). CreateBitMap(), listed
below, creates an off-screen GrafPort the size of the specified Rect. This GrafPort can
be drawn in, just like a window’s GrafPort. You can use SetPort() on it, as well as all
the standard Quickdraw routines such as DrawString() and DrawPicture(). While
your drawing won’t appear on the screen, the drawing will affect the memory used to
implement the GrafPort.
/* 7 */
/* Leaves backPortPtr as current port */
backPortPtr = CreateBitMap( &r );
CreateBitMap() returns a pointer to the newly created GrafPort. When
CreateBitMap() returns, this port is made the current port. Next, DrawPicture() is
called to draw the background PICT in the background GrafPort.
/* 8 */
DrawPicture( backPict, &r );
Next, the master GrafPort is created. This GrafPort is used to merge the
foreground PICT with the background PICT. Once again, when this call of
CreateBitMap() returns, the new GrafPort is the current port.
/* 9 */
/* Leaves mixerPortPtr as current port */
mixerPortPtr = CreateBitMap( &r );
Just as we did with the background PICT, this next sequence of code loads the
foreground PICT, creates a normalized bounding Rect, and finally creates a GrafPort
for the foreground PICT.
/* 10 */
forePict = LoadPicture( kForegroundPictID );
r = (**forePict).picFrame;
OffsetRect( &r, -r.left, -r.top );
/* Leaves forePortPtr as current port */
forePortPtr = CreateBitMap( &r );
The call of CreateBitMap() leaves forePortPtr as the current port. Next,
DrawPicture() is used to draw the foreground picture in this newly created GrafPort.
/* 11 */
DrawPicture( forePict, &r );
OK. That’s about all the preliminary stuff. Now we’re ready to animate. Before we
do, we’ll use HideCursor() to make the cursor invisible.
/* 12 */
HideCursor();
Next, we’ll enter a loop, waiting for the mouse button to be clicked.
/* 13 */
while ( !Button() )
{
At the heart of our program is the CopyBits() Toolbox routine. CopyBits() copies
one Quickdraw BitMap to another. We’ll get into the BitMap data structure a bit later
on. This call of CopyBits() copies the background BitMap into the mixer BitMap, using
the bounding rectangle associated with each of the BitMaps. The srcCopy parameter
specifies how the BitMap is copied. srcCopy tells CopyBits() to replace all bits in the
destination BitMap’s rectangle with the bits in the source BitMap.
/* 14 */
CopyBits( &(backPortPtr->portBits),
&(mixerPortPtr->portBits),
&(backPortPtr->portBits.bounds),
&(mixerPortPtr->portBits.bounds), srcCopy, nil );
Next, we get the current position of the mouse, in global coordinates.
/* 15 */
GetMouse( &p );
Next, set the port to the BitMapper window, then convert the mouse position to
the window’s local coordinates.
/* 16 */
SetPort( window );
GlobalToLocal( &p );
Next, the foreground BitMap’s bounding rectangle is copied to a local variable, r,
and offset by the mouse’s position. Basically, r is the same size as the foreground
BitMap (the pointing hand), positioned on the background BitMap (which is the same
size as the window) according to the current location of the mouse.
/* 17 */
r = forePortPtr->portBits.bounds;
OffsetRect( &r, p.h, p.v );
Next, the foreground BitMap is copied to the mixer BitMap, using r as the
destination bounding rectangle. Notice the use of srcOr instead of srcCopy. This makes
the foreground BitMap transparent. To see the effect this has, try changing the srcOr to
srcCopy.
/* 18 */
CopyBits( &(forePortPtr->portBits),
&(mixerPortPtr->portBits),
&(forePortPtr->portBits.bounds), &r,
srcOr, nil );
Finally, the mixer BitMap is copied to the window. The loop works like this:
Build the window’s image off-screen, copy the combined image to the window.
/* 19 */
CopyBits( &(mixerPortPtr->portBits), &( window->portBits),
&(mixerPortPtr->portBits.bounds),
&( window->portRect), srcCopy, nil );
}
}
ToolboxInit() is the same as it ever was...
/* 20 */
/****************** ToolBoxInit *********************/
void ToolboxInit( void )
{
InitGraf( &thePort );
InitFonts();
InitWindows();
InitMenus();
TEInit();
InitDialogs( nil );
InitCursor();
}
WindowInit() loads the background PICT, copying its framing rectangle into r.
/* 21 */
/****************** WindowInit ***********************/
WindowPtr WindowInit( void )
{
WindowPtr window;
PicHandle pic;
Rect r;
pic = LoadPicture( kBackgroundPictID );
r = (**pic).picFrame;
r is normalized, then offset 20 pixels from the left and 50 pixels from the top. r
will be used to create a window the same size as the background PICT.
/* 22 */
OffsetRect( &r, 20 - r.left, 50 - r.top );
NewWindow() is used to create the BitMapper window, using r as a bounding
rectangle.
/* 23 */
window = NewWindow( nil, &r, "\pBitMapper", true,
noGrowDocProc, kMoveToFront, false, 0L );
The WindowPtr is returned to the calling routine.
/* 24 */
return( window );
}
LoadPicture() loads the specified PICT resource.
/* 25 */
/****************** LoadPicture *********************/
PicHandle LoadPicture( short resID )
{
PicHandle picture;
picture = GetPicture( resID );
If the PICT wasn’t found, beep once, then exit.
if ( picture == nil )
{
SysBeep( 10 ); /* Couldn't load the PICT resource!!! */
ExitToShell();
}
}
CreateBitMap() will create a new GrafPort() the size of the specified Rect. A
BitMap is a Quickdraw data structure designed to hold a bitmap of an image one pixel
deep (black and white). The BitMap is described in Inside Macintosh, Volume I, page
144, and in Inside Macintosh: Overview, page 91.
/* 26 */
/****************** CreateBitMap *********************/
GrafPtr CreateBitMap( const Rect *rPtr )
{
short i;
BitMap *bPtr;
GrafPtr g;
First, a new GrafPort is allocated using NewPtr(). If the memory couldn’t be
allocated, beep once.
/* 27 */
g = (GrafPtr)NewPtr( sizeof(GrafPort) );
if ( g == nil )
SysBeep(20);
Next, a BitMap data structure is allocated. Again, if the memory was not
allocated, beep once. These beeps aren’t really effective. They’re put in place as a weak
substitute for error checking. You’ll want to weave memory allocation failure into
your overall error handling scheme.
/* 28 */
bPtr = (BitMap *)NewPtr( sizeof( BitMap ) );
if ( bPtr == nil )
SysBeep( 20 );
Next, the specified rectangle is copied into the BitMap’s bounds field. This field
specifies the coordinates bounding the BitMap.
/* 29 */
bPtr->bounds = *rPtr;
The rowBytes field specifies how many bytes are used to store one row of the
BitMap. For example, 0 through 8 pixels can be stored in 1 byte, 9 through 16 pixels
in 2 bytes, etc.
/* 30 */
bPtr->rowBytes = (rPtr->right - rPtr->left + 7) /8;
Next, i is set to the number of rows in the bounding rectangle, and i * rowBytes
bytes are allocated for the bit image itself.
/* 31 */
i = rPtr->bottom - rPtr->top;
bPtr->baseAddr = NewPtr( bPtr->rowBytes * i );
Again, if the memory was not allocated, beep once.
/* 32 */
if ( bPtr->baseAddr == nil )
SysBeep( 20 );
Next, OpenPort() is called to initialize the new GrafPort, which is pointed to by
g. OpenPort() leaves g as the current port. SetPortBits() ties the specified BitMap to
the current port.
/* 33 */
OpenPort( g );
SetPortBits( bPtr );
Finally, we return a pointer to the newly allocated GrafPort.
/* 34 */
return( g );
}
Till Next Month...
This sample code should get you on your way to successful bitmap animation. Once
you’ve mastered this technique, you’re ready to tackle color animation by using
PixMaps and the Toolbox routine CopyPixMap(). These are described in Inside
Macintosh, Volume V. As I mentioned at the beginning of the column, we’ll eventually go
over PixMap animation, but first we’ll have to cover the basics of programming with
color quickdraw.
In next month’s column, we’ll take a break from the Toolbox and explore some of
the differences between C and C++. In the meantime, I’ll be busy trying to catch up
with Daniel. Oh, how those little feet can fly...