Professional GEM - Part VI - Raster operations
Professional GEM 39
P�PA�AR�RT�T -�- V�VI�I
R�Ra�as�st�te�er�r o�op�pe�er�ra�at�ti�io�on�ns�s
S�SE�EA�AS�SO�ON�NS�S G�GR�RE�EE�ET�TI�IN�NG�GS�S
This is the Yuletide installment of ST PRO GEM, devoted to
explaining the raster, or "bit-blit" portion of the Atari ST's
VDI functions.
Please note that this is NOT an attempt to show how to
write directly to the video memory, although you will be able to
deduce a great deal from the discussion.
As usual, there is a download with this column. You will
find it in ATARI16 (PCS-58) in DL3 under the name of GEMCL6.C.
D�DE�EF�FI�IN�NI�IN�NG�G T�TE�ER�RM�MS�S
To understand VDI raster operations, you need to
understand the jargon used to describe them. (Many programmers
will be tempted to skip this section and go directly to the
code. Please don't do it this time: Learning the jargon is the
larger half of understanding the raster operations!)
In VDI terms a raster area is simply a chunk of contiguous
words of memory, defining a bit image. This chunk is called a
"form". A form may reside in the ST's video map area or it may
be in the data area of your application. Forms are roughly
analogous to "blits" or "sprites" on other systems. (Note,
however, that there is no sprite hardware on the ST.)
Unlike other systems, there is NO predefined organization
of the raster form. Instead, you determine the internal layout
of the form with an auxiliary data structure called the MFDB, or
Memory Form Definition Block. Before going into the details of
the MFDB, we need to look at the various format options. Their
distinguishing features are monochrome vs. color, standard vs.
device-specific and even-word vs. fringed.
M�MO�ON�NO�OC�CH�HR�RO�OM�ME�E V�VS�S.�. C�CO�OL�LO�OR�R
Although these terms are standard, it might be better to
say "single-color vs. multi-color". What we are actually
defining is the number of bits which correspond to each dot, or
pixel, on the screen. In the ST, there are three possible
answers. The high-resolution mode has one bit per pixel, because
there is only one "color": white.
Professional GEM Part VI 40
In the medium resolution color mode, there are four
possible colors for each pixel. Therefore, it takes two bits to
represent each dot on the screen. (The actual colors which
appear are determined by the settings of the ST's pallette
registers.)
In the low resolution color mode, sixteen colors are
generated requiring four bits per pixel. Notice that as the
number of bits per pixel has been doubled for each mode, so the
number of pixels on the screen has been halved: 640 by 400 for
monochrome, 640 by 200 for medium-res, and 320 by 200 by
low-res. In this way the ST always uses the same amount of
video RAM: 32K.
Now we have determined how many bits are needed for each
pixel, but not how they are laid out within the form. To find
this out, we have to see whether the form is device-dependent
or not.
S�ST�TA�AN�ND�DA�AR�RD�D V�VS�S.�. D�DE�EV�VI�IC�CE�E-�-S�SP�PE�EC�CI�IF�FI�IC�C F�FO�OR�RM�MA�AT�T
The standard raster form format is a constant layout which
is the same for all GEM systems. A device-specific form is one
which is stored in the internal format of a particular GEM
system. Just as the ST has three different screen modes, so it
has three different device-specific form formats. We will look
at standard form first, then the ST-specific forms.
First, it's reasonable to ask why a standard format is
used. Its main function is to establish a portability method
between various GEM systems. For instance, an icon created in
standard format on an IBM PC GEM setup can be moved to the ST,
or a GEM Paint picture from an AT&T 6300 could be loaded into
the ST version of Paint.
The standard format has some uses even if you only work
with the ST, because it gives a method of moving your
application's icons and images amongst the three different
screen modes. To be sure, there are limits to this. Since
there are different numbers of pixels in the different modes,
an icon built in the high-resolution mode will appear twice as
large in low-res mode, and would appear oblong in medium-res.
(You can see this effect in the ST Desktop's icons.) Also,
colors defined in the lower resolutions will be useless in
monochrome.
The standard monochrome format uses a one-bit to represent
black, and uses a zero for white. It is assumed that the form
begins at the upper left of the raster area, and is written a
word at a time left to right on each row, with the rows being
Professional GEM Part VI 41
output top to bottom. Within each word, the most significant
bit is the left-most on the screen.
The standard color form uses a storage method called "color
planes". The high-order bits for all of the pixels are stored
just as for monochrome, followed by the next-lowest bit in
another contiguous block, and so on until all of the necessary
color bits have been stored.
For example, on a 16-color system, there would be four
different planes. The color of the upper-leftmost bit in the
form would be determined by concatenating the high-order bit in
the first word of each plane of the form.
The system dependent form for the ST's monochrome mode is
very simple: it is identical to the standard form! This occurs
because the ST uses a "reverse-video" setup in monochrome mode,
with the background set to white.
The video organization of the ST's color modes is more
complicated. It uses an "interleaved plane" system to store the
bits which make up a pixel. In the low-resolution mode, every
four words define the values of 16 pixels. The high-order bits
of the four words are merged to form the left-most pixel,
followed by the next lower bit of each word, and so on. This
method is called interleaving because the usually separate color
planes described above have been shuffled together in memory.
The organization of the ST's medium-resolution mode is
similar to low-res, except the only two words are taken at a
time. These are merged to create the two bits needed to address
four colors.
You should note that the actual color produced by a
particular pixel value is NOT fixed. The ST uses a color
remapping system called a palette. The pixel value in memory is
used to address a hardware register in the palette which
contains the actual RGB levels to be sent to the display.
Programs may set the palette registers with BIOS calls, or the
user may alter its settings with the Control Panel desk
accessory. Generally, palette zero (background) is left as
white, and the highest numbered palette is black.
E�EV�VE�EN�N-�-W�WO�OR�RD�D V�VS�S.�. F�FR�RI�IN�NG�GE�ES�S
A form always begins on a word boundary, and is always
stored with an integral number of words per row. However, it
is possible to use only a portion of the final word. This
partial word is called a "fringe". If, for instance, you had a
form 40 pixels wide, it would be stored with four words per
row: three whole words, and one word with the eight pixel fringe
Professional GEM Part VI 42
in its upper byte.
M�MF�FD�DB�B'�'s�s
Now we can intelligently define the elements of the MFDB.
Its exact C structure definition will be found in the download.
The fdnplanes entry determines the color scheme: a value of one
is monochrome, more than one denotes a color form. If fdstand
is zero, then the form is device-specific, otherwise it is in
standard format.
The fdw and fdh fields contain the pixel width and height
of the form respectively. Fdwdwidth is the width of a row in
words. If fdw is not exactly equal to sixteen times fdwdwidth,
then the form has a fringe.
Finally, fdaddr is the 32-bit memory address of the form
itself. Zero is a special value for fdaddr. It denotes that
this MFDB is for the video memory itself. In this case, the VDI
substitutes the actual address of the screen, and it ignores ALL
of the other parameters. They are replaced with the size of the
whole screen and number of planes in the current mode, and the
form is (of course) in device-specific format.
This implies that any MFDB which points at the screen can
only address the entire screen. This is not a problem, however,
since the the VDI raster calls allow you to select a rectangular
region within the form. (A note to advanced programmers: If
this situation is annoying, you can retrieve the address of the
ST's video area from low memory, add an appropriate offset, and
substitute it into the MFDB yourself to address a portion of the
screen.)
L�LE�ET�T'�'S�S O�OP�PE�ER�RA�AT�TE�E
Now we can look at the VDI raster operations themselves.
There are actually three: transform form, copy raster opaque,
and copy raster transparent. Both copy raster functions can
perform a variety of logic operatoins during the copy.
T�TR�RA�AN�NS�SF�FO�OR�RM�M F�FO�OR�RM�M
The purpose of this operation is to change the format of a
form: from standard to device-specific, or vice-versa. The
calling sequence is:
vrtrnfm(vdihandle, source, dest);
where source and dest are each pointers to MFDBs. They ARE
Professional GEM Part VI 43
allowed to be the same. Transform form checks the fdstand flag
in the source MFDB, toggles it and writes it into the
destination MFDB after rewriting the form itself. Note that
transform form CANNOT change the number of color planes in a
form: fdnplanes must be identical in the two MFDBs.
If you are writing an application to run on the ST only,
you will probably be able to avoid transform form entirely.
Images and icons are stored within resources as standard forms,
but since they are monochrome, they will work "as is" with the
ST.
If you may want to move your program or picture files to
another GEM system, then you will need transform form. Screen
images can be transformed to standard format and stored to
disk. Another system with the same number of color planes could
the read the files, and transform the image to ITS internal
format with transform form.
A GEM application which will be moved to other systems
needs to contain code to transform the images and icons within
its resource, since standard and device-specific formats will
not always coincide.
If you are in this situation, you will find several
utilities in the download which you can use to transform GICON
and GIMAGE objects. There is also a routine which may be used
with maptree() from the last column in order to transform all
of the images and icons in a resource tree at once.
C�CO�OP�PY�Y R�RA�AS�ST�TE�ER�R O�OP�PA�AQ�QU�UE�E
This operation copies all or part of the source form into
the destination form. Both the source and destination forms
must be in device-specific form. Copy raster opaque is for
moving information between "like" forms, that is, it can copy
from monochrome to monochrome, or between color forms with the
same number of planes. The calling format is:
vrocpyfm(vdihandle, mode, pxy, source, dest);
As above, the source and dest parameters are pointers to MFDBs
(which in turn point to the actual forms). The two MFDBs may
point to memory areas which overlap. In this case, the VDI
will perform the move in a non-destructive order. Mode
determines how the pixel values in the source and destination
areas will be combined. I will discuss it separately later on.
The pxy parameter is a pointer to an eight-word integer
array. This array defines the area within each form which will
be affected. Pxy[0] and pxy[1] contain, respectively, the X and
Professional GEM Part VI 44
Y coordinates of the upper left corner of the source rectangle.
These are given as positive pixel displacements from the upper
left of the form. Pxy[2] and pxy[3] contain the X and Y
displacements for the lower right of the source rectangle.
Pxy[4] through pxy[7] contain the destination rectangle in
the same format. Normally, the destination and source should be
the same size. If not, the size given for the source rules, and
the whole are is transferred beginning at the upper left given
for the destination.
This all sounds complex, but is quite simple in many
cases. Consider an example where you want to move a 32 by 32
pixel area from one part of the display to another. You would
need to allocate only one MFDB, with a zero in the fdaddr
field. The VDI will take care of counting color planes and so
on. The upper left raster coordinates of the source and
destination rectangles go into pxy[0], pxy[1] and pxy[4], pxy[5]
respectively. You add 32 to each of these values and insert the
results in the corresponding lower right entries, then make the
copy call using the same MFDB for both source and destination.
The VDI takes care of any overlaps.
C�CO�OP�PY�Y R�RA�AS�ST�TE�ER�R T�TR�RA�AN�NS�SP�PA�AR�RE�EN�NT�T
This operation is used for copying from a monochrome form
to a color form. It is called transparent because it "writes
through" to all of the color planes. Again, the forms need to
be in device-specific form. The calling format is:
vrtcpyfm(vdihandle, mode, pxy, source, dest, color);
All of the parameters are the same as copy opaque, except that
color has been added. Color is a pointer to a two word integer
array. Color[0] contains the color index which will be used when
a one appears in the source form, and color[1] contains the
index for use when a zero occurs.
Incidentally, copy transparent is used by the AES to draw
GICONs and GIMAGEs onto the screen. This explains why you do
not need to convert them to color forms yourself.
A note for advanced VDI programmers: The pxy parameter in
both copy opaque and transparent may be given in normalized
device coordinates (NDC) if the workstation associated with
vdihandle was opened for NDC work.
T�TH�HE�E M�MO�OD�DE�E P�PA�AR�RA�AM�ME�ET�TE�ER�R
The mode variable used in both of the copy functions is an
Professional GEM Part VI 45
integer with a value between zero and fifteen. It is used to
select how the copy function will merge the pixel values of the
source and destination forms. The complete table of functions
is given in the download. Since a number of these are of
obscure or questionable usefulness, I will only discuss the most
commonly used modes.
R�RE�EP�PL�LA�AC�CE�E M�MO�OD�DE�E
A mode of 3 results in a straight-forward copy: every
destination pixel is replaced with the corresponding source form
value.
E�ER�RA�AS�SE�E M�MO�OD�DE�E
A mode value of 4 will erase every destination pixel which
corresponds to a one in the source form. (This mode corresponds
to the "eraser" in a Paint program.) A mode value of 1 will
erase every destination pixel which DOES NOT correspond to a one
in the source.
X�XO�OR�R M�MO�OD�DE�E
A mode value of 6 will cause the destination pixel to be
toggled if the corresponding source bit is a one. This operation
is invertable, that is, executing it again will reverse the
effects. For this reason it is often used for "software
sprites" which must be shown and then removed from the screens.
There are some problems with this in color operations, though -
see below.
T�TR�RA�AN�NS�SP�PA�AR�RE�EN�NT�T M�MO�OD�DE�E
Don't confuse this term with the copy transparent function
itself. In this case it simply means that ONLY those
destination pixels corresponding with ones in the source form
will be modified by the operation. If a copy transparent is
being performed, the value of color[0] is substituted for each
one bit in the source form. A mode value of 7 selects
transparent mode.
R�RE�EV�VE�ER�RS�SE�E T�TR�RA�AN�NS�SP�PA�AR�RE�EN�NT�T M�MO�OD�DE�E
This is like transparent mode except that only those
destination pixels corresponding to source ZEROS are modified.
In a copy transparent, the value of color[1] is substituted for
each zero bit. Mode 13 selects reverse transparent.
Professional GEM Part VI 46
T�TH�HE�E P�PR�RO�OB�BL�LE�EM�M O�OF�F C�CO�OL�LO�OR�R
I have discussed the various modes as if they deal with one
and zero pixel values only. This is exactly true when both
forms are monochrome, but is more complex when one or both are
color forms.
When both forms are color, indicating that a copy opaque is
being performed, then the color planes are combined bit-by-bit
using the rule for that mode. That is, for each corresponding
source and destination pixel, the VDI extracts the top order
bits and processes them, then operates on the next lower bit,
and so on, stuffing each bit back into the destination form as
the copy progresses. For example, an XOR operation on pixels
valued 7 and 10 would result in a pixel value of 13.
In the case of a copy transparent, the situation is more
complex. The source form consists of one plane, and the
destination form has two or more. In order to match these up,
the color[] array is used. Whenever a one pixel is found, the
value of color[0] is extracted and used in the bit-by-bit merge
process described in the last paragraph. When a zero is found,
the value of color[1] is merged into the destination form.
As you can probably see, a raster copy using a mode which
combines the source and destination can be quite complex when
color planes are used! The situation is compounded on the ST,
since the actual color values may be remapped by the palette at
any time. In many cases, just using black and white in color[]
may achieve the effects you desire. If need to use full color,
experimentation is the best guide to what looks good on the
screen and what is garish or illegible.
O�OP�PT�TI�IM�MI�IZ�ZI�IN�NG�G R�RA�AS�ST�TE�ER�R O�OP�PE�ER�RA�AT�TI�IO�ON�NS�S
Because the VDI raster functions are extremely generalized,
they are also slower than hand-coded screen drivers which you
might write for your own special cases. If you want to speed up
your application's raster operations without writing assembl
language drivers, the following hints will help you increase the
VDI's performance.
A�AV�VO�OI�ID�D M�ME�ER�RG�GE�ED�D C�CO�OP�PI�IE�ES�S
These are copy modes, such as XOR, which require that
words be read from the destination form. This extra memory
access increases the running time by up to fifty percent.
Professional GEM Part VI 47
M�MO�OV�VE�E T�TO�O C�CO�OR�RR�RE�ES�SP�PO�ON�ND�DI�IN�NG�G P�PI�IX�XE�EL�LS�S
The bit position within a word of the destination rectangle
should correspond with the bit position of the source
rectangle's left edge. For instance, if the source's left edge
is one pixel in, then the destination's edge could be at one,
seventeen, thirty-three, and so. Copies which do not obey this
rule force the VDI to shift each word of the form as it is
moved.
A�AV�VO�OI�ID�D F�FR�RI�IN�NG�GE�ES�S
Put the left edge of the source and destination rectangles
on an even word boundary, and make their widths even multiples
of sixteen. The VDI then does not have to load and modify
partial words within the destination forms.
U�US�SE�E A�AN�NO�OT�TH�HE�ER�R M�ME�ET�TH�HO�OD�D
Sometimes a raster operation is not the fastest way to
accomplish your task. For instance, filling a rectangle with
zeros or ones may be accomplished by using raster copy modes
zero and fifteen, but it is faster to use the VDI vbar function
instead. Likewise, inverting an area on the screen may be done
more quickly with vbar by using BLACK in XOR mode.
Unfortunately, vbar cannot affect memory which is not in the
video map, so these alternatives do not always work.
F�FE�EE�ED�DB�BA�AC�CK�K R�RE�ES�SU�UL�LT�TS�S
The results of the poll on keeping or dropping the use of
portability macros are in. By a slim margin, you have voted to
keep them. The vote was close enough that in future columns I
will try to include ST-only versions of routines which make
heavy use of the macros. C purists and dedicated Atarians may
then use the alternate code.
T�TH�HE�E N�NE�EX�XT�T Q�QU�UE�ES�ST�TI�IO�ON�N
This time I'd like to ask you to drop by the Feedback
Section and tell me whether the technical level of the columns
has been:
A) Too hard! Who do you think we are, anyway?
B) Too easy! Don't underestimate Atarians.
C) About right, on the average.
Professional GEM Part VI 48
If you have the time, it would also help to know a little
about your background, for instance, whether you are a
professional programmer, how long you have been computing, if
you owned an 8-bit Atari, and so on.
C�CO�OM�MI�IN�NG�G U�UP�P S�SO�OO�ON�N
The next column will deal with GEM menus: How they are
constructed, how to decipher menu messages, and how to change
menu entries at run-time. The following issue will contain more
feedback response, and a discussion on designing user interfaces
for GEM programs.
Back to Professional_GEM