Animate PICS
Volume Number: | | 7
|
Issue Number: | | 3
|
Column Tag: | | Developer Forum
|
Related Info: Picture Utilities
Animating PICS
By Steven Sheets, Herdon, VA
Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.
Animating PICS
In the spring of 1988, at the Apple Developer Conference, a standard was agreed upon by several animation and graphic developers that would allow each developer to import and export simple animation sequences. (An animation sequence is a group of pictures that when shown sequentially create an animated image). Since that time, most animation developers have either implemented this standard in their programs, or have promised to have it implemented in the near future. The name of this standard is PICS.
While obviously animation packages need to know how to manipulate PICS files, any Macintosh program can use these files, and display the animated images. The file format is extremely simple and the code needed to animate the images is easy to write and understand.
The main advantage in using PICS files is that while most Macintosh developers know how to animate a bit or pixel map across the screen, they are usually lousy artists. The images they create are often extremely crude, and fail to have a finished look. This is especially true if the programmer has to create the bit or pixel map by hand and enter the image in as hex data. Instead of these amateurish attempts, a developer can now create (or have his friend the graphic artist create for him) a professional looking animation sequence using professional animation packages and tools. Once the sequence is completed, the programmer can then import the created PICS data into his program, and animate it himself.
This article will cover how to animate PICS files. First the file format will be described. Then a sample program will be given that displays PICS files. The program will include PICSUnit, a unit that reads, disposes and draws PICS data structures.
PICS File Format
The file type for a PICS file is PICS. The file creator should be set to the creator type of whatever animation package exported the data. It is recommended that the following icon be used:
The hex data for this icon is given in the example program (even though the example does not create PICS files).
The PICS file itself consists of one or more resources. The files data fork is not used by the PICS format. PICS file format is an open ended format in that a developer (or group of developers) can add or use as much information as he wishes. Only one resource is required, although that would make a very short animation sequence. If another application duplicates a PICS file, all resources should be copied. A resource that is not used by one animation package might be used by another.
The single required resource is a picture (resource type PICT, id number 128). This picture is the initial setting of the animation sequence. All animation will be done inside the rectangle defined by this pictures picFrame rectangle. Normally a pictures picFrame is set so that top and left are 0 (zero), while the bottom and right are the height and width of the picture. But be careful! This is not always the case; the top left can be any value. Whatever the top left is, the following drawing is done in that coordinate system.
Once the first frame is defined, each new frame of animation is defined in a new PICT resource. The resource ID of this new frame is sequentially in order after the preceding frame. Thus if the PICS file contains 10 frames, there would be 10 PICT resource in the file, number 128 through 137.
The PICT resource for all the frames after the first one need not be an entire image. The picFrame of the PICT resource defines exactly how the frame is displayed. In all cases, the picFrame of the new PICT should never be larger, or outside, than the picFrame of the first PICT.
First, the picture handle can contain an empty picFrame (usually coordinate 0,0,0,0, but really any coordinates where right is less than or equal to left or bottom is less than or equal to top). In this case, no new animation is displayed for this frame. Such a frame is often used to pause the animation.
Second, a frame can contain an image the exact size, and coordinates of the first PICT. In this case, the entire image is drawn using the same coordinates and rectangle as the first PICT.
Finally, a frame can have only the changes from the previous frame. In that case, the picFrame of the PICT resource would be smaller than the size of the entire image. The picture should only be drawn in the rectange given in the picFrame (again using the coordinate system of the first PICT). The PICT for such a frame is often called a delta picture (PICT containing the difference). The advantage of this type of frame is memory size. If an animation image is large, but the difference from one frame to another is smaller, a series of delta pictures is much smaller in byte size than the same number of pictures of the entire image.
In addition to the animation frame, there was one other optional resource. A resource of type INFO and id 128 provides additional information about the animation sequence. The following is the resource Pascal data structure. Remember that, like the file format, this structure may be expanded in the future with additional fields. The resource handle may be longer than this structure:
{1}
TYPE TPICSInfoRec = RECORD
BWColor: INTEGER; {0 = Black & White, 1 = Color}
Depth: INTEGER; {1,2,4,8,16 pixel depth}
Speed: INTEGER; {1..200 frames per sec}
{ else negative seconds per frame}
Version: INTEGER; {0 currently}
Creator: ResType; {original creator signature}
Largest: LongInt; {if non-zero, largest picture size}
END;
TPICSInfoPtr = ^TPICSInfoRec;
TPICSInfoHdl = ^TPICSInfoPtr;
The first field of the structure (BWColor) tells if the animation sequence is in black & white or color. If the sequence is in color, the next field (depth) defines the depth (in pixels) of the image (or in other words, the numbers of colors 1, 4, 16, 256, or more). The next field (Depth) defines the speed that the animation images are displayed on the screen. If the number is 1 to 200, then that number is the number of frames per second. Remember, due to the flicker rate of most Mac screens (around 60 frames of sec) animation of more than 60 frames per sec is impossible. If the Speed number is negative, than the absolute value of Speed is the number of seconds between frames. The Version field defines the version of the file format (currently 0), while the Creator field shows the creator of the data (regardless of what the file type creator was set to). The last field, Largest, gives the size of the largest frame (PICT resource) in bytes. This is an optional field, and may contain the value zero.
The PICS format does have its deficiencies. The format could have been expanded to allow better use of memory. For example, the pictures should have been able to be used in more than one frame. Many times, animation sequences return to the same image over and over again. The PICS format requires each frame to have its own picture, even if that image is used in more than one spot. Also, the drawing of the delta frames could have used an X & Y position value. This would have allowed the same picture to be animated across the screen. The PICS format requires multiple pictures even if the image is the same but in a different position.
There are a couple more items that could have been added to the format. The amount of time between two given frames should have been variable. Finally, a color table could have been provided for color animation sequences, that would give the optimal colors for the sequence.
Example Program
The example program demonstrates how code can use PICSUnit, a Pascal unit that manipulates PICS. PICSUnit consists of 3 calls; ReadPICS (which reads a PICS file into memory and creates a PICS data structure), DisposPICS (which disposes of a PICS data structure in memory), and DrawPICS (which animates the PICS data structure in the current grafport at a given X & Y position). Notice that a PICS data structure in memory is a complex handle (ie. handle that contains other handles in it). Be sure to use the DisposPICS call, or a program will start to use up memory with unreferenced handles.
The DrawPICS routine is also passed two flags to indicate how many times to draw the animation (once or continuous) and also whether or not the animation should stop if the user presses a key or the mouse. Be careful! If the call is set for continuous animation without stopping when the user prompts, the program will go into a endless loop of animation (very pretty, but not a very good user interface).
What Next?
Obviously the example program could be improved. The PICSUnit could be rewritten for performance, at the cost of more memory. Drawing with a PICT handle can be a time consuming action; flickering can also occur. If offscreen grafports (and color grafports) were used, the images could be drawn there. Then when it is time for a new frame to be animated, Copybits could be used to move the image onto the screen. For that matter, multiple offscreen grafports could be created for each frame (assuming enough memory), thus speeding up the animation and eliminating flickers.
The example program that uses the PICSUnit is not the end-all utility it could be. A Public Domain PICS Editor would be very useful (any one interested?). Such an Editor would show each frame of animation, and allow the user to step through the frames any way they wished.
Other PICS utilities could be useful. Perhaps a program that takes a PICS file that consists of PICTs all the same size (regardless of how much of the image changes), and calculates exactly the portion of the image that changes from one frame to another. It would then output a PICS file consisting of these delta PICTs. Such a utility would greatly reduce the size of a PICS file.
As always, any comment or ideas or suggestions are always appreciated.
Listing: PICSUnit.p
{}
{PICS Unit- Steve Sheets}
{}
{This Unit provides the Interface to the PICS data structure}
{as well as the procedures to create, dispose and draw the}
{PICS information.}
unit PICSUnit;
interface
const
kPICStype = 'PICS'; {File type of PICS}
kINFOtype = 'INFO';
{Resource type of PICS information resource}
{Interface for the optional information handle and the PICS handle which
contains 1 or more Pictures and the information handle. Notice that the
PICS handle is a variable length handle based on the number of frames.}
type
TPICSInfoRec = record
BWColor: INTEGER; {0 = Black & White, 1 = Color}
Depth: INTEGER; {1,2,4,8,16 pixel depth}
Speed: INTEGER; {1..200 frames per sec, else negative seconds per frame}
Version: INTEGER; {0 currently}
Creator: ResType; {original creator signature}
Largest: LongInt; {if non-zero, largest picture size}
end;
TPICSInfoPtr = ^TPICSInfoRec;
TPICSInfoHdl = ^TPICSInfoPtr;
TPICSRec = record
NumFrames, DimH, DimV: INTEGER;
PICSInfoHdl: TPICSInfoHdl;
Frame: array[1..1] of PicHandle;
end;
TPICSPtr = ^TPICSRec;
TPICSHdl = ^TPICSPtr;
{Given a file name and volume reference number, try to read the PICS
file at that location. If successful, return noErr in the function and
the information in thePICS parameter. If there was a problem, return
the error number in the function, and thePICS is set to NIL.}
function ReadPICS (theFileName: Str255;
theVRefNum: INTEGER;
var thePICS: TPICSHdl): OSErr;
{Given thePICS data, dispos of all the handles and data structures.}
procedure DisposePICS (thePICS: TPICSHdl);
{Given thePICS data, and an V & H position to draw at, draw the animation.
The Loopflag tells the procedure to either loop the animation continously
(TRUE), or only draw once time (FALSE). The ScanKeyFlag tells the procedure
if it should look to see if someone has pressed a key during animation.
If so, the procedure is stopped at that point. Notice that it is dangerous
to have Loopflag set TRUE and ScanKeyFlag set FALSE (infinite loop time).}
procedure DrawPICS (thePICS: TPICSHdl;
HPos, VPos: INTEGER;
LoopFlag, ScanKeyFlag: BOOLEAN);
implementation
{Simple utility function, given number of frames, size of the TPICSRec
record in bytes.}
function PICSsize (theNumFrames: INTEGER): INTEGER;
begin
PICSsize := (theNumFrames * 4) + 10;
end;
function ReadPICS (theFileName: Str255;
theVRefNum: INTEGER;
var thePICS: TPICSHdl): OSErr;
var
tempE: OSErr;
tempResNum: INTEGER;
tempSize: INTEGER;
tempPICS: TPICSHdl;
tempPicture: PicHandle;
tempFlag: BOOLEAN;
begin
thePICS := nil;
tempPICS := nil;
tempPicture := nil;
tempResNum := OpenRFPerm(theFileName, theVRefNum, 0);
if tempResNum = -1 then
tempE := ResError
else
begin
tempPicture := PicHandle(Get1Resource('PICT', 128));
if tempPicture = nil then
tempE := ResError
else
begin
HNoPurge(Handle(tempPicture));
DetachResource(Handle(tempPicture));
tempSize := 100;
tempPICS := TPICSHdl(NewHandle(PICSsize(tempSize)));
if tempPICS = nil then
tempE := MemError
else
begin
with tempPICS^^ do
begin
NumFrames := 1;
with tempPicture^^.picFrame do
begin
DimH := Right - Left;
DimV := Bottom - Top;
end;
PICSInfoHdl := nil;
Frame[1] := tempPicture;
end;
tempPicture := nil;
tempPICS^^.PICSInfoHdl :=
TPICSInfoHdl(Get1Resource(kINFOtype, 128));
if tempPICS^^.PICSInfoHdl <> nil then
begin
HNoPurge(Handle(tempPICS^^.PICSInfoHdl));
DetachResource(Handle(tempPICS^^.PICSInfoHdl));
end;
tempFlag := FALSE;
repeat
tempPicture := PicHandle(Get1Resource('PICT', 128 +
tempPICS^^.NumFrames));
if tempPicture = nil then
begin
tempE := ResError;
if (tempE = resNotFound) or (tempE = noErr) then
begin
tempE := noErr;
SetHandleSize(Handle(tempPICS),
PICSsize(tempPICS^^.NumFrames));
thePICS := tempPICS;
tempPICS := nil;
end;
tempFlag := TRUE;
end
else
begin
HNoPurge(Handle(tempPicture));
DetachResource(Handle(tempPicture));
if tempPICS^^.NumFrames = tempSize then
begin
tempSize := tempSize + 100;
SetHandleSize(Handle(tempPICS),
PICSsize(tempSize));
tempE := ResError;
end;
if tempE = noErr then
begin
tempPICS^^.NumFrames := tempPICS^^.NumFrames
+ 1;
tempPICS^^.Frame[tempPICS^^.NumFrames] :=
tempPicture;
tempPicture := nil;
end
else
tempFlag := TRUE;
end;
until tempFlag;
end;
end;
CloseResFile(tempResNum);
end;
if tempPICS <> nil then
DisposePICS(tempPICS);
if tempPicture <> nil then
DisposHandle(Handle(tempPicture));
ReadPICS := tempE;
end;
procedure DisposePICS (thePICS: TPICSHdl);
var
tempNum: INTEGER;
begin
if thePICS <> nil then
begin
if thePICS^^.PICSInfoHdl <> nil then
DisposHandle(Handle(thePICS^^.PICSInfoHdl));
for tempNum := 1 to thePICS^^.NumFrames do
DisposHandle(Handle(thePICS^^.Frame[tempNum]));
DisposHandle(Handle(thePICS));
end;
end;
procedure DrawPICS (thePICS: TPICSHdl;
HPos, VPos: INTEGER;
LoopFlag, ScanKeyFlag: BOOLEAN);
var
tempRect: Rect;
tempTicks: LongInt;
tempDone: BOOLEAN;
tempCount: INTEGER;
{Wait tempTicks number of ticks, stopping at any time if mouse or key
is pressed.}
procedure WaitFrame;
var
tempLong: LongInt;
tempEvent: EventRecord;
begin
tempLong := tickCount + tempTicks;
while (tempLong > tickCount) and (not tempDone) do
begin
SystemTask;
tempDone := GetNextEvent(mDownMask + keyDownMask + autoKeyMask, tempEvent);
end;
end;
begin
if thePICS <> nil then
if thePICS^^.NumFrames > 0 then
if thePICS^^.Frame[1] <> nil then
begin
tempDone := FALSE;
if thePICS^^.PICSInfoHdl <> nil then
begin
tempTicks := thePICS^^.PICSInfoHdl^^.Speed;
if tempTicks <= 0 then
tempTicks := -60 * tempTicks
else
tempTicks := 60 div tempTicks;
end
else
tempTicks := 6;
repeat
tempCount := 0;
repeat
tempCount := tempCount + 1;
if thePICS^^.Frame[tempCount] <> nil then
if not
EmptyRect(thePICS^^.Frame[tempCount]^^.PicFrame)
then
begin
tempRect := thePICS^^.Frame[tempCount]^^.PicFrame;
OffSetRect(tempRect, HPos, VPos);
DrawPicture(thePICS^^.Frame[tempCount], tempRect);
end;
WaitFrame;
until tempDone or (tempCount >= thePICS^^.NumFrames);
until tempDone or (not LoopFlag);
end;
end;
end.
Listing: PICSPlayer.p
{PICS Player- Steve Sheets}
{}
{This Progam displays a PICS animation sequence. It loads PICS files,
animates the file once or animates it in a continous loop. Either animation
can be canceled by pressing any key. The program uses alerts to prompt
the user for actions. The actual animation is drawn in a window the
size of the screen.}
program PICSplayer;
uses
PICSUnit;
const
kLoadQuit = 500;
kPICSinfo = 501;
kError = 502;
kColorProblem = 503;
var
gDone, gColorFlag: BOOLEAN;
gName: Str255;
gNum: INTEGER;
gPICS: TPICSHdl;
gWindow: WindowPtr;
procedure SetUp;
const
ROM85Loc = $28E;
TwoHighMask = $C000;
type
WordPtr = ^INTEGER;
var
tempWordPtr: WordPtr;
begin
tempWordPtr := POINTER(ROM85Loc);
gColorFlag := (BitAnd(tempWordPtr^, TwoHighMask) = 0);
gDone := FALSE;
gName := '';
gPICS := nil;
if gColorFlag then
gWindow := NewCWindow(nil, Screenbits.Bounds, '',
TRUE, dBoxProc, POINTER(-1), FALSE, 0)
else
gWindow := NewWindow(nil, Screenbits.Bounds, '',
TRUE, dBoxProc, POINTER(-1), FALSE, 0);
if gWindow <> nil then
begin
SetPort(gWindow);
EraseRect(screenbits.bounds);
end;
SetCursor(Arrow);
end;
procedure ShutDown;
begin
if gPICS <> nil then
begin
DisposePICS(gPICS);
gPICS := nil;
end;
if gWindow <> nil then
begin
DisposeWindow(gWindow);
gWindow := nil;
end;
end;
procedure PlayPICS (Loop: BOOLEAN);
var
tempH, tempV: INTEGER;
begin
if gPICS <> nil then
begin
SelectWindow(gWindow);
SetPort(gWindow);
EraseRect(screenbits.bounds);
with screenbits.bounds, gPICS^^ do
begin
tempH := (right - left - DimH) div 2;
tempV := (bottom - top - DimV) div 2;
if tempH < 0 then
tempH := 0;
if tempV < 0 then
tempV := 0;
end;
HideCursor;
DrawPICS(gPICS, tempH, tempV, Loop, TRUE);
ShowCursor;
EraseRect(screenbits.bounds);
end;
end;
procedure LoadPICS;
var
tempList: SFTypeList;
tempPt: Point;
tempE: OSErr;
tempStr: Str255;
tempNum: INTEGER;
tempReply: SFReply;
begin
if gPICS <> nil then
begin
DisposePICS(gPICS);
gPICS := nil;
end;
tempPt.v := 40;
tempPt.h := 40;
tempList[0] := kPICStype;
SFGetFile(tempPt, '', nil, 1, tempList, nil, tempReply);
if tempReply.good then
begin
gName := tempReply.fname;
tempE := ReadPICS(gName, tempReply.vRefNum, gPICS);
if tempE <> noErr then
begin
case tempE of
memFullErr:
tempStr := 'Memmory full error. The file you are reading is to large';
fnfErr:
tempStr := 'File not found error';
resNotFound:
tempStr := 'A required resource was not found in the file';
otherwise
begin
NumToString(tempE, tempStr);
tempStr := CONCAT('Error Number: ', tempStr);
end
end;
ParamText(gName, tempStr, '', '');
tempNum := Alert(kError, nil);
end
else if (not gColorFlag) and (gPICS <> nil) then
if (gPICS^^.PICSInfoHdl <> nil) then
if (gPICS^^.PICSInfoHdl^^.BWColor = 1) then
begin
ParamText(gName, '', '', '');
tempNum := Alert(kColorProblem, nil);
end;
end;
end;
procedure DoInformationAlert;
var
tempStr: Str255;
begin
NumToString(gPICS^^.NumFrames, tempStr);
ParamText(gName, tempStr, '', '');
gNum := Alert(kPICSinfo, nil);
end;
begin
SetUp;
if gWindow <> nil then
repeat
if gPICS = nil then
gNum := Alert(kLoadQuit, nil)
else
DoInformationAlert;
case gNum of
1:
PlayPICS(FALSE);
2:
LoadPICS;
3:
gDone := TRUE;
4:
PlayPICS(TRUE);
otherwise
end;
until gDone;
ShutDown;
end.
Listing: PICSPlayer.r
/*----------------------------------------------------------
#
#PICS Animator Resource Source
#
#Steve Sheets
#
----------------------------------------------------------*/
#include "Types.r"
#include "SysTypes.r"
type 'PcPl' as 'STR ';
resource 'PcPl' (0) {
"PICS Player 1.0, © Steve Sheets." };
resource 'vers' (1) {
0x1, 0x0, 0x0, -0x80, verUs, "1.0", "1.0, © 1990 Steve Sheets." };
resource 'vers' (2) {
0x1, 0x0, 0x0, -0x80, verUs, "1.0", "PICS Player 1.0" };
resource 'BNDL' (128) {
'PcPl', 0,
{ 'ICN#', { 0, 128, 1, 129 },
'FREF', { 0, 128, 1, 129 } } };
resource 'ICN#' (128) {
{ $"FFE0 0000 8030 0000 8010 0000 9FFC 0000"
$"9006 0000 9002 0000 93FF 8000 9200 C000"
$"9200 4000 927F F000 9240 1800 9240 1400"
$"9248 3F00 9248 4080 9248 8040 9249 3020"
$"924B C810 F24E 7F8F 1242 3007 1241 0007"
$"1E40 8007 0242 6007 0245 1FE7 03C8 811F"
$"005F C107 0040 0100 007F FF",
$"FFE0 0000 FFF0 0000 FFF0 0000 FFFC 0000"
$"FFFE 0000 FFFE 0000 FFFF 8000 FFFF C000"
$"FFFF C000 FFFF F000 FFFF F800 FFFF FC00"
$"FFFF FF00 FFFF FF80 FFFF FFC0 FFFF FFE0"
$"FFFF FFF0 FFFF FFFF 1FFF FFFF 1FFF FFFF"
$"1FFF FFFF 03FF FFFF 03FF FFFF 03FF FF1F"
$"007F FF07 007F FF00 007F FF" } };
resource 'ICN#' (129) {
{ $"FFE0 0000 8030 0000 8010 0000 9FFC 0000"
$"9006 0000 9002 0000 93FF 8000 9200 C000"
$"9200 4000 927F F000 9240 1800 9240 1400"
$"924F 9E00 9248 8200 9248 8200 9248 C200"
$"9249 2200 F24E 1200 1242 1200 1241 2200"
$"1E40 C200 0242 0200 0245 0200 03C8 8200"
$"005F C200 0040 0200 007F FE",
$"FFE0 0000 FFF0 0000 FFF0 0000 FFFC 0000"
$"FFFE 0000 FFFE 0000 FFFF 8000 FFFF C000"
$"FFFF C000 FFFF F000 FFFF F800 FFFF FC00"
$"FFFF FE00 FFFF FE00 FFFF FE00 FFFF FE00"
$"FFFF FE00 FFFF FE00 1FFF FE00 1FFF FE00"
$"1FFF FE00 03FF FE00 03FF FE00 03FF FE00"
$"007F FE00 007F FE00 007F FE" } };
resource 'FREF' (128) { 'APPL', 0, "" };
resource 'FREF' (129) { 'PICS', 1, "" };
resource 'ALRT' (500) {
{40, 31, 170, 481}, 500,
{ Cancel, visible, sound1,
Cancel, visible, sound1,
Cancel, visible, sound1,
Cancel, visible, sound1 } };
resource 'ALRT' (501) {
{40, 31, 170, 481}, 501,
{ OK, visible, sound1,
OK, visible, sound1,
OK, visible, sound1,
OK, visible, sound1 } };
resource 'ALRT' (502) {
{40, 56, 160, 456}, 502,
{ OK, visible, sound1,
OK, visible, sound1,
OK, visible, sound1,
OK, visible, sound1 } };
resource 'ALRT' (503) {
{40, 56, 190, 456}, 503,
{ OK, visible, sound1,
OK, visible, sound1,
OK, visible, sound1,
OK, visible, sound1 } };
resource 'DITL' (500) {
{ {10, 125, 30, 325}, StaticText { disabled,
"PICS Player 1.0 - Steve Sheets" },
{100, 80, 120, 180}, Button { enabled, "Load PICS" },
{100, 260, 120, 360}, Button { enabled, "Quit" },
{40, 10, 90, 440}, StaticText { disabled,
"This is an example program that demonstrates how to animate "
"PICS files. This program was written for MacTutor magazine." } } };
resource 'DITL' (501) {
{ {100, 10, 120, 110}, Button { enabled, "Play Once" },
{100, 230, 120, 330}, Button { enabled, "Read PICS" },
{100, 340, 120, 440}, Button { enabled, "Quit" },
{100, 120, 119, 220}, Button { enabled, "Play Loop" },
{35, 10, 90, 440}, StaticText { disabled,
"Name: ^0\n"
"Number of Frames ^1\n"
"Select the amount of animation, load PICS or exit the program." },
{10, 125, 30, 325}, StaticText { disabled,
"PICS Player 1.0 - Steve Sheets" } } };
resource 'DITL' (502) {
{ {80, 170, 100, 230}, Button { enabled, "OK" },
{20, 20, 60, 380}, StaticText { disabled,
"There was a problem while reading the file \"^0\". ^1." }
} };
resource 'DITL' (503) {
{ {110, 170, 130, 230}, Button { enabled, "OK"},
{20, 20, 86, 380}, StaticText { disabled,
"You are running on a Black & White Macintosh, and the PICS file "
"you selected contains color information. There may be a problem "
"when drawing using Quickdraw. Proceed with caution." } }
};