Paint Files
Volume Number: | | 3
|
Issue Number: | | 5
|
Column Tag: | | Pascal Procedures
|
Reading Paint Files
By Gary Palmer, University of Nevada
Paint files have become generic on the Macintosh as a way of transferring bit mapped type graphics information between applications. Several commercial programs have come out that can read and write MacPaint file formats, making support of this type of Macintosh object an important design consideration. FullPaint by Ann Arbor Softworks is one of the most popular MacPaint alternatives because it is the most faithful to the original design in simplicity and function, yet improves on the obvious limitations of MacPaint without introducing any new wrinkles or problems to get in the way. Thunderscan by Thunderware & Andy Hertzfeld opens, reads and writes paint files with the added feature that you can use Andy's wonderful "moving window" scroller to select any part or all of a paint drawing for alteration. As such, it is a useful paint editor. Paint Cutter by Silicon Beach Software has some important features including the ability to make large selections and rotate large selections of a paint diagram. This is especially useful in combination with Thunderscan drawings that must be rotated. SuperPaint also by Silicon Beach Software offers a "MacDraw-MacPaint" combo that can be very powerful in addition to reading and writing paint files. As a result of all this developer support for paint documents, the ability to read and display a paint type document could be an important design element in your application.
As figure 1 shows, our program this month illustrates how to open and read a MacPaint type document, displaying it in a window at 3/8's of it's normal size. Add this to a paint type program and you can expand to editing and any number of other quickdraw functions.
MacPaint documents are described in technical note number 86 released last August, and according to the note header, the note was written by Bill Atkinson in 1983! Figure 2 summarizes the format of the MacPaint document.
The beginning of a MacPaint file is a 512 byte header block, which contains the version number, pattern array, and empty space. The header matches the following record example:
MPHeader = RECORD
version: LongInt;
PatArray: Array [1..39] of Pattern;
Future: PACKED ARRAY [1..204] OF SignedByte;
END;
Typically, the version number is zero, in which case the patterns are ignored and MacPaint uses the default patterns instead. Applications can ignore the header by skipping it when reading a document or by writing out 512 bytes of zero when writing a paint document. (Recall that a Pattern is 8 bytes so the PatArray is 38*8 = 304 bytes.)
Paint documents are a screen dump at 72 dots per inch, of the bit map, which represents a 576 pixel wide (72 bytes times 8 bits per byte) by 720 pixel tall array, thus covering an 8 by 10 inch document. Each line of 72 bytes, representing 576 pixels is shoved through the trap PackBits to output a single pixel line, until all 720 lines have been packed. Therefore, the maximum size of an unpacked bit map is 720 lines by 72 bytes per line or 51,840 bytes. With the PackBits routine, this compresses down to about 10,000 bytes normally.
Fig. 1 Our Paint Reader Program
Program Details
To read the file, we call the standard file routine to get a file name and reference number, then call FSOpen to open the file. We can skip the 512 byte header by positioning the file marker past the first 512 bytes with SetFPos. We determine the size of the file by calling GetEOF, and then subtracting the 512 header bytes to determine the number of bytes making up the bit map, which is what we want to read and display. We then use FSRead to read in the bit map into the buffer and close the file. (See figure 3 above for flowchart.)
To prepare the bit map for display, we have to unpack it. This can be done by calling UnPackBits in a loop, unpacking 72 bytes at a time until all the lines of the document (720) are done. The nice thing about MacPaint is that it doesn't try to do anything fancy with variable size files. All files have the same 720 lines to unpack. Sometimes simplicity is a great virtue! In our program, we just divide the bit map in two and call UnPackBits twice.
Fig. 2 Format of Paint File Data Fork
Once the bit map is unpacked, we can copy the bit map to an off-screen bit map we have allocated, and then to our window to display the document in a destination rectangle. By making the destination rectangle 3/8's the size of the document, we can nicely display the entire drawing at a reduced size. In our program, we have scaled everything to ScreenBits.bounds, so on a larger display, a bigger proportional picture would also be displayed. This is a good habit to get into in preparation for Macintosh II.
Our main program is fairly simple. We perform the standard init stuff and open a window. Then we begin our display loop where we continue to call standard file until the user clicks cancel. This is done by calling our procedure GetPaintImage, which in turn calls standard file, and then attempts to open the file and unpack the bit map, followed by DisplayPaintFile, which copies the off-screen bit map to our window. A simple event loop is used to allow a cmd-shift-3 to capture the window contents and save it to disk to help write this article! The real work is in our paint file manager unit, where the actual reading and displaying of the file takes place.
Standard File Dialog
Figure 4 shows our standard file dialog from which we get the name of the file. We call it with an allowed file type of PNTG so that we get all MacPaint type files. The standard file dialog fills in a Reply record from which we can extract the file name and reference number for the FSOpen call. After opening the file we call our ReadPaintFile routine to read in the packed bit map and return to us a pointer to the bit map. Using the pointer, we call UnpackBits twice to unpack and copy the bit map to our off-screen bit map from which we will copy the image to the window, as shown in figure 3.
Fig. 3 Program Flowchart
Debugging Aid
A useful feature when dealing with the file manager is our doMessage procedure. This little routine takes four string arguments and stuffs them into the low memory globals with ParamText trap. A simple dialog is displayed that reads the four low memory parameters and displays them in the dialog box. This is useful for a quick and dirty output device, both for the user, and for debugging. Since every file manager call returns an error code that must be checked, it can be a real pain while you are writing and testing code, to deal with a formal exception handler procedure. Our little dialog box lets you know what happened and where and by using NumToString, can be an easy way to find out the values of parameters in a hurry. Whenever you need some info, just stick in a doMessage() line in your code. Of course, this violates the resource manager thinking of Apple by putting human readable text in your program rather than in your resource fork! But, when you are done with development, a simple search on doMessage would find all the strings which could then be transferred to a string resource for the final product.
Fig. 4 Calling Standard File
Each time we get a file, our doMessage proc displays a dialog box showing how many bytes there are in the packed bit map. It also shows if the number of bytes is odd. MacPaint files will always return even, so the dialog in figure 5 is shown. But sometimes another program will return an odd number of bytes, in which case, the dialog in figure 6 is displayed. Our program will attempt to read any paint type file, and other error checking traps will catch any problem and return the user to the desktop.
Fig. 5 Paint file has even bytes
Fig. 6 Other files may have odd bytes
Combining this program with the C column this month and adding in Joel West's article on printing a few months back, you have the making of the next FullPaint application!
PROGRAM ReadPaint;
{ Reads paint files and displays them in 3/8 normal size in }
{ center of large window. After reading a file, press }
{ the mouse button to read another file. Choosing cancel }
{ in the dialog box quits the program. }
{ Lightspeed Pascal version, but very generic! }
USES
PaintFileMgr;
VAR
theWindow : WindowPtr;
theWindowRec : WindowRecord;
WindowRect : Rect;
MaskEvents : Integer;
theImagePtr : Ptr;
DoIt : boolean;
Event : eventrecord;
{ procedures start here }
PROCEDURE crash;
BEGIN
ExitToShell;
END;
PROCEDURE StandardInit;
BEGIN
InitGraf(@thePort);
InitFonts;
MaskEvents := EveryEvent - keyUpMask;
FlushEvents(MaskEvents, 0);
InitWindows;
InitMenus;
TEInit;
InitDialogs(@crash);
InitCursor;
PenNormal;
END;{StandardInit}
PROCEDURE OpenWindow;
CONST
mBarHeightGlobal = $BAA;
VAR
screen : rect;
mBarHeight : Integer;
MemoryPtr : ^Integer;
BEGIN
MemoryPtr := pointer(mBarHeightGlobal);
mBarHeight := MemoryPtr^;
screen := screenBits.bounds;
SetRect(WindowRect, screen.left + 4, screen.top + mBarHeight + 20, screen.right
- 4, screen.bottom - 4);
theWindow := NewWindow(@theWindowRec, WindowRect, 'PaintFile', True,
0, Pointer(-1), False, 0);
SetPort(theWindow);
END;
{ main program }
BEGIN
MaxApplZone;
MoreMasters;
MoreMasters;
StandardInit;
OpenWindow;
REPEAT {on theImagePtr}
GetPaintImage(theImagePtr);
DisplayPaintFile(theImagePtr);
IF theImagePtr <> NIL THEN
BEGIN
DisposPtr(theImagePtr);
REPEAT {on button }
systemtask;
DoIt := GetNextEvent(KeyDownMask, Event);
IF DoIt THEN
CASE Event.what OF
KeyDown, Autokey :
BEGIN
sysbeep(5);
END;
OTHERWISE
BEGIN
END;
END;
UNTIL button;
END;
UNTIL theImagePtr = NIL;
END.
{___________________________________________________________}
{PAINTFILEMGR Unit }
{ }
{Procedures for opening and displaying Paint files with }
{high level routines from Toolbox file manager. }
{might not work in a 128K Mac, but could probably be made}
{to work by reading and unpacking the file in smaller }
{chunks. }
{AUTHOR }
{Gary B. Palmer. Public domain. October 25, 1986. }
{Author reserves right to use in own programs. }
{___________________________________________________________}
UNIT PaintFileMgr;
INTERFACE
PROCEDURE GetPaintImage (VAR ImagePtr : Ptr);
PROCEDURE DisplayPaintFile (ImagePtr : Ptr);
IMPLEMENTATION
{--------- Internal routines --------}
PROCEDURE doMessage (mes0 : str255;
mes1 : str255;
mes2 : str255;
mes3 : str255);
CONST
MessageDialog = 258;
VAR
dialogP : DialogPtr;
item : integer;
dlogRect : rect;
BEGIN
ParamText(mes0, mes1, mes2, mes3);
SetRect(dlogRect, 100, 100, 400, 200);
dialogP := GetNewDialog(MessageDialog, NIL, pointer(-1));
IF dialogP = NIL THEN
BEGIN
SysBeep(5);
ExitToShell;
END;
initCursor;
ModalDialog(NIL, item);
DisposDialog(dialogP);
END;
PROCEDURE SFGetPaint (VAR theReply : SFReply);
CONST
SFPutLeft = 100;
SFPutTop = 100;
VAR
SFPutPt : Point;
PNTG_list : SFTypeList;
BEGIN
PNTG_list[0] := 'PNTG';
SetPt(SFPutPt, SFPutLeft, SFPutTop);
SFGetFile(SFPutPt, '', NIL, 1, PNTG_list, NIL, theReply);
END;{SFGetPaint}
PROCEDURE CloseOldFile (refNum : Integer;
vRefNum : Integer);
VAR
err : OSErr;
BEGIN
err := FSClose(refNum);
IF err <> noErr THEN
BEGIN
doMessage('FSClose error', 'CloseOldFile routine',
'Could not close file ', '');
END;
err := FlushVol(NIL, vRefNum);
IF err <> noErr THEN
BEGIN
doMessage('FlushVol error', 'CloseOldFile routine',
'Could not Flush volume ', '');
END;
END;{CloseOldFile}
PROCEDURE ReadPaintFile (refNum : Integer;
VAR PackedBitsPtr : Ptr);
LABEL
1;
VAR
bytes : LongInt;
str1 : str255;
err : OSErr;
BEGIN
PackedBitsPtr := NIL;
err := GetEOF(refNum, bytes); {FIND LOGICAL END OF FILE}
IF err <> noErr THEN
BEGIN
doMessage('GetEOF error', 'ReadPaintFile routine',
'Could not find file end', '');
END;
bytes := bytes - 512; {HEADER BLOCK NOT NEEDED}
IF odd(bytes) THEN
BEGIN
NumToString(bytes, str1);
str1 := concat('Bytes - header = ', str1);
doMessage('Logical EOF Odd', str1, 'Not a MacPaint
File.', '');
{goto 1; try anyway!}
END
ELSE
BEGIN
NumToString(bytes, str1);
str1 := concat('Bytes - header =', str1);
doMessage('Reading Paint type...', str1, '', '');
END;
PackedBitsPtr := NewPtr(bytes); {MAKE A HOME FOR DATA}
IF MemError <> noErr THEN
BEGIN
PackedBitsPtr := NIL;
doMessage('PackBitsPtr Memory err', 'ReadPaintFile
routine', 'No room to read in data', '');
GOTO 1;
END;
err := SetFPos(refNum, FSFromStart, 512); { BEGIN OF DATA}
IF err <> noErr THEN
BEGIN
doMessage('SetFPos error', 'ReadPaintFile routine',
'Could not set file ', 'at start of data');
END;
err := FSRead(refNum, bytes, PackedBitsPtr); {READ IT}
IF err <> noErr THEN
BEGIN
doMessage('FSRead error', 'ReadPaintFile routine',
'Problem reading in file', '');
GOTO 1;
END;
1 :
END;{ReadPaintFile}
PROCEDURE GetPaintImage;{ (var ImagePtr : Ptr)}
LABEL
2;
CONST
SizeOfPaintImage = 51840;
VAR
refNum : Integer;
theReply : SFReply;
err : OSErr;
packedBitsPtr : Ptr;
destPtr, SrcPtr : Ptr;
saveStart : longInt;
bytesUnPacked : Integer;
BEGIN
ImagePtr := NIL;
SFGetPaint(theReply);
WITH theReply DO
IF NOT good THEN
GOTO 2
ELSE
BEGIN
err := FSOpen(fName, vRefNum, refNum);
IF err <> 0 THEN
BEGIN
doMessage('FSOpen error on file', 'GetPaintImage routine', 'Can not
Open File ', '');
GOTO 2;
END;
ReadPaintFile(refNum, packedBitsPtr);
{ RETURNS A POINTER TO THE PACKED DATA }
CloseOldFile(refNum, vRefNum); { CLOSE FILE IMMEDIATELY }
IF packedBitsPtr = NIL THEN
BEGIN
GOTO 2;
END;
ImagePtr := NewPtr(SizeOfPaintImage); {THE IMAGE}
IF MemError <> 0 THEN
BEGIN
doMessage('ImagePtr Memory err', 'GetPaintImage
routine', 'No room for image', '');
GOTO 2;
END;
{POINTERS TO BE USED BY UNPACKBITS INCREMENTED, SO SAVE}
{OLD POINTERS BY CREATING SCAPEGOATS: SRCPTR AND DESTPTR}
SrcPtr := packedBitsPtr; {SRCPTR WILL BE INCREMENTED}
DestPtr := ImagePtr;{DESTPTR WILL BE INCREMENTED}
{A PAINT IMAGE HAS MORE BYTES THAN CAN BE REPRESENTED BY AN}
{INTEGER, AND UNPACKBITS ACCEPTS ONLY INTEGERS, SO UNPACK}
{ONLY HALF THE BYTES AT A TIME.}
saveStart := ord(DestPtr);
UnpackBits(SrcPtr,DestPtr,SizeOfPaintImage DIV 2);
bytesUnPacked := ord(DestPtr) - saveStart;
{THE FINAL UNPACKING STARTS FROM THE NEW VALUES OF SRCPTR.}
UnpackBits(SrcPtr, DestPtr, SizeOfPaintImage - bytesUnPacked);
DisposPtr(packedBitsPtr);
END;
2 :
END;{GetPaintImage}
PROCEDURE DisplayPaintFile; {(ImagePtr : Ptr);}
LABEL
3;
VAR
pageBits : BitMap;
drawRect : Rect;
screen : Rect;
BEGIN
IF ImagePtr = NIL THEN
BEGIN
GOTO 3;
END;
{SET UP AN APPROPRIATE BITMAP TO SEND TO COPYBITS}
WITH pageBits DO
BEGIN
baseAddr := ImagePtr; {GIVE THE BUFFER TO THE BITMAP}
rowBytes := 72; {ROWBYTES OF PAINT IMAGE}
SetRect(bounds, 0, 0, 576, 720); {ENCLOSES PAINT IMAGE}
END;
{ASSUMES THE MAIN PROGRAM HAS OPENED A WINDOW APPROX}
{THE SAME SIZE AS THE SCREEN AND SET THE PORT}
screen := screenBits.bounds;
setRect(drawRect, screen.left + 148, screen.top + 0, screen.right
- 148, screen.bottom - 72);
{3/8 image bounds size}
copyBits(pageBits, thePort^.portbits, pagebits.bounds, drawRect,
srcCopy, NIL);
3 :
END;{DisplayPaintFile}
END. {of unit}
*PaintReader.R
*
PaintReader.RSRC
APPLPAIN
Type PAIN = STR
,0
© by MacTutor 1 MAY 1987
Type FREF
,128
APPL 0
,129
PICT 1
Type BNDL
,128
PAIN 0
ICN#
0 128 1 129
FREF
0 128 1 129
* ------- Dialogs --------
* Program Messages Dialog box...
type DLOG
,258
Program Messages
100 100 200 400
Visible NoGoAway
1
0
258
type DITL
,258
3
BtnItem Enabled
65 230 95 285
OK
StatText Disabled
15 60 85 222
^0\0D^1\0D^2\0D^3
IconItem Disabled
10 10 42 42
1
* ------- Icon --------
Type ICN# = GNRL
,128
.H
0001 0000 0002 8000 0004 4000 0008 2000
0010 1000 0021 0800 0043 8400 0087 C200
010F E100 0217 C080 042F 8040 085F 0020
10AE 0010 2054 0008 4008 3F04 8010 4082
4000 8041 27EF FF22 1FF0 7F14 3FF1 FF0F
37F1 3F07 7DEF 9F07 4780 8007 0080 6007
0040 1FE7 0020 021F 0010 0407 0008 0800
0004 1000 0002 2000 0001 4000 0000 8000
*
0001 0000 0003 8000 0007 C000 000F E000
001F F000 003F F800 007F FC00 00FF FE00
01FF FF00 03FF FF80 07FF FFC0 0FFF FFE0
1FFF FFF0 3FFF FFF8 7FFF FFFC FFFF FFFE
FFFF FFFF FFFF FFFE BFFF FFFC 7FFF FFFF
FFFF FFFF FFFF FFFF 7FFF FFFF 0FFF FFFF
02FF FFFF 017F FFFF 00BF FFFF 005F F830
002F F000 0017 E000 000B C000 0005 8000