Bitmap for SuperPaint
Volume Number: 6
Issue Number: 2
Column Tag: Programmer's Workshop
BitMapper Utility For SuperPaint 
By Michael Ogawa, Oceanside, CA
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
[Michael Ogawa is a Software Designer for Palomar Software where he has been
involved in several projects including the Print Preview and PrintQ Monitor features
of Palomar’s printer and plotter drivers. He has done design and development on Apple
][ computers since 1978, and has worked on business productivity tools, such as
database and word processing applications, for the Macintosh since 1985.]
This article covers two interesting and relatively new topics: SuperPaint
plug-ins, and a new data structure/resource format for bit images. The ‘BTMP’
resource type is a handy way of encapsulating a bit image and its dimension specifying
bit map data into one package. It is easy to retrieve from disk, and to draw with or
manipulate. SuperPaint is a wonderful application for creating bit image graphics.
And using a plug-in tool that we’ll create in this article, it’s a snap grabbing an image
from a SuperPaint document and creating a ‘BTMP’ resource.
Writing this article should be a snap because I’ll be able to leverage off of two
other articles in this issue of MacTutor--meaning that I won’t have to write as much!
This article is a how-to on writing a transformation menu command. For an overview
of SuperPaint plug-ins, and for specifics on interactive palette tools, see Linda
McLennan’s article. Mike Scanlin’s article covers the ‘BTMP’ resource type. It
includes routines to retrieve these resources from disk and to draw them. He also
shows you how to write a custom ResEdit editor to create and edit these resources
directly within ResEdit.
What’s a Butmump?
The familiar ‘ICON’ and ‘SICN’ resources are nothing more than bit image data in
pre-defined dimension formats. An ‘ICON’ is a 32-bit by 32-bit bit image which is
easily retrieved from disk using the GetICON() Toolbox routine, and drawn using
PlotICON(). A ‘SICN’ is a array of 16-bit by 16-bit image. The Macintosh Toolbox
doesn’t have any routines specific to this resource type, but most Macintosh
developers have their own library routines in their bag of tricks for dealing with
them.
So great, we’ve got 32 by 32, and 16 by 16 covered. What if we need to draw a
bit image that’s 36-bits wide and 24-bits tall? The common answer is to create a
standard ‘PICT’ resource and use GetPicture() and DrawPicture(). One drawback to
this is the lack of flexibility in drawing modes. Many developers have implemented
their small icon drawing routines with a copy mode parameter allowing them to
opaquely (blast-all-them-bits) or transparently (overlay) draw a small icon, or to
punch holes using a masking small icon. DrawPicture() has no such flexibility.
Another advantage with bit images has to do with the recent availability of
routines to create regions directly from bit map images. Now available from Apple
Computer as part of 32-Bit Color QuickDraw, or available separately in MPW object
form through Apple Software Licensing, is a routine called BitMapRgn(). Ted Cohn’s
article “Covert PICTs to Regions”, MacTutor, June 1989, provides sources to a
routine called MakeRgn(). Both of these routines take a bit map and create a region
from it. Very handy when you want to drag around a gray region based on some bit
image graphic.
What we have to deal with are bit images of non-standard dimensions, and bit
map records explaining just what we have in the way of our bit images. The bounds
field of the bit map record readily tells us the exact bitwise dimensions of the bit
image. The rowBytes field tells us the row width of the bit image, which must be an
even number of bytes. (Therefore, the bit image data may have unused bits off to the
right of each row of the actual image.)
The bit map record is a fixed size data structure, and contains an even number of
bytes. We can conviently tack on the actual bytes of the bit image to the bit map
record, creating the variable size ‘BTMP’ data structure and resource type:
/* 1 */
typedef struct BTMP {
BitMap map;
short image[];
} BTMP, *BTMPPeek, **BTMPPkHndl;
typedef BitMap *BTMPPtr, **BTMPHndl;
The only field that is a little “fuzzy” is the baseAddr field of the bit map record.
On disk this field has no meaning and is merely a place holder. Once in memory and
locked down, this field is set to contain the actual beginning address of the following bit
image.
Mike Scanlin’s article contains routines to get and draw these puppies. And
because the first field is an actual BitMap record, no type coercion is necessary when
passing a ‘BTMP’ to a routine expecting a BitMap.
Writing SuperPaint Externals
Silicon Beach Software has come up with a neat method of making their products
extendable. Both SuperPaint 2.0 and Digital Darkroom employ this technology which
allows developers to add features to these products by writing some code and wrapping
it in a file with a specified file type and a standard version identifying resource. The
file is then placed in the same folder as the preferences file and voilá, the application
suddenly has a new feature!
SuperPaint supports two types of plug-in modules, the term they use for their
“externals”. One type adds custom painting tools to their painting tools palette. This
type of tool is referred to as an interactive painting tool. The other type adds a
command to the Paint menu and operates on the selected area in the current document.
This type of tool is referred to as a menu command or transformation command tool.
When the user puts a menu command plug-in in the folder that contains their
preferences file, the command appears at the bottom of the Paint menu.
Figure 1. Plug-in menu commands appears at the bottom of the Paint menu in
SuperPaint. The resource name of the plug-in menu’s code resource appears as the
command name in the menu.
To keep things simple this article only deals with SuperPaint menu command
tools. For an overview on plug-in modules and details on other types of tools see Linda
McLennan’s article.
The Bare Essentials
You can create a plug-in tool in any development environment that allows you to
create a stand-alone code resource (e.g. a definition proc such as a WDEF, CDEF, or
LDEF, or a HyperCard or 4th Dimension external). A menu command tool is a file
whose file type is ‘BWtc’. That stands for “Black and White transformation
command”. It’s creator type is up to you. If you use ‘SPNT’, SuperPaint’s creator
type, it will show up on the Finder desktop with a standard plug-in icon provided by
SuperPaint. You can give it your own creator type, and provide the other necessary
resources (creator, ‘BNDL’, ‘FREF’, and ‘ICN#’) to give it your own unique desktop
icon.
The plug-in must contain a plug-in module version information resource, and
the code resource. The plug-in module version information resource is used for
compatibility checking. It is a resource of type ‘PiMI’. Currently it is two bytes long
and must contain the current version value of $0001 (or just plain ol’ decimal one).
The code resource must be of type ‘BWtc’, the same as the file type. The resource
name of the ‘BWtc’ code resource will show up at the bottom of SuperPaint’s Paint
menu, and in SuperPaint’s plug-in info list in the About Box.
The file may contain any other resources the tool requires, and all resources
should be marked purgeable. When SuperPaint executes the plug-in code resource the
plug-in file is set as the current resource file. The plug-in should do one-deep
resource calls (e.g Get1Resource()) unless it is trying to get a resource from the
System file.
I’ve Got Your Number
What resource IDs should your resources have? Practically any that you want,