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