Related Info: Color Quickdraw

Special Effects

By Kirk Chase, MacTutor

Introduction

Unless you’ve been trapped in a cave with your Mac, you have probably heard of multimedia. It seems like everyone is getting into the act of combining clip art and video clips along with a cornucopia of sounds to go along with it. You sit in front of the multimedia booths and wish that you could bring some visual and/or sound effects to your application. “Plain” is out, and “Zap! Pow! Zowie!” is in.

The trouble is that you are spending most your time getting the application to work well and work fast. “Zap! Pow! Zowie!” won’t cut it after the user has had a day or two to get over the “video game” and has gotten the credit card bill. You can’t spend most of your life getting that Star Trek “transporter” effect. That type of effect is for the bit twiddlers. Macintoshes just don’t have the tools for normal folks to create visual fireworks. Wrong! This article will discuss how to get some spiffy effects (black & white only for now).

CopyBits

“CopyBits” is a word that strikes fear into the uninitiated. But to those who have taken the time to understand the trap call, CopyBits offers a world of opportunities. With CopyBits you can hilight icons, make your updates quicker, and create nifty effects.

CopyBits is for transferring one image onto another image quickly and with a number of effects. It is defined in Inside Macintosh Vol. I (or volume V for the color aspects) as follows:

For Pascal users:

{1}

Procedure CopyBits(srcBits, dstBits: BitMap; srcRect, dstRect: Rect; 
mode: Integer; maskRgn: RgnHandle);

or for C users:

/* 2 */

void CopyBits(BitMap *srcBits, BitMap *dstBits, Rect *srcRect, Rect *dstRect, 
int mode, RgnHandle maskRgn);

(The differences between the C and Pascal versions are due to the fact that objects over 4 bytes must be passed explicitly by address.)

The first two parameters, srcBits and dstBits, are BitMap objects. Now one of the reasons you probably haven’t looked into CopyBits is this “BitMap” structure. Just think of BitMaps as a piece of paper. One piece of paper has on it the object you wish to transfer-srcBits. And the other piece of paper is where you want the object to be drawn-dstBits.

The next two parameters are a couple of rectangles, srcRect and dstRect. Since the BitMaps, or pieces of paper, may be arbitrarily large, the two rectangles serve as pinpointing the location of the object you wish transferred and where you want it transferred. CopyBits is quite flexible in resizing images if the srcRect and dstRect are of different sizes).

The next parameter is the transfer mode, mode. No doubt you are already familiar with them if you have worked with them in drawing objects or text. The transfer mode of srcCopy will just blast all bits from the object to the destination. An interesting effect is that of srcXor which will draw itself inverting the bits it is drawn on, and, if drawn twice, will restore the original image of the destination. This is how outlined images such as window outlines and “rubber band” lines of drawing programs are implemented.

The last parameter, maskRgn, is used for confining the drawing area. The image transfer is clipped to the intersection of the current grafPort’s clipRgn and visRgn (if the destination is the current grafPort) and the maskRgn parameter of the CopyBits call. This will ensure that no drawing is done where no drawing should be done. If maskRgn is NIL, then no clipping is done to the image except the with the clipRgn and visRgn of the current grafPort. maskRgn, if not NIL, should be in the coordinates of the destination and not the source or you may end up in trouble (like not seeing anything drawn at all).

We’re Making A Transition Here

This article provides a number of visual effects using CopyBits. These routines model the structure of the CopyBits call with a few more items added as well.

• WipeTopBottom(), WipeBottomTop(), WipeLeftRight(), WipeRightLeft()-these routines transfer the object to the destination similar to wiping a wet towel across a window; the dirty image is replaced with a cleaner (new) image. There is a parameter, panes, which allow you to create the effect like shutters on a window or a single curtain. The procedure tells what direction the wipe effect is.

• Iris()-this routine is takes a shape, such as a circle, draws the corresponding part of the source object onto the destination and then continually grows the shape until the destination is filled with the object. You see this in places like cartoons where a black field fills up the screen leaving a smaller and smaller circular view of the previous image (Th-That’s All Folks!). You may use any object though.

• FadePat()-the idea for this routine is taken from Mike Morton’s article, “The DissBits Subroutine”, The Best of MacTutor, Volume 1, page 111. Basically what Mike’s assembly level routine used was a series of patterns to copy the source object on to the destination. This yields a Star Trek “transporter” dissolve effect. My routine was re-written in a high level language and made to take any series of patterns.

• PageFlipDown() and PageFlipRight()-the idea for this was taken from the similar effect in HyperCard 2.0. It basically looks like a page flipping down or across.

All of these routines contain a pause option, pauseTicks, to slow down animation if too fast. Believe it or not, there are times when it will be too fast. Your image may be small enough to transfer very quickly, or the routine you are using may be very efficient, or the hardware may have incredible speed. You should use Gestalt or SysEnvirons to get your machine speed. You may even perform a short timing test, like an empty loop, to get some speed measurement to use in deciding how many ticks to wait from iteration to iteration of the transition effect. If an iteration takes longer to do than pauseTicks requires, then it will just go on to the next iteration. In any case, just pass the number of ticks you wish to pause. I will talk more about speed considerations later.

OffScreen Support

You will more than likely be transferring an object onto the screen from an unseen source. This is using an offscreen bitmap. To create this scratch piece of paper, you can simply create the NewBitMap() in the source listing; it essentially creates one using memory calls. When finished, you should call DisposBitMap() to release the memory.

However, an offscreen grafport has the distinct advantage of letting you draw to your hearts content unseen to avoid things like screen flicker and then transfer the finished image onto the screen. The routines for offscreen grafports in the listing are called NewOffScreen() and DisposOffScreen(). The concept is drawn heavily from Technical Note #41.

Basically to use them after creating the offscreen grafport you use the following steps:

• Save the old port to return to.

• Set the port to the offscreen one.

• Do your drawing

• Set the old port back.

Using The Various Transitions

This is how you use the various visual effects in Transition.c. All the following examples assume that you are copying an image from the GrafPtr, offScreenPort, and its BitMap, offScreenPort->portBits to your window pointer, MyWindow, and its BitMap, MyWindow->portBits. The object is enclosed in the rectangle, srcRect, and it being transferred to the rectangle, destRect. The mask for the CopyBits call, mask, is a region in the destination port, MyWindow. Each iteration of the effect is done at least pauseTicks ticks from the previous iteration.

Wipes

void WipeTopBottom(BitMap *srcBits, BitMap *dstBits,
 Rect *srcRect, Rect *dstRect, int mode, RgnHandle mask, 
 int partitions, long pauseTicks);
 
void WipeBottomTop(BitMap *srcBits, BitMap *dstBits,
 Rect *srcRect, Rect *dstRect, int mode, RgnHandle mask, 
 int partitions, long pauseTicks);
 
void WipeLeftRight(BitMap *srcBits, BitMap *dstBits,
 Rect *srcRect, Rect *dstRect, int mode, RgnHandle mask, 
 int partitions, long pauseTicks);
 
void WipeRightLeft(BitMap *srcBits, BitMap *dstBits,
 Rect *srcRect, Rect *dstRect, int mode, RgnHandle mask, 
 int partitions, long pauseTicks);

The four wipe effects are similar. Their names denote the direction of the wipe. mode is the CopyBits transfer mode. The parameter partitions tells the routine how many slices, or shutters, to do the transfer. You should adjust the number of partitions with the speed of the transfer to get the desired effects.

All the calls are similar. A call might look like this:

/* 4 */

WipeTopBottom(&(offScreen->portBits), &(MyWindow->portBits), &srcRect, 
&dstRect, srcCopy, NIL, 5, 0L);

This gives five partitions, in srcCopy mode, with no additional masking, at the fastest speed.

Iris

void Iris(BitMap *srcBits, BitMap *dstBits, Rect *srcRect, Rect *dstRect, 
int mode, RgnHandle mask, RgnHandle irisRgn, long pauseTicks);

The Iris() transfer effect takes the usual parameters. Rather than a partition parameter, it takes a region to use as the iris, irisRgn. The image being transferred is clipped to the mask region and irisRgn. Then, irisRgn is expanded, and the process is repeated. If the iris has a hole, such as a ring, then the whole is eventually filled in.

There are a number of ideas you should keep in mind when creating your iris. In creating your iris, be aware that framing an object does not leave a hole in making a region as the QuickDraw call; to make a frame of an object, you must expand the region a bit and remove the center by using DiffRgn() with the expanded region and a copy of the original region. Also, an object as it grows does not tend to keep its shape very well. For example, a circle, when expanded, tends to transform into a rounded rectangle. If you wish a “circle in” or “circle out” transition, you will have to write those yourself.

A call to the Iris() transfer using our example and an iris region called triangleRgn might look like this:

/* 6 */
Iris(&(offScreen->portBits), &(MyWindow->portBits), &srcRect, &dstRect, 
srcCopy, NIL, triangleRgn, 0L);

FadePat

void FadePat(BitMap *srcBits, BitMap *dstBits, Rect *srcRect, Rect *dstRect, 
int mode, RgnHandle mask, int patList, int patCount, long pauseTicks);

FadePat(), along with the usual parameters, takes a couple of new parameters, patList and patCount. patList is a ‘PAT#’ resource ID in an open resource fork. patCount is the number of patterns in the list. The pattern list may be anything you wish, but every pixel in the 8x8 pattern matrix must be used once and only once. This is to insure the whole image is transferred and to overcome the problems of certain copy modes such as srcXor. If you use srcCopy transfer mode, you need not worry that a particular pixel is used in more than one pattern. See Figure 1.

Figure 1. Example of “Good” and “Bad” Patterns

A call to FadePat() using a ‘PAT#’ resource with the ID of 210 that contains 8 patterns might be:

/* 8 */

FadePat(&(offScreen->portBits), &(MyWindow->portBits), &srcRect, &dstRect, 
srcCopy, NIL, 210, 8, 0L);

One more thing. MakeRgn() was taken from Ted Cohn’s article, “Convert PICTs to Regions”, Best of MacTutor, Volume V, page 11. A similar call is in 32-bit QuickDraw and is documented in Tech Note #193.

PageFlips

void PageFlipDown(BitMap *srcBits, BitMap *dstBits, Rect *srcRect, Rect 
*dstRect, RgnHandle mask, int partitions, long pauseTicks);
 
void PageFlipRight(BitMap *srcBits, BitMap *dstBits, Rect *srcRect, Rect 
*dstRect, RgnHandle mask, int partitions, long pauseTicks);

The two page flips are similar to all the other visual effects. The parameter, partitions, controls how fast the page flips down or to the right. One notable exception in these routines when compared to the other routines; there is no parameter for the CopyBits copy mode. These visual effects only work in srcCopy mode.

The reason why they only work in srcCopy mode is simple. To achieve the page flipping effect, the object is drawn in a small rectangle at the top or left of the destination rectangle. This rectangle is then made larger to the bottom or right, respectively, and the object is then drawn again. This is done until the growing rectangle is the same as the destination rectangle. Since the object is drawn over and over, copy modes like srcXor will not work very well (Each successive draw would flip the pixel state and thereby turning on or off a pixel when it should be in the other state).

A call to one of the page flips with seven partitions may look like this:

/* 10 */

PageFlipDown(&(offScreen->portBits), &(MyWindow->portBits), &srcRect, 
&dstRect, NIL, 7, 0L);

A Discussion of CopyBits Speed

In animation, speed is everything. This usually means assembly language to fine tune the code and perhaps a vertical blank routine to do during a screen refresh. This is not always the case, especially if you look for ways to optimize either CopyBits’ performance or the routine that uses it. Let’s examine CopyBits and see what can be done to increase its performance first. I will refer you to Tech Note #277 for a more complete look at ways to improve CopyBits’ performance.

• Size of the Image

Obviously, CopyBits can transfer a smaller image faster than a larger one. CopyBits also works better on areas that are wider than taller; this is because the pixels occupy consecutive bytes in memory.

• Size and Shape of the Clip, Vis and Mask Regions

The more complex these regions are, the longer it takes for CopyBits to do its job. The simplest area is a rectangular one. If the intersection of all these regions is rectangular, CopyBits can really fly.

• Transfer Mode

The transfer mode of CopyBits also affects the speed of performance. CopyBits must take each bit in the source and the destination and perform some calculation to set the destination bit. The transfer mode srcCopy generally has the greatest speed. I say “generally” because the image and the destination has quite a lot to do with this.

• Alignment

CopyBits will go faster if the image and the destination are aligned. If they are not, CopyBits must shift the pixels over. To keep the two areas aligned, the portBits.bounds.left or the port must be the same and the left sides of the source and destination rectangles must be the same. When you create the offscreen port, align its portBits.bounds to the rectangle that contains your destination. Then draw your offscreen area in the same relative position to the left that the area is as defined by the destination rectangle. See Figure 2.

• Scaling and Offscreen/Onscreen

These are two other factors to consider. If the source and destination rectangles are of differing sizes, then CopyBits must scale the image accordingly; this slows CopyBits down considerably. Also the transfer is influenced if the source and/or the destination in on or off the screen. Unfortunately, the most used one (Offscreen-to-Onscreen) is the slowest (Offscreen-to-Offscreen is the fastest followed by Onscreen-to-Onscreen, and Onscreen-to-Offscreen).

Figure 2.

Optimizing Transition Routines

There are a number of ways to make these transfer routines faster.

• Make A srcCopy Only Version

Much of the code and region acrobatics are so that srcXor mode will be supported. In order to do that, masks must be created so that no pixel is transferred more than once. If srcCopy is used then you do not need to care about this problem. FadePat() could use a list of patterns that eventually used every bit in the 8x8 matrix; Iris() would not need to keep a running sum of what region has been transferred; the wipes could go faster, too.

• Use CopyBits Speed Improvements

Although it is more complicated, try to implement the improvements that have been talked about in the previous discussion. Even making the regions rectangular might add a big speed improvement.

• Draw During Refresh Time

This is not the most accurate way to determine refresh time, but you might want to wait until the tick count value has changed. This is done during vertical blanking. Get the tick value and sit in a tight loop until you get a different value, then draw fast!

• Play Around With The Routines

Test out the routines on different image sizes and different parameter values for each routine. Tables 1 to 4 shows the various tick counts to complete each operation on a standard image of 132 x 122 pixels without regard to alignment and so on. The tables also show a comparison from an SE to a IIcx.

You may notice the great time differences between Random Pattern 1 and Random Pattern 2 for FadePat(). Figure 3 shows a pictorial representation of the two pattern lists. Random Pattern 2 uses 2x2 dots instead of 1x1 dots. I feel this pattern achieves the same effect as Random Pattern 1, but in a third of the time to transfer the image. It is experiments like this that could give you the effect you desire.

Figure 3. FadePat()’s Random Pattern 1 & 2

I hope this will help you make the transition from a boring application to a “Zap! Pow! Zowie!” application.

Table 1. Wipe Benchmarks

Table 2. PageFlip Benchmarks

Table 3. Iris Benchmarks

Table 4. FadePat Benchmarks

Listing:  Transition.h

/***********************
Transition.h
************************/

extern Ptr NewBitMap(BitMap *bm, Rect *r);

extern void DisposBitMap(BitMap *bm);

extern GrafPtr NewOffScreen(Rect *theBounds);

extern void DisposOffScreen(GrafPtr offPort);

extern void WipeTopBottom(BitMap *srcBits, BitMap *dstBits,
 Rect *srcRect, Rect *dstRect, int mode, RgnHandle mask, 
 int partitions, long pauseTicks);
 
extern void WipeBottomTop(BitMap *srcBits, BitMap *dstBits,
 Rect *srcRect, Rect *dstRect, int mode, RgnHandle mask, 
 int partitions, long pauseTicks);
 
extern void WipeLeftRight(BitMap *srcBits, BitMap *dstBits,
 Rect *srcRect, Rect *dstRect, int mode, RgnHandle mask, 
 int partitions, long pauseTicks);
 
extern void WipeRightLeft(BitMap *srcBits, BitMap *dstBits,
 Rect *srcRect, Rect *dstRect, int mode, RgnHandle mask, 
 int partitions, long pauseTicks);

extern void Iris(BitMap *srcBits, BitMap *dstBits,
 Rect *srcRect, Rect *dstRect, int mode, RgnHandle mask,
 RgnHandle irisRgn, long pauseTicks);
 
extern void FadePat(BitMap *srcBits, BitMap *dstBits,
 Rect *srcRect, Rect *dstRect, int mode, RgnHandle mask,
 int patList, int patCount, long pauseTicks);

extern void PageFlipDown(BitMap *srcBits, BitMap *dstBits,
 Rect *srcRect, Rect *dstRect, RgnHandle mask,
 int partitions, long pauseTicks);
 
extern void PageFlipRight(BitMap *srcBits, BitMap *dstBits,
 Rect *srcRect, Rect *dstRect, RgnHandle mask,
 int partitions, long pauseTicks);

Listing:  Transition.c

/**************************
Transition.c
created by Kirk Chase 3/29/90
***************************/
#include “Transition.h”
/* external variables and globals */
extern pascal RgnHandle MakeRgn(BitMap *srcMap);
 /* in 32 bit QD */

/************************************/
/* routines:
 • Ptr NewBitMap(bm, r)
 • void DisposBitMap(bm)
 • GrafPtr NewOffScreen(theBounds)
 • void DisposOffScreen(offPort)
 • void WipeTopBottom(srcBits, dstBits, srcRect, dstRect,
 mode, mask,
 partitions, pauseTicks)
 • void WipeBottomTop(srcBits, dstBits, srcRect, dstRect,
 mode, mask,
 partitions, pauseTicks)
 • void WipeLeftRight(srcBits, dstBits, srcRect, dstRect,
 mode, mask,
 partitions, pauseTicks)
 • void WipeRightLeft(srcBits, dstBits, srcRect, dstRect,
 mode, mask, partitions, pauseTicks)
 • void Iris(srcBits, dstBits, srcRect, dstRect, mode, mask,
 irisRgn, pauseTicks)
 • void FadePat(srcBits, dstBits, srcRect, dstRect, mode,
 mask, patList, patCount, pauseTicks)
 • void PageFlipDown(srcBits, dstBits, srcRect, dstRect,
 mask, partitions, pauseTicks)
 • void PageFlipRight(srcBits, dstBits, srcRect, dstRect,
 mask, partitions, pauseTicks)
 */
/************************************/

/************************************/
/* Ptr NewBitMap()
 creates a bitmap */
/************************************/
Ptr NewBitMap(bm, r)
BitMap *bm;
Rect *r;
{ /* NewBitMap() */
bm->rowBytes = ((r->right - r->left + 15) / 16) * 2;
bm->bounds = *r;
bm->baseAddr = NewPtr(bm->rowBytes * (long) (r->right - r->left));
if (MemError() != noErr) return (0L);
else return (bm->baseAddr);
} /* NewBitMap() */

/************************************/
/* void DisposBitMap()
 disposes of a bitmap */
/************************************/
void DisposBitMap(bm)
BitMap *bm;
{ /* DisposBitMap() */
DisposPtr(bm->baseAddr);
SetRect(&bm->bounds,0,0,0,0);
bm->rowBytes=0;
bm->baseAddr=0L;
} /* DisposBitMap() */

/************************************/
/* GrafPtr NewOffScreen()
 creates an offscreen grafport */
/************************************/
GrafPtr NewOffScreen(theBounds)
Rect *theBounds;
{ /* NewOffScreen() */
GrafPtr oldPort, offPort;

/* allocate port memory */
offPort = (GrafPtr) NewPtr(sizeof(GrafPort));
if (MemError() != noErr)
 return (0L);

/* open port and set port variables */
GetPort(&oldPort);
OpenPort(offPort);
offPort->portRect = *theBounds;

if (NewBitMap(&(offPort->portBits), theBounds) == (0L)) {
 ClosePort(offPort);
 SetPort(oldPort);
 DisposPtr((Ptr) offPort);
 return(0L);
 }

RectRgn(offPort->clipRgn, theBounds);
RectRgn(offPort->visRgn, theBounds);

EraseRect(theBounds);

SetPort(oldPort);

return(offPort);


} /* NewOffScreen() */

/************************************/
/* void DisposOffScreen()
 destroys an offscreen grafport */
/************************************/
void DisposOffScreen(offPort)
GrafPtr offPort;
{ /* DisposOffScreen() */
ClosePort(offPort);
DisposBitMap(&(offPort->portBits));
DisposPtr((Ptr) offPort);
} /* DisposOffScreen() */

/************************************/
/* void WipeTopBottom()
 WipeTopBottom transfers one image on top of another
in segments called partitions with an optional pause */
/************************************/
void WipeTopBottom(srcBits, dstBits, srcRect, dstRect, mode, mask, partitions, 
pauseTicks)
BitMap *srcBits, *dstBits;
Rect *srcRect, *dstRect;
int mode;
RgnHandle mask;
int partitions;
long pauseTicks;
{ /*WipeTopBottom */
int width,i, j;
Rect partSRect, partDRect;
long ticks;

width = (srcRect->bottom - srcRect->top) / partitions;
while ((partitions * width) < (srcRect->bottom - srcRect->top)) width 
+= 1;

for (j=0; j<width; j++) { /* increment pane */
 ticks = TickCount();
 
 for (i=0; i<partitions; i++) { /* each pane */
 SetRect(&partSRect, srcRect->left,
 (srcRect->top) + (i * width) + j,
 srcRect->right,
 (srcRect->top) + (i * width) + j + 1);
 
 if (partSRect.bottom > srcRect->bottom) partSRect.bottom = srcRect->bottom;
 
 partDRect = partSRect;
 MapRect(&partDRect, srcRect, dstRect);
 
 CopyBits(srcBits, dstBits, &partSRect, &partDRect, mode, mask);
 } /* each pane */
 
 while (TickCount() < ticks + pauseTicks) ;
 } /* increment pane */
 
} /*WipeTopBottom */

/************************************/
/* void WipeBottomTop()
 WipeBottomTop transfers one image on top of another
in segments called partitions with an optional pause */
/************************************/
void WipeBottomTop(srcBits, dstBits, srcRect, dstRect, mode, mask, partitions, 
pauseTicks)
BitMap *srcBits, *dstBits;
Rect *srcRect, *dstRect;
int mode;
RgnHandle mask;
int partitions;
long pauseTicks;
{ /*WipeBottomTop */
int width,i, j;
Rect partSRect, partDRect;
long ticks;

width = (srcRect->bottom - srcRect->top) / partitions;
while ((partitions * width) < (srcRect->bottom - srcRect->top)) width 
+= 1;

for (j=0; j<width; j++) { /* increment pane */
 ticks = TickCount();
 
 for (i=0; i<partitions; i++) { /* each pane */
 SetRect(&partSRect, srcRect->left,
 (srcRect->bottom) - (i * width) - j - 1,
 srcRect->right,
 (srcRect->bottom) - (i * width) - j);
 
 if (partSRect.top < srcRect->top) partSRect.top = srcRect->top;
 
 partDRect = partSRect;
 MapRect(&partDRect, srcRect, dstRect);
 
 CopyBits(srcBits, dstBits, &partSRect, &partDRect, mode, mask);
 } /* each pane */
 
 while (TickCount() < ticks + pauseTicks) ;
 } /* increment pane */
 
} /*WipeBottomTop */

/************************************/
/* void WipeLeftRight()
 WipeLeftRight transfers one image on top of another
in segments called partitions with an optional pause */
/************************************/
void WipeLeftRight(srcBits, dstBits, srcRect, dstRect, mode, mask, partitions, 
pauseTicks)
BitMap *srcBits, *dstBits;
Rect *srcRect, *dstRect;
int mode;
RgnHandle mask;
int partitions;
long pauseTicks;
{ /*WipeLeftRight */
int width,i, j;
Rect partSRect, partDRect;
long ticks;

width = (srcRect->right - srcRect->left) / partitions;
while ((partitions * width) < (srcRect->right - srcRect->left)) width 
+= 1;

for (j=0; j<width; j++) { /* increment pane */
 ticks = TickCount();
 
 for (i=0; i<partitions; i++) { /* each pane */
 SetRect(&partSRect, srcRect->left + (i * width) + j,
 srcRect->top,
 srcRect->left + (i * width) + j + 1,
 srcRect->bottom);
 
 if (partSRect.right > srcRect->right) partSRect.right = srcRect->right;
 
 partDRect = partSRect;
 MapRect(&partDRect, srcRect, dstRect);
 
 CopyBits(srcBits, dstBits, &partSRect, &partDRect, mode, mask);
 } /* each pane */
 
 while (TickCount() < ticks + pauseTicks) ;
 } /* increment pane */
 
} /*WipeLeftRight */

/************************************/
/* void WipeRightLeft()
 WipeRightLeft transfers one image on top of another
in segments called partitions with an optional pause */
/************************************/
void WipeRightLeft(srcBits, dstBits, srcRect, dstRect, mode, mask, partitions, 
pauseTicks)
BitMap *srcBits, *dstBits;
Rect *srcRect, *dstRect;
int mode;
RgnHandle mask;
int partitions;
long pauseTicks;
{ /*WipeRightLeft */
int width,i, j;
Rect partSRect, partDRect;
long ticks;

width = (srcRect->right - srcRect->left) / partitions;
while ((partitions * width) < (srcRect->right - srcRect->left)) width 
+= 1;

for (j=0; j<width; j++) { /* increment pane */
 ticks = TickCount();
 
 for (i=0; i<partitions; i++) { /* each pane */
 SetRect(&partSRect, srcRect->right - (i * width) - j - 1,
 srcRect->top,
 srcRect->right - (i * width) - j,
 srcRect->bottom);
 
 if (partSRect.left < srcRect->left) partSRect.left = srcRect->left;
 
 partDRect = partSRect;
 MapRect(&partDRect, srcRect, dstRect);
 
 CopyBits(srcBits, dstBits, &partSRect, &partDRect, mode, mask);
 } /* each pane */
 
 while (TickCount() < ticks + pauseTicks);
 } /* increment pane */
 
} /*WipeRightLeft */

/************************************/
/* void Iris()
 Iris uses CopyBits to transfer one image on top of another
using an iris region with an optional pause */
/************************************/
void Iris(srcBits, dstBits, srcRect, dstRect, mode, mask,
irisRgn, pauseTicks)
BitMap *srcBits, *dstBits;
Rect *srcRect, *dstRect;
int mode;
RgnHandle mask;
long pauseTicks;
RgnHandle irisRgn;
{ /* Iris() */
long ticks;
RgnHandle theMask, sumRgn;
RgnHandle iris;

/* prepare iris */
iris = NewRgn();
CopyRgn(irisRgn, iris);

sumRgn = NewRgn();
SetEmptyRgn(sumRgn);

theMask = NewRgn();

while (!EqualRgn(mask, sumRgn)) {
 SectRgn(iris, mask, theMask);
 ticks = TickCount();
 CopyBits(srcBits, dstBits, srcRect, dstRect, mode, theMask);
 while (TickCount() < ticks + pauseTicks);
 
 /* create new iris region */
 UnionRgn(sumRgn, theMask, sumRgn);
 InsetRgn(iris, -1, -1);
 DiffRgn(iris, sumRgn, iris);
 } /* while */
 
DisposeRgn(sumRgn);
DisposeRgn(iris);
DisposeRgn(theMask);
} /* Iris() */

/************************************/
/* void FadePat()
 FadePat transfers one image on top of another
using a series of patterns with an optional pause */
/************************************/
void FadePat(srcBits, dstBits, srcRect, dstRect, mode, mask,
patList, patCount, pauseTicks)
BitMap *srcBits, *dstBits;
Rect *srcRect, *dstRect;
int mode;
RgnHandle mask;
long pauseTicks;
int patList;
int patCount;
{ /* FadePat() */
int i;
long ticks;
Pattern pat;
BitMap bm, *bmPtr;
Ptr p;
GrafPort gp, *savePort;
RgnHandle theRgn;

p = NewBitMap(&bm, srcRect);
if (p == 0L) return;

bmPtr = (BitMap *) &bm;

GetPort(&savePort);
OpenPort(&gp);
SetPortBits(bmPtr);
RectRgn(gp.clipRgn, &(bmPtr->bounds));
RectRgn(gp.visRgn, &(bmPtr->bounds));
gp.portRect = bmPtr->bounds;

for (i=1; i<= patCount; i++) { /* pattern loop */
 GetIndPattern(&pat, patList, i);
 PenPat(pat);
 PaintRect(srcRect);
 theRgn = MakeRgn(bmPtr);
 ticks = TickCount();
 CopyBits(srcBits, bmPtr, srcRect, srcRect, srcCopy, theRgn);
 
 MapRgn(theRgn, srcRect, dstRect);
 CopyBits(bmPtr, dstBits, srcRect, dstRect, mode, theRgn);
 while (TickCount() < ticks + pauseTicks);
 DisposeRgn(theRgn);
 } /* pattern loop */
 
ClosePort(&gp);
SetPort(savePort);

DisposPtr(p);
} /* FadePat() */

/************************************/
/* void PageFlipDown()
 PageFlipDown transfers one image on top of another
(only in srcCopy Mode) with an optional pause */
/************************************/
void PageFlipDown(srcBits, dstBits, srcRect, dstRect, mask,
partitions, pauseTicks)
BitMap *srcBits, *dstBits;
Rect *srcRect, *dstRect;
RgnHandle mask;
int partitions;
long pauseTicks;
{ /* PageFlipDown() */
Rect tempRect = *dstRect;
char done = 0;
long ticks;

tempRect.bottom = tempRect.top + partitions;
if (tempRect.bottom > dstRect->bottom) tempRect.bottom = dstRect->bottom;
while (!done) {
 ticks = TickCount();
 CopyBits(srcBits, dstBits, srcRect, &tempRect, srcCopy, mask);
 while (TickCount() < ticks + pauseTicks);
 
 if (tempRect.bottom == dstRect->bottom) done = 1;
 tempRect.bottom = tempRect.bottom + partitions;
 if (tempRect.bottom > dstRect->bottom) tempRect.bottom = dstRect->bottom;
 }
} /* PageFlipDown() */

/************************************/
/* void PageFlipRight()
 PageFlipRight transfers one image on top of another
(only in srcCopy Mode) with an optional pause */
/************************************/
void PageFlipRight(srcBits, dstBits, srcRect, dstRect, mask, partitions, 
pauseTicks)
BitMap *srcBits, *dstBits;
Rect *srcRect, *dstRect;
RgnHandle mask;
int partitions;
long pauseTicks;
{ /* PageFlipRight() */
Rect tempRect = *dstRect;
char done = 0;
long ticks;

tempRect.right = tempRect.left + partitions;
if (tempRect.right > dstRect->right) tempRect.right = dstRect->right;
while (!done) {
 ticks = TickCount();
 CopyBits(srcBits, dstBits, srcRect, &tempRect, srcCopy, mask);
 while (TickCount() < ticks + pauseTicks);
 
 if (tempRect.right == dstRect->right) done = 1;
 tempRect.right = tempRect.right + partitions;
 if (tempRect.right > dstRect->right) tempRect.right = dstRect->right;
 }
} /* PageFlipRight() */

Listing:  General.h

/************************************
General.h

General and useful constants
************************************/

#define _H_General

#ifndef TRUE
#define TRUE (1)
#endif

#ifndef true
#define true (1)
#endif

#ifndef FALSE
#define FALSE (0)
#endif

#ifndef false
#define false (0)
#endif

#ifndef NULL
#define NULL ((void *) 0)
#endif

#ifndef null
#define null ((void *) 0)
#endif

#ifndef NIL
#define NIL ((void *) 0)
#endif

#ifndef nil
#define nil ((void *) 0)
#endif

#define WindowInFront ((WindowPtr)-1)

#define NONE 0
#define CENTER 2
#define THIRD 3

/* SICN declarations */
typedef short SICN[16];
typedef SICN *SICNList;
typedef SICNList *SICNHandle;

#ifndef _DialogMgr_
#include “DialogMgr.h”
#endif

/* DITL declarations */
typedef struct DITLItem {
 long HorP;
 Rect displayRect;
 char itemType;
 char dataLength;
 } DITLItem, *DITLItemPtr, **DITLItemHandle;

OSErr AddDItem(Handle *theDITL, char theType, Rect * theRect, char *param);

void PositionRect(Rect *small, Rect *large, int hOption, int vOption);

/* SICN Routines */
SICNHandle GetSICN(int sicnID);
long CountSICN(SICNHandle theSICN);
void PlotSICN(Rect *theRect, SICNHandle theSICN, long theIndex);

Listing:  General.c

/************************************/
/* General.c

Contains some general functions */
/************************************/
#include “General.h”

/* Routines are as follows:

 • int MenuBarHeight(void)
 • void PositionRect(small, large, hOption, vOption)
 • OSErr AddDItem(theDITL, theType, theRect, param)
 • SICNHandle GetSICN(sicnID)
 • long CountSICN(theSICN)
 • void PlotSICN(theRect, theSICN, theIndex)
*/

/* routines */
/************************************/
/* int MenuBarHeight(void)
 Gets the current height of the menu bar */
/************************************/
int MenuBarHeight(void)
{
#define  mBarHeightGlobal 0xBAA
int *memPtr;

memPtr = (int *) mBarHeightGlobal;

if (*memPtr < 20)
 return (20);
else
 return(*memPtr);
} /* int MenuBarHeight(void) */

/************************************/
/* void PositionRect(small, large, hOption, vOption)
 takes two rectangles, small and large, and positions
 the smaller one horiz. and vert. according to
 options */
/************************************/
void PositionRect(small, large, hOption, vOption)
Rect *small, *large;
int hOption, vOption;
{
int hOff, vOff;

if (hOption != 0) {
 small->right -= small->left;
 small->left = 0;
 hOff = (large->right - large->left - small->right) / hOption;
 small->left = large->left + hOff;
 small->right += small->left;
 }
 
if (vOption != 0) {
 small->bottom -= small->top;
 small->top = 0;
 vOff = (large->bottom - large->top - small->bottom) / vOption;
 small->top = large->top + vOff;
 small->bottom += small->top;
 }
} /* void PositionRect(small, large, hOption, vOption) */

/************************************/
/* OSErr AddDItem(theDITL, theType, theRect, param)
 adds a dialog item to a dialog item list creating
 it if needed */
/************************************/
OSErr AddDItem(theDITL, theType, theRect, param)
Handle *theDITL;
char theType;
Rect *theRect;
char *param;
{
char *p;
DITLItemPtr d;
OSErr error;
int **itemCount, i;
char baseType, dataLen, dataLenDITL;

/* 1.  Check on first one and get count
 2.  Get size to add onto handle
 3.  Loop to place
 4.  Put data in
*/

/* 1.  Check on first one */
baseType = theType;
if ((unsigned char) baseType >= itemDisable) baseType -= itemDisable;
switch (baseType) {
 case ctrlItem + btnCtrl:
 case ctrlItem + chkCtrl:
 case ctrlItem + radCtrl:
 case statText:
 case editText:
 dataLen = *param;
 break;
 case ctrlItem + resCtrl:
 case iconItem:
 case picItem:
 dataLen = 2;
 break;
 case userItem:
 dataLen = 0;
 break;
 
 default:
 return(-50); /* unknown type */
 }

if (*theDITL == NIL) { /* first item */
 *theDITL = NewHandle(2);
 if ((error = MemError()) != noErr) return(error);
 itemCount = (int **) *theDITL;
 **itemCount = -1;
 } /* first item */
else { /* another item */
 itemCount = (int **) *theDITL;
 }

/* 2.  Get size to add onto handle */
/* Get size to make handle */
dataLenDITL = dataLen;
if (dataLenDITL % 2) ++dataLenDITL;

/* increase handle size */
SetHandleSize(*theDITL, GetHandleSize(*theDITL) + sizeof(DITLItem) + 
dataLenDITL);
if ((error = MemError()) != noErr) return(error);

/* 3.  Loop to place */
HLock(*theDITL);
p = (char *) (**theDITL) + 2;

for (i=0; i<= (int) (**itemCount); i++) { /* item loop */
 d = (DITLItemPtr) p;
 dataLenDITL = (int) (*d).dataLength;
 if (dataLenDITL % 2) ++dataLenDITL;
 p = p + sizeof(DITLItem) + dataLenDITL;
 } /* item loop */

d = (DITLItemPtr) p;

/* 4.  Put data in */
if (baseType == userItem)
 (*d).HorP = (long) param;
else
 (*d).HorP = 0L;
(*d).displayRect = *theRect;
(*d).itemType = theType;
(*d).dataLength = (char) dataLen;

p = p + sizeof(DITLItem);
switch (baseType) {
 case ctrlItem + btnCtrl:
 case ctrlItem + chkCtrl:
 case ctrlItem + radCtrl:
 case statText:
 case editText:
 BlockMove(param + 1, p, dataLen);
 break;
 case ctrlItem + resCtrl:
 case iconItem:
 case picItem:
 BlockMove(param + 2, p, dataLen);
 break;
 
 case userItem:
 break;
 
 default:;
 }

**itemCount = (int) (**itemCount) + 1;

HUnlock(*theDITL);
} /* OSErr AddDItem(theDITL, theType, theRect, param) */

/************************************/
/* SICNHandle GetSICN(sicnID)
 Gets a sicn handle */
/************************************/
SICNHandle GetSICN(sicnID)
int sicnID;
{
return ((SICNHandle) GetResource(‘SICN’, sicnID));
} /* SICNHandle GetSICN(sicnID) */

/************************************/
/* long CountSICN(theSICN)
 counts the sicn in a sicn handle */
/************************************/
long CountSICN(theSICN)
SICNHandle theSICN;
{
return ((long) (GetHandleSize((Handle) theSICN) / sizeof(SICN)) );
} /* long CountSICN(theSICN) */

/************************************/
/* void PlotSICN(theRect, theSICN, theIndex)
 plots a small icon */
/************************************/
void PlotSICN(theRect, theSICN, theIndex)
Rect *theRect;
SICNHandle theSICN;
long theIndex;
{
auto char state; /* saves original flags of SICN handle */
auto BitMap srcBits; /* built up around SICN data so we can _CopyBits 
*/

/* check the index for a valid value */
if (((GetHandleSize((Handle)theSICN)) / sizeof(SICN)) > theIndex) {
 /* store the resource’s current locked/unlocked condition */
 state = HGetState((Handle) theSICN);
 
 /* lock the resource so it won’t move during _CopyBits */
 HLock((Handle) theSICN);
 
 /* set up small icon’s bitmap */
 srcBits.baseAddr = (Ptr) (*theSICN)[theIndex];
 srcBits.rowBytes = 2;
 SetRect(&srcBits.bounds, 0, 0, 16, 16);
 
 /* draw the small icon in the current grafport */
 CopyBits(&srcBits, &(thePort->portBits), &srcBits.bounds, theRect, srcCopy, 
NIL);
 
 /* restore handle’s state */
 HSetState((Handle) theSICN, state);
 }
} /* void PlotSICN(theRect, theSICN, theIndex) */

Listing:  Transition.Π.r

resource ‘PAT#’ (1000) {
 { /* array PatArray: 8 elements */
 $”0420 0210 8001 0840",
 $”4001 1008 0420 8002",
 $”1080 0820 0240 0401",
 $”0208 4001 2004 1080",
 $”0110 0480 0802 4020",
 $”2002 8004 4010 0108",
 $”0840 0102 1080 2004",
 $”8004 2040 0108 0210"
 }
};

resource ‘PAT#’ (4000) {
 { /* array PatArray: 8 elements */
 $”0101 0101 0101 0101",
 $”0202 0202 0202 0202",
 $”0404 0404 0404 0404",
 $”0808 0808 0808 0808",
 $”1010 1010 1010 1010",
 $”2020 2020 2020 2020",
 $”4040 4040 4040 4040",
 $”8080 8080 8080 8080"
 }
};

resource ‘PAT#’ (3000) {
 { /* array PatArray: 8 elements */
 $”0804 0201 8040 2010",
 $”0402 0180 4020 1008",
 $”1008 0402 0180 4020",
 $”0201 8040 2010 0804",
 $”2010 0804 0201 8040",
 $”0180 4020 1008 0402",
 $”4020 1008 0402 0180",
 $”8040 2010 0804 0201"
 }
};

resource ‘PAT#’ (2000) {
 { /* array PatArray: 8 elements */
 $”C0C0 0000 0C0C 0000",
 $”0C0C 0000 C0C0 0000",
 $”0000 3030 0000 0303",
 $”0000 0303 0000 3030",
 $”0303 0000 3030 0000",
 $”3030 0000 0303 0000",
 $”0000 0C0C 0000 C0C0",
 $”0000 C0C0 0000 0C0C”
 }

};

Note from Nov 91 Letters

BitMap Error

Kirk Chase

I would like to point out an error in some code published in MacTutor, November 1990 ("Special Effect") and June 1991 ("Kolorize Your B&W Application"). Basically the code in question is the offscreen bitmap allocation function used in both articles. The offending line in the procedure NewBitMap is

bm->baseAddr=NewPtr(bm->rowBytes *(long (r->right - r->left));

This assumes a height the same size as the width. Correct it to the following:

/* Fix */

bm->baseAddr=NewPtr(bm->rowBytes *(long (r->bottom - r->top));

Thanks to Randy Frank for pointing this out.