home *** CD-ROM | disk | FTP | other *** search
/ Falcon 030 Power 2 / F030_POWER2.iso / ST_STE / MAGS / ICTARI08.ARJ / ictari.08 / GFA / BITMAP.TXT < prev    next >
Text File  |  1994-03-10  |  13KB  |  246 lines
  1.         Subject: The Complete And Essential Guide To Bitmaps
  2.        Part Two: The GFA Bitmap Handling Sources
  3.              By: James Collett (Professor)
  4.     A Member Of: VIRTUAL INFINITY
  5.            Date: January 1994
  6.          E-mail: s6005146@brookes.ac.uk
  7.         Address: Park View Farm, Carlton, Nr Nuneaton, Warks, CV13 ODA
  8.     Mono account: bcc
  9.  
  10.  
  11.     Disclaimer & Copyright
  12.     ======================
  13.     This is not a contradiction in  terms!   Although every effort has been
  14.     made to ensure the programs  are  working correctly,  no responsibility
  15.     is held for the actions of the  programs.   The programs should work if
  16.     used in accord with this file,  but  if you don`t read this file -well,
  17.     you never know!
  18.  
  19.     Although there is no financial  charge  for the program,   support   is
  20.     appreciated.  You can support in two ways:
  21.  
  22.     1) by  distributing the programs, with all notes,  to everyone  you
  23.        know,  ensuring the names PROFESSOR and VIRTUAL INFINITY  remain
  24.        with the program,
  25.  
  26.     2) feedback:  all comments,  queries,  suggestions,  ideas, error /
  27.        incompatibility  reports,  etc are welcome - both  positive  and
  28.        negative.  My E-mail and postal addresses are previously listed.
  29.  
  30.     If you wish to use any part of  any  of my programs or routines in your
  31.     own programs or applications,  you must give credit to me,  for example
  32.     "Bitmap coding by Professor of VIRTUAL INFINITY".
  33.  
  34.  
  35.     Notice
  36.     ======
  37.     Before you read this file  you  may  like to read  BITPLANE.TXT,  which
  38.     contains an introduction to  bitmaps  &  bitplanes plus explanations of
  39.     the terms and notations I use.
  40.  
  41.     If  this file is missing,  and  you  would like a copy,  please  either
  42.     E-mail or write to me.
  43.  
  44.  
  45.     On The Disk
  46.     ===========
  47.     The following three files should also be included on the disk:
  48.  
  49.                  BITMAP_G.GFA, the 'generic' version
  50.                  BITMAP_S.GFA, the 'speedy' version
  51.                  BITMAP_U.GFA, the 'ultra speedy' version
  52.  
  53.     If any of these files are missing,  and you would like a copy, please
  54.     either E-mail or write to me.
  55.  
  56.  
  57.     Before Running The Programs, Setting The Constants
  58.     ==================================================
  59.     Before  the  functions and procedures  in  these programs can  be  run,
  60.     four  constants  must  be  correctly  set  up  by  the  user  and  then
  61.     NOT  altered.   The first,  NO_PLANES|,  is  the number of planes,  and
  62.     should  take  a  value  between  1  and  16  (inclusive).   The  second
  63.     constant, PLANE_BITS|,  is the plane size  (in bits).  The routines can
  64.     handle four  plane sizes:  8,  16,  24  and  32,  though  8  and 16 are
  65.     recommended for speed  reasons.    The   third  constant,  S_ADDR%,  is
  66.     the start address  of   the   bitmap  (screen),   and  MUST  be an even
  67.     value.   [XBIOS(2) is  normally  the   start   address   of the 'system
  68.     bitmap  (screen)',  i.e.  that  which  is  displayed,  and is always an
  69.     even value].   The final constant which the  user must set, S_LENG%, is
  70.     the length (in bytes) of the bitmap (screen).
  71.  
  72.     This can be calculated from  (Total  pixels  *  Number  of planes / 8).
  73.     The  length  is not as  vital  as  the  first  three constants,  and an
  74.     arbitrary  value can be used if necessary.
  75.  
  76.     Note the default settings for the  first  four constants are for ST Low
  77.     resolution compatible.
  78.  
  79.     From  the  first  four  constants  a  number  of  other  constants  are
  80.     calculated by the  program:  plane  size  (in  bytes),  block  size (in
  81.     bytes),  total blocks, total pixels and the plane mask.  Note that when
  82.     the plane size  is 32 bits (4 bytes),  two additional masks are needed.
  83.     The reason for  this   is   32  bit  words  need  to  be converted from
  84.     unsigned to  signed  in  order to  be stored and processed,  whereas 24
  85.     bit or lower words can  be   stored   and processed unsigned.   The two
  86.     additional  masks,  'positive  mask' and  'negative mask',  are used by
  87.     @sign to convert unsigned 32 bit  words (called LONG WORDS).
  88.  
  89.     Note that once these constants have been initially set, they should NOT
  90.     be  altered.
  91.  
  92.  
  93.     The 'Generic' Version: BITMAP_G.GFA
  94.     ===================================
  95.     This  program  is very very slow,   but   contains lots  of  low  level
  96.     bitmap   utilities   and   should  be   portable   to   virtually   any
  97.     graphics  machine or language.    The  first utility,  @exist,  returns
  98.     TRUE if  the  pixel`s  block  exists,   or  FALSE  if the block doesn`t
  99.     exist.   It can  be  used  to   test  whether a block exists,  prior to
  100.     attempting to  read   or   write  a  plane  in  the  block.    It is an
  101.     alternative to testing whether  a  pixel exists.
  102.  
  103.     The second utility,  @block,  returns  the  theoretical block in  which
  104.     the  pixel  is   stored.     The   third   utility,   @b_addr,  returns
  105.     the  theoretical  'offset' or address (in bytes),  of the pixel`s block
  106.     from  the start of the bitmap.    Neither  of these utilities take into
  107.     account  whether the block or pixel actually exist.
  108.  
  109.     The  fourth utility,  @position,  returns  the  position of the bit  in
  110.     each plane (in a theoretical  block),  which  will be used to determine
  111.     the  pixel`s color.  This utility doesn`t take into account whether the
  112.     block  of pixels actually exist.
  113.  
  114.     The fifth utility, @bin$, displays  the  plane in binary.  This utility
  115.     is  primarily provided for  testing  and  debugging  purposes.   It  is
  116.     not  intended to be used on final applications.
  117.  
  118.     The  sixth,  seventh and  eighth   utilities,  @get_bit,  @set_bit  and
  119.     @reset_bit respectively,  perform  binary  operations  on  data (planes
  120.     and  colors).  Note the mask must be 2^bit_to_operate.
  121.  
  122.     The ninth utility,  @sign, has already  been  discussed.  It is used to
  123.     convert 32 bit unsigned planes to signed planes.
  124.  
  125.     The tenth and eleventh  utilities,   @read_plane and  write_plane,  are
  126.     not  hidden  for  copyright  reasons,   it   is  simply  to  make  them
  127.     convenient.   If   you   wish   to  unhide  them  simply   remove   the
  128.     markers.   Note  once  unhidden,  functions  & procedures cannot easily
  129.     be re-hidden.   If  you  wish  to unhide,   you may wish to keep a copy
  130.     of the hidden functions  &   procedures  on disk.  These utilities read
  131.     or write a single plane, given  the  address of the block and the plane
  132.     within the  block.   Neither   of   these   utilities take into account
  133.     whether the block or  plane  actually  exist.
  134.  
  135.     The  twelfth and thirteenth  utilities,   @read_pixel and  write_pixel,
  136.     are  not  hidden  for   copyright  reasons,   it  is   simply  to  make
  137.     them  convenient.   If  you  wish  to  unhide  them  simply  remove the
  138.     markers.  Note  that  once  unhidden,   functions  &  procedures cannot
  139.     easily be  re-hidden.   If  you wish to unhide,  you may wish to keep a
  140.     copy of the hidden functions   &  procedures on disk.   These utilities
  141.     read or write a 'complete'  pixel   using  some of the above utilities.
  142.     Initially,   both  utilities  set    the    block   address   (used  by
  143.     @read_plane & write_plane) plus   position   mask   (used by the binary
  144.     operation utilities).  Then @read_pixel extracts  the  pixel`s bit from
  145.     each plane and constructs the  colour,   before  returning  the colour.
  146.     After initialising,  write_pixel either  sets  or  resets  the  pixel`s
  147.     bit  in  each  plane,   dependant  on  the   colour   to   be  written.
  148.     Neither of these  utilities  take  into  account  whether  the block or
  149.     pixel  actually exist.
  150.  
  151.  
  152.     The 'Speedy' Version: BITMAP_S.GFA
  153.     ==================================
  154.     The  'generic' program,  discussed above,   is  very very  slow.   This
  155.     program   is  just  very  slow!    The   constants  are  the  same   as
  156.     previously  discussed,  and should NOT  be  altered once initially set.
  157.     This version,  as  with  the 'generic' version,  should be portable  to
  158.     virtually  any  graphics machine or  language.   However the library of
  159.     bitmap  utilities  with  the  'generic'  version  has been considerably
  160.     shortened - the  price  that  has   to  be paid for optimisation.   The
  161.     first   utility   in   this    version,   @sign,  has  previously  been
  162.     discussed.  It is used to  convert  32   bit  unsigned planes to signed
  163.     planes.
  164.  
  165.     The second and third utilities,   @read_plane  and write_plane, are not
  166.     hidden for copyright reasons,  it  is  simply  to make them convenient.
  167.     If  you wish to  unhide  them  simply  remove  the markers.   Note once
  168.     unhidden,  functions  &  procedures  cannot  easily  be re-hidden.   If
  169.     you  wish  to  unhide,  you  may  wish  to  keep  a  copy of the hidden
  170.     functions & procedures  on  disk.    These   utilities  read or write a
  171.     single  plane,  given  the  address of  the  block and the plane within
  172.     the block.   Neither of  these  utilities take into account whether the
  173.     block or plane actually exist.
  174.  
  175.     The fourth and fifth utilities,  @read_pixel  and write_pixel,  are not
  176.     hidden for copyright reasons,  it  is  simply  to make them convenient.
  177.     If  you wish to  unhide  them  simply  remove  the markers.   Note once
  178.     unhidden,  functions  &  procedures  cannot  easily  be re-hidden.   If
  179.     you  wish  to  unhide,  you  may  wish  to  keep  a  copy of the hidden
  180.     functions & procedures  on   disk.    These  utilities  read or write a
  181.     'complete'  pixel   using   the   above  utilities.    Initially,  both
  182.     utilities set the block address  (used  by  @read_plane  & write_plane)
  183.     plus position mask (used by  the  binary  operations). Then @read_pixel
  184.     extracts the  pixel`s  bit  from  each  plane   and    constructs   the
  185.     colour, before returning the  color.  After  initialising,  write_pixel
  186.     either sets or resets the pixel`s bit  in each  plane, dependant on the
  187.     colour to be written.  Neither  of  these  utilities  take into account
  188.     whether the block or pixel actually exist.
  189.  
  190.  
  191.     The 'Ultra Speedy' Version: BITMAP_U.GFA
  192.     ========================================
  193.     The 'speedy' program, discussed above,  is  very slow.  This program is
  194.     just slow!  The constants are  the  same  as previously discussed, with
  195.     the  exception of PLANE_BITS|, the plane  size (in bits), which MUST be
  196.     set to  16.   The  constants should  NOT be altered once initially set.
  197.     As  the  plane size is fixed  at  16 bits, the 'ultra speedy' version`s
  198.     portability  is  limited   -   the  price  that  has  to  be  paid  for
  199.     optimisation.   The  library  of  bitmap  utilities  with  the 'speedy'
  200.     version has been shortened  further.
  201.  
  202.     The two utilities,  @read_pixel and  write_pixel,   are not hidden  for
  203.     copyright reasons, it is simply to  make  them convenient.  If you wish
  204.     to  unhide  them  simply  remove  the  markers.    Note  once unhidden,
  205.     functions &  procedures cannot easily  be  re-hidden.    If you wish to
  206.     unhide,  you may   wish  to  keep  a  copy  of  the  hidden functions &
  207.     procedures on disk.   {Now  where have you read that before!}
  208.  
  209.     The  utilities read or write  a   'complete'  pixel.   Initially,  both
  210.     utilities set  the  block  address  (used  for  locating  planes)  plus
  211.     position  mask  (used  by  the  binary  operations).   Then @read_pixel
  212.     extracts  the  pixel`s bit from  each  plane and constructs the colour,
  213.     before   returning   the  colour.    After  initialising,   write_pixel
  214.     either sets or resets  the  pixel`s bit in each plane, dependant on the
  215.     colour to be written.  Neither   of  these  utilities take into account
  216.     whether the block or pixel actually  exist.  {Sounds a bit familiar!}
  217.  
  218.  
  219.     Future Developments: Assembly Version Wanted
  220.     ==================== ~~~~~~~~~~~~~~~~~~~~~~~
  221.     The  ideas and plans for  future  developments of bitmap  routines  are
  222.     virtually  ENDLESS,   though  a  list  of  some  utilities  proposed as
  223.     future   development   is   included   with   the   'generic'  program,
  224.     BITMAP_G.GFA.
  225.  
  226.     Although adequate for low level  graphics  research,  the GFA  routines
  227.     are barely fast  enough  for  applications  (demos,   games,  etc).   I
  228.     have  attempted to optimise  the  'ultra  speedy' version further,  but
  229.     have been  unable to step it up much more - and even if the speed could
  230.     be  HALVED,  they  still  wouldn`t  be  FAST!    The best (only) way to
  231.     make  them  fast  enough   for  applications,   is  to  convert them to
  232.     assembly.   If  anyone   feels   like  converting  them  to assembly or
  233.     writing some  bitmap   routines   in   assembly  one  rainy  afternoon,
  234.     please let me know.   My  E-mail   and  postal addresses are previously
  235.     listed.
  236.  
  237.  
  238.     And Finally: Feedback
  239.     =====================
  240.     All comments,  queries,  suggestions,   ideas,  error / incompatibility
  241.     reports,  etc are welcome  -  both  positive  and negative.   My E-mail
  242.     and  postal addresses are previously listed.
  243.  
  244.  
  245.                                    ---END---
  246.