        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---
