6 - Raster operations
*PROFESSIONAL GEM*
by Tim Oren
Column #6 - Raster operations
SEASONS GREETINGS!
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.
DEFINING TERMS
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.
MONOCHROME VS. COLOR
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.
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.
STANDARD VS. DEVICE-SPECIFIC FORMAT
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 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.
EVEN-WORD VS. FRINGES
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 in its upper byte.
MFDBs
Now we can intelligently define the elements of the MFDB. Its exact C structure definition will be found in the download. The fd_nplanes entry determines the color scheme: a value of one is monochrome, more than one denotes a color form. If fd_stand is zero, then the form is device-specific, otherwise it is in standard format.
The fd_w and fd_h fields contain the pixel width and height of the form respectively. Fd_wdwidth is the width of a row in words. If fd_w is not exactly equal to sixteen times fd_wdwidth, then the form has a fringe.
Finally, fd_addr is the 32-bit memory address of the form itself. Zero is a special value for fd_addr. 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.)
LET'S OPERATE
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.
TRANSFORM FORM
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:
vr_trnfm(vdi_handle, source, dest);
where source and dest are each pointers to MFDBs. They ARE allowed to be the same. Transform form checks the fd_stand 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: fd_nplanes 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 G_ICON and G_IMAGE objects. There is also a routine which may be used with map_tree() from the last column in order to transform all of the images and icons in a resource tree at once.
COPY RASTER OPAQUE
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:
vro_cpyfm(vdi_handle, 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 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 fd_addr 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.
COPY RASTER TRANSPARENT
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:
vrt_cpyfm(vdi_handle, 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 G_ICONs and G_IMAGEs 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 vdi_handle was opened for NDC work.)
THE MODE PARAMETER
The mode variable used in both of the copy functions is an 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.
REPLACE MODE
A mode of 3 results in a straight-forward copy: every destination pixel is replaced with the corresponding source form value.
ERASE MODE
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.
XOR MODE
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.
TRANSPARENT MODE
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.
REVERSE TRANSPARENT MODE
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.
THE PROBLEM OF COLOR
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.
OPTIMIZING RASTER OPERATIONS
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.
AVOID MERGED COPIES
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.
MOVE TO CORRESPONDING PIXELS
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.
AVOID FRINGES
Put theleft 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.AVOID FRINGES
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.
USE ANOTHER METHOD
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 v_bar function instead. Likewise, inverting an area on the screen may be done more quickly with v_bar by using BLACK in XOR mode. Unfortunately, v_bar cannot affect memory which is not in the video map, so these alternatives do not always work.
FEEDBACK RESULTS
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.
THE NEXT QUESTION
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.
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.
COMING UP SOON
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.
GEMCL6.C
>>>>>>>>>>>>>>>>>>>>>>>>>>>>> MFDB Structure <<<<<<<<<<<<<<<<<<<<<<<<<<<<<
/* Memory Form Definition Block */
typedef struct fdbstr
{
long fd_addr; /* Form address */
int fd_w; /* Form width in pixels */
int fd_h; /* Form height in pixels */
int fd_wdwidth; /* Form width in memory words */
int fd_stand; /* Standard form flag */
int fd_nplanes; /* Number of color planes */
int fd_r1; /* Dummy locations: */
int fd_r2; /* Reserved for future use */
int fd_r3;
} MFDB;
>>>>>>>>>>>>>>>>>>>>>>> Resource Transform Utilities <<<<<<<<<<<<<<<<<<<<<
/*------------------------------*/
/* vdi_fix */
/*------------------------------*/
VOID
vdi_fix(pfd, theaddr, wb, h) /* This routine loads the MFDB */
MFDB *pfd; /* Input values are the MFDB's */
LONG theaddr; /* address, the form's address,*/
WORD wb, h; /* the form's width in bytes, */
{ /* and the height in pixels */
pfd->fww = wb >> 1;
pfd->fwp = wb << 3;
pfd->fh = h;
pfd->np = 1; /* Monochrome assumed */
pfd->mp = theaddr;
}
/*------------------------------*/
/* vdi_trans */
/*------------------------------*/
WORD
vdi_trans(saddr, swb, daddr, dwb, h) /* Transform the standard form */
LONG saddr; /* pointed at by saddr and */
UWORD swb; /* store in the form at daddr */
LONG daddr; /* Byte widths and pixel height*/
UWORD dwb; /* are given */
UWORD h;
{
MFDB src, dst; /* These are on-the-fly MFDBs */
vdi_fix(&src, saddr, swb, h); /* Load the source MFDB */
src.ff = TRUE; /* Set it's std form flag */
vdi_fix(&dst, daddr, dwb, h); /* Load the destination MFDB */
dst.ff = FALSE; /* Clear the std flag */
vr_trnfm(vdi_handle, &src, &dst ); /* Call the VDI */
}
/*------------------------------*/
/* trans_bitblk */
/*------------------------------*/
VOID
trans_bitblk(obspec) /* Transform the image belonging */
LONG obspec; /* to the bitblk pointed to by */
{ /* obspec. This routine may also*/
LONG taddr; /* be used with free images */
WORD wb, hl;
if ( (taddr = LLGET(BI_PDATA(obspec))) == -1L)
return; /* Get and validate image address */
wb = LWGET(BI_WB(obspec)); /* Extract image dimensions */
hl = LWGET(BI_HL(obspec));
vdi_trans(taddr, wb, taddr, wb, hl); /* Perform a transform */
} /* in place */
/*------------------------------*/
/* trans_obj */
/*------------------------------*/
VOID
trans_obj(tree, obj) /* Examine the input object. If */
LONG tree; /* it is an icon or image, trans- */
WORD obj; /* form the associated raster */
{ /* forms in place. */
WORD type, wb, hl; /* This routine may be used with */
LONG taddr, obspec; /* map_tree() to transform an */
/* entire resource tree */
type = LLOBT(LWGET(OB_TYPE(obj))); /* Load object type */
if ( (obspec = LLGET(OB_SPEC(obj))) == -1L) /* Load and check */
return (TRUE); /* ob_spec pointer */
switch (type) {
case G_IMAGE:
trans_bitblk(obspec); /* Transform image */
return (TRUE);
case G_ICON: /* Load icon size */
hl = LWGET(IB_HICON(obspec));
wb = (LWGET(IB_WICON(obspec)) + 7) >> 3;
/* Transform data */
if ( (taddr = LLGET(IB_PDATA(obspec))) != -1L)
vdi_trans(taddr, wb, taddr, wb, hl);
/* Transform mask */
if ( (taddr = LLGET(IB_PMASK(obspec))) != -1L)
vdi_trans(taddr, wb, taddr, wb, hl);
return (TRUE);
default:
return (TRUE);
}
}
>>>>>>>>>>>>>>>>>>> Macro definitions for the code above <<<<<<<<<<<<<<<<<<
#define BI_PDATA(x) (x)
#define BI_WB(x) (x + 4)
#define BI_HL(x) (x + 6)
#define OB_TYPE(x) (tree + (x) * sizeof(OBJECT) + 6)
#define OB_SPEC(x) (tree + (x) * sizeof(OBJECT) + 12)
#define IB_PMASK(x) (x)
#define IB_PDATA(x) (x + 4)
#define IB_WICON(x) (x + 22)
#define IB_HICON(x) (x + 24)
>>>>>>>>>>>>>>>>>>>>>>>>>>> VDI Copy Mode Table <<<<<<<<<<<<<<<<<<<<<<<<<<<<
Symbols: N = new destination pixel value (0 or 1)
D = old destination pixel value (0 or 1)
S = source pixel value (0 or 1)
~ = Boolean not (inversion)
& = Boolean and
| = Boolean or
^ = Boolean xor (exclusive-or)
Mode Number Action
---------- ------
0 N = 0 (USE V_BAR INSTEAD)
1 N = S & D
2 N = S & ~D
3 N = S (REPLACE)
4 N = ~S & D (ERASE)
5 N = D (USELESS)
6 N = S ^ D (XOR)
7 N = S | D (TRANSPARENT)
8 N = ~ (S | D)
9 N = ~ (S ^ D)
10 N = ~D (USE V_BAR INSTEAD)
11 N = S | ~D
12 N = ~S
13 N = ~S | D (REVERSE TRANSPARENT)
14 N = ~ (S & D)
15 N = 1 (USE V_BAR INSTEAD)
>>>>>>>>>>>>>>>>>>>>>>>>>>> END OF DOWNLOAD <<<<<<<<<<<<<<<<<<<<<<<<<<<<<
