Professional GEM - Part VI - Raster operations: Difference between revisions
No edit summary |
No edit summary |
||
| Line 1: | Line 1: | ||
| + | {{Professional GEM}} |
||
| − | <pre> |
||
| + | ==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. |
||
| − | Professional GEM 39 |
||
| + | 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. |
||
| − | PART VI |
||
| − | Raster operations |
||
| + | ==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.) |
||
| − | SEASONS GREATINGS |
||
| + | 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. |
||
| − | 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. |
||
| + | ==Monochrome vs. color== |
||
| − | 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. |
||
| + | 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.) |
||
| − | DEFINING TERMS |
||
| + | 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. |
||
| − | 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!) |
||
| + | 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. |
||
| − | 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. |
||
| + | ==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. |
||
| − | MONOCHROME VS. COLOR |
||
| + | 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. |
||
| − | 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. |
||
| + | 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. |
||
| − | Professional GEM Part VI 40 |
||
| + | 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. |
||
| − | 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.) |
||
| + | 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. |
||
| − | 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. |
||
| + | ==Even words 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. |
||
| − | 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. |
||
| + | ==MFDB's== |
||
| − | 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. |
||
| + | 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 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 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. |
||
| − | 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 |
||
| + | 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.) |
||
| − | |||
| + | ==Let's operate== |
||
| − | Professional GEM Part VI 41 |
||
| + | 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. |
||
| − | output top to bottom. Within each word, the most significant |
||
| − | bit is the left-most on the screen. |
||
| + | ==Transform form== |
||
| − | 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. |
||
| + | 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: |
||
| − | 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. |
||
| + | <pre> |
||
| − | The system dependent form for the ST's monochrome mode is |
||
| + | vrtrnfm(vdihandle, source, dest); |
||
| − | very simple: it is identical to the standard form! This occurs |
||
| + | </pre> |
||
| − | because the ST uses a "reverse-video" setup in monochrome mode, |
||
| − | with the background set to white. |
||
| + | where source and dest are each pointers to MFDBs. They ARE 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. |
||
| − | 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. |
||
| + | 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. |
||
| − | 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. |
||
| + | 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. |
||
| − | 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. |
||
| + | 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. |
||
| − | EVEN WORDS 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 |
||
| + | ==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: |
||
| − | |||
| + | <pre> |
||
| + | vrocpyfm(vdihandle, mode, pxy, source, dest); |
||
| + | </pre> |
||
| + | 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. |
||
| − | Professional GEM Part VI 42 |
||
| + | 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. |
||
| − | in its upper byte. |
||
| + | 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. |
||
| − | MFDB's |
||
| + | ==Copy raster transparent== |
||
| − | 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. |
||
| + | 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: |
||
| − | 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. |
||
| + | <pre> |
||
| − | Finally, fdaddr is the 32-bit memory address of the form |
||
| + | vrtcpyfm(vdihandle, mode, pxy, source, dest, color); |
||
| − | itself. Zero is a special value for fdaddr. It denotes that |
||
| + | </pre> |
||
| − | 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. |
||
| + | 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. |
||
| − | 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.) |
||
| + | 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. |
||
| − | 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. |
||
| + | ==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. |
||
| − | 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: |
||
| + | ==Replace mode== |
||
| − | vrtrnfm(vdihandle, source, dest); |
||
| + | A mode of 3 results in a straight-forward copy: every destination pixel is replaced with the corresponding source form value. |
||
| − | where source and dest are each pointers to MFDBs. They ARE |
||
| + | ==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. |
||
| − | Professional GEM Part VI 43 |
||
| + | ==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. |
||
| − | 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. |
||
| + | ==Transparent mode== |
||
| − | 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. |
||
| + | 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. |
||
| − | 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. |
||
| + | ==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. |
||
| − | 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: |
||
| + | ==The problem of color== |
||
| − | vrocpyfm(vdihandle, mode, pxy, source, dest); |
||
| + | 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. |
||
| − | 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. |
||
| + | 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. |
||
| − | 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 |
||
| + | 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== |
||
| − | Professional GEM Part VI 44 |
||
| + | 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 assembly language drivers, the following hints will help you increase the VDI's performance. |
||
| − | 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. |
||
| + | ==AVoid merged copies== |
||
| − | 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. |
||
| + | 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. |
||
| − | 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. |
||
| + | ==Move to corresponding pixels== |
||
| − | COPY RASTER TRANSPARENT |
||
| + | 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. |
||
| − | 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); |
||
| + | ==Avoid fringes== |
||
| − | 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. |
||
| + | 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. |
||
| − | 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. |
||
| + | ==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 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. |
||
| − | THE MODE PARAMETER |
||
| − | The mode variable used in both of the copy functions is an |
||
| + | ==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== |
||
| − | Professional GEM Part VI 45 |
||
| + | 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? |
||
| − | integer with a value between zero and fifteen. It is used to |
||
| + | B) Too easy! Don't underestimate Atarians. |
||
| − | select how the copy function will merge the pixel values of the |
||
| + | C) About right, on the average. |
||
| − | 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. |
||
| + | 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. |
||
| − | REPLACE MODE |
||
| + | ==Coming up soon== |
||
| − | 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. |
||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | Professional GEM Part VI 46 |
||
| − | |||
| − | |||
| − | |||
| − | |||
| − | 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. |
||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | Professional GEM Part VI 47 |
||
| − | |||
| − | |||
| − | |||
| − | |||
| − | 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 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 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. |
||
| − | |||
| − | |||
| − | 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. |
||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | 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. |
||
| − | |||
| − | |||
| − | 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. |
||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | </pre> |
||
| + | 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]] |
||
Revision as of 22:30, 12 October 2006
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 words 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.
MFDB'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.)
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:
vrtrnfm(vdihandle, source, dest);
where source and dest are each pointers to MFDBs. They ARE 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.
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:
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 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.
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:
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.
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 assembly 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 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 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.
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.