Subject: The Complete And Essential Guide To Bitmaps Part Two: The GFA Bitmap Handling Sources By: James Collett (Professor) A Member Of: VIRTUAL INFINITY Date: January 1994 E-mail: s6005146@brookes.ac.uk Address: Park View Farm, Carlton, Nr Nuneaton, Warks, CV13 ODA Mono account: bcc Disclaimer & Copyright ====================== This is not a contradiction in terms! Although every effort has been made to ensure the programs are working correctly, no responsibility is held for the actions of the programs. The programs should work if used in accord with this file, but if you don`t read this file -well, you never know! Although there is no financial charge for the program, support is appreciated. You can support in two ways: 1) by distributing the programs, with all notes, to everyone you know, ensuring the names PROFESSOR and VIRTUAL INFINITY remain with the program, 2) feedback: all comments, queries, suggestions, ideas, error / incompatibility reports, etc are welcome - both positive and negative. My E-mail and postal addresses are previously listed. If you wish to use any part of any of my programs or routines in your own programs or applications, you must give credit to me, for example "Bitmap coding by Professor of VIRTUAL INFINITY". Notice ====== Before you read this file you may like to read BITPLANE.TXT, which contains an introduction to bitmaps & bitplanes plus explanations of the terms and notations I use. If this file is missing, and you would like a copy, please either E-mail or write to me. On The Disk =========== The following three files should also be included on the disk: BITMAP_G.GFA, the 'generic' version BITMAP_S.GFA, the 'speedy' version BITMAP_U.GFA, the 'ultra speedy' version If any of these files are missing, and you would like a copy, please either E-mail or write to me. Before Running The Programs, Setting The Constants ================================================== Before the functions and procedures in these programs can be run, four constants must be correctly set up by the user and then NOT altered. The first, NO_PLANES|, is the number of planes, and should take a value between 1 and 16 (inclusive). The second constant, PLANE_BITS|, is the plane size (in bits). The routines can handle four plane sizes: 8, 16, 24 and 32, though 8 and 16 are recommended for speed reasons. The third constant, S_ADDR%, is the start address of the bitmap (screen), and MUST be an even value. [XBIOS(2) is normally the start address of the 'system bitmap (screen)', i.e. that which is displayed, and is always an even value]. The final constant which the user must set, S_LENG%, is the length (in bytes) of the bitmap (screen). This can be calculated from (Total pixels * Number of planes / 8). The length is not as vital as the first three constants, and an arbitrary value can be used if necessary. Note the default settings for the first four constants are for ST Low resolution compatible. From the first four constants a number of other constants are calculated by the program: plane size (in bytes), block size (in bytes), total blocks, total pixels and the plane mask. Note that when the plane size is 32 bits (4 bytes), two additional masks are needed. The reason for this is 32 bit words need to be converted from unsigned to signed in order to be stored and processed, whereas 24 bit or lower words can be stored and processed unsigned. The two additional masks, 'positive mask' and 'negative mask', are used by @sign to convert unsigned 32 bit words (called LONG WORDS). Note that once these constants have been initially set, they should NOT be altered. The 'Generic' Version: BITMAP_G.GFA =================================== This program is very very slow, but contains lots of low level bitmap utilities and should be portable to virtually any graphics machine or language. The first utility, @exist, returns TRUE if the pixel`s block exists, or FALSE if the block doesn`t exist. It can be used to test whether a block exists, prior to attempting to read or write a plane in the block. It is an alternative to testing whether a pixel exists. The second utility, @block, returns the theoretical block in which the pixel is stored. The third utility, @b_addr, returns the theoretical 'offset' or address (in bytes), of the pixel`s block from the start of the bitmap. Neither of these utilities take into account whether the block or pixel actually exist. The fourth utility, @position, returns the position of the bit in each plane (in a theoretical block), which will be used to determine the pixel`s color. This utility doesn`t take into account whether the block of pixels actually exist. The fifth utility, @bin$, displays the plane in binary. This utility is primarily provided for testing and debugging purposes. It is not intended to be used on final applications. The sixth, seventh and eighth utilities, @get_bit, @set_bit and @reset_bit respectively, perform binary operations on data (planes and colors). Note the mask must be 2^bit_to_operate. The ninth utility, @sign, has already been discussed. It is used to convert 32 bit unsigned planes to signed planes. The tenth and eleventh utilities, @read_plane and write_plane, are not hidden for copyright reasons, it is simply to make them convenient. If you wish to unhide them simply remove the markers. Note once unhidden, functions & procedures cannot easily be re-hidden. If you wish to unhide, you may wish to keep a copy of the hidden functions & procedures on disk. These utilities read or write a single plane, given the address of the block and the plane within the block. Neither of these utilities take into account whether the block or plane actually exist. The twelfth and thirteenth utilities, @read_pixel and write_pixel, are not hidden for copyright reasons, it is simply to make them convenient. If you wish to unhide them simply remove the markers. Note that once unhidden, functions & procedures cannot easily be re-hidden. If you wish to unhide, you may wish to keep a copy of the hidden functions & procedures on disk. These utilities read or write a 'complete' pixel using some of the above utilities. Initially, both utilities set the block address (used by @read_plane & write_plane) plus position mask (used by the binary operation utilities). Then @read_pixel extracts the pixel`s bit from each plane and constructs the colour, before returning the colour. After initialising, write_pixel either sets or resets the pixel`s bit in each plane, dependant on the colour to be written. Neither of these utilities take into account whether the block or pixel actually exist. The 'Speedy' Version: BITMAP_S.GFA ================================== The 'generic' program, discussed above, is very very slow. This program is just very slow! The constants are the same as previously discussed, and should NOT be altered once initially set. This version, as with the 'generic' version, should be portable to virtually any graphics machine or language. However the library of bitmap utilities with the 'generic' version has been considerably shortened - the price that has to be paid for optimisation. The first utility in this version, @sign, has previously been discussed. It is used to convert 32 bit unsigned planes to signed planes. The second and third utilities, @read_plane and write_plane, are not hidden for copyright reasons, it is simply to make them convenient. If you wish to unhide them simply remove the markers. Note once unhidden, functions & procedures cannot easily be re-hidden. If you wish to unhide, you may wish to keep a copy of the hidden functions & procedures on disk. These utilities read or write a single plane, given the address of the block and the plane within the block. Neither of these utilities take into account whether the block or plane actually exist. The fourth and fifth utilities, @read_pixel and write_pixel, are not hidden for copyright reasons, it is simply to make them convenient. If you wish to unhide them simply remove the markers. Note once unhidden, functions & procedures cannot easily be re-hidden. If you wish to unhide, you may wish to keep a copy of the hidden functions & procedures on disk. These utilities read or write a 'complete' pixel using the above utilities. Initially, both utilities set the block address (used by @read_plane & write_plane) plus position mask (used by the binary operations). Then @read_pixel extracts the pixel`s bit from each plane and constructs the colour, before returning the color. After initialising, write_pixel either sets or resets the pixel`s bit in each plane, dependant on the colour to be written. Neither of these utilities take into account whether the block or pixel actually exist. The 'Ultra Speedy' Version: BITMAP_U.GFA ======================================== The 'speedy' program, discussed above, is very slow. This program is just slow! The constants are the same as previously discussed, with the exception of PLANE_BITS|, the plane size (in bits), which MUST be set to 16. The constants should NOT be altered once initially set. As the plane size is fixed at 16 bits, the 'ultra speedy' version`s portability is limited - the price that has to be paid for optimisation. The library of bitmap utilities with the 'speedy' version has been shortened further. The two utilities, @read_pixel and write_pixel, are not hidden for copyright reasons, it is simply to make them convenient. If you wish to unhide them simply remove the markers. Note once unhidden, functions & procedures cannot easily be re-hidden. If you wish to unhide, you may wish to keep a copy of the hidden functions & procedures on disk. {Now where have you read that before!} The utilities read or write a 'complete' pixel. Initially, both utilities set the block address (used for locating planes) plus position mask (used by the binary operations). Then @read_pixel extracts the pixel`s bit from each plane and constructs the colour, before returning the colour. After initialising, write_pixel either sets or resets the pixel`s bit in each plane, dependant on the colour to be written. Neither of these utilities take into account whether the block or pixel actually exist. {Sounds a bit familiar!} Future Developments: Assembly Version Wanted ==================== ~~~~~~~~~~~~~~~~~~~~~~~ The ideas and plans for future developments of bitmap routines are virtually ENDLESS, though a list of some utilities proposed as future development is included with the 'generic' program, BITMAP_G.GFA. Although adequate for low level graphics research, the GFA routines are barely fast enough for applications (demos, games, etc). I have attempted to optimise the 'ultra speedy' version further, but have been unable to step it up much more - and even if the speed could be HALVED, they still wouldn`t be FAST! The best (only) way to make them fast enough for applications, is to convert them to assembly. If anyone feels like converting them to assembly or writing some bitmap routines in assembly one rainy afternoon, please let me know. My E-mail and postal addresses are previously listed. And Finally: Feedback ===================== All comments, queries, suggestions, ideas, error / incompatibility reports, etc are welcome - both positive and negative. My E-mail and postal addresses are previously listed. ---END---