
                               VDI IMAGE COPYING
                              -------------------
                             By:  Mrten Lindstrm
                            -----------------------

     When writing the documentation  for  my  image un/packing sub-routines
     (in assembler) designed to  be  used  with  the  VDI copy functions, I
     realised/remembered that, to  a  newcomer  to  GEM,  the VDI functions
     themselves need a bit of explanation too.

     This is a description  not  on  HOW  to  pass  parameters  or call VDI
     functions, but on WHAT parameters  to  pass  and functions to call and
     WHY.

     Screen dimensions and number of planes
     --------------------------------------
     As with all (compatible) work on the screen you should never assume it
     is of a particular size or number of colour planes. So just as a quick
     reminder, you get the  screen  dimensions  (coordinates of lower right
     corner) as the first two words of the WORK_OUT array returned when you
     open a (virtual) workstation (with V_OPNVWK).

     To get the number of planes  you  call VQ_EXTND after which the number
     can be found as WORK_OUT[4] (i.e.  the  word at offset 8 from WORK_OUT
     start.)

     The MFDB (Memory Form Definition Block)
     --------
     As parameters, all the  VDI  copy  functions  use  pointers NOT to the
     image/screen data but to MFDBs:

     MFDB (20 bytes):
       L: Pointer to image (or 0 = screen)
       W: Width in pixels
       W: Height
       W: Width in words  = (width in pixels +15)/16 truncated
       W: Format flag:  1 for device independent  0 for device specific
       W: Number of planes
      3W: 0 (reserved)

     An MFDB for the  screen  needs  only  to  consist  of  a single zeroed
     longword.

     Picture formats
     ---------------
     The format flag describes how the image data are arranged:

     0 - DEVICE SPECIFIC:
     This is how the screen memory  is  organized  and depends on where the
     program happens to be running. For  all  standard ST resolutions it is
     "word interleaved" (if  you  don't  understand  this  term don't worry
     about it), but in a  general  program,  written to be 100% compatible,
     you cannot make any assumptions at all regarding the organization of a
     device specific image - including the screen. And therefore you should
     not manipulate it directly in any way.


     1 - DEVICE INDEPENDENT:
     Here the image data are  separated  according to 'colour planes', i.e.
     first comes colour plane 0 for the complete image, then colour plane 1
     for the full image etc. (Colour plane 0 contains bit 0 for all pixels,
     plane 1 contains bit 1 etc.  Together  these bits form a colour number
     for each pixel.) In each  plane  the  pixel  data come in the 'natural
     order', line-wise 'left to right'  (bytes  in address number order and
     more significant bits of byte  before  the lesser ones) beginning with
     the top line and ending  with  the  bottom  line.  Each new pixel line
     always starts at next word boundary.

     An image in this format  can  safely be manipulated without 'dirtying'
     the code one bit.

     In practice you should load  all  images  as device independent forms,
     then transform them to  device  specific  format (with VR_TRNFM) after
     which  you  can   copy   (rectangles   of)   them   to   screen  (with
     VRO_CPYFM/VRT_CPYFM).

     In the opposite  direction  you  can  copy  from  screen  to  a device
     specific form, which can then be  transformed before it is exported as
     an image file.

     VR_TRNFM (Raster TRaNsForM)
     --------
     This function transforms a device  independent form to device specific
     format or vice versa. As parameters,  it  takes TWO pointers to source
     and destination MFDBs. These CAN be the  same (to save space) but that
     makes the transformation very slow.

     VR_TRNFM will look at the  format  flag  for  the source MFDB only and
     invert this in the destination MFDB.

     NOTE that VR_TRNFM must be used on  EVERY  image you import (load as a
     file) before you can copy it  to  screen.  Even mono images need to be
     transformed if you want your program  to  be 100% compatible (in spite
     of the fact that transformations  for  Atari standard mono resolutions
     perform nothing but a plain copy operation).

     VR_TRNFM does NOT (contrary to what  is  said in the Atari Compendium)
     transform colour numbers in any way.


     VRO_CPYFM (Raster Opaque CoPY ForM)
     ---------
     Copies a rectangle from a form to another. Both forms must (in present
     versions of TOS) be DEVICE  SPECIFIC.  And  they both must contain the
     same number of planes.

     Since VR_TRNFM too demands  forms  with  equal  number  of planes, the
     latter requirement means that if the  actual number of image planes is
     less than the screen planes, then  you  must add extra memory space to
     (the end of)  the  device  independent  image  as  fill planes, before
     transformation is effected.

     In the opposite case (# screen  planes  less  than # image planes) you
     only have to change the number of  planes in the MFDB (which will make
     VR_TRNFM ignore the extra planes).

     Parameters of VRO_CPYFM:
             Copy mode: word = 3 for plain copy
             Pointer to rectangle definition
             Pointer to source MFDB
             Pointer to destination MFDB

     If you use other  values  than  3  for  copy  mode,  you can logically
     combine source and  destination  images  in  various  ways.  Of the 16
     possible - more or less peculiar - modes, 1 ANDs and 7 ORs source with
     destination (possibly usable for sprite copying).

     The rectangle definition is an array of 8 words:

             Source X1,Y1, X2,Y2, Destination X1,Y1, X2,Y2

     where X1,Y2 are the coordinates for the upper left and X2,Y2 the lower
     right corner of the rectangle. Obviously you should make sure that the
     width and height are the  same  for source and destination rectangles.
     The present versions of VDI uses only  the  source size I think, but a
     future version could implement scaling.

     If you are unfamiliar  to  VDI  you  should  note  that the difference
     between first and second X/Y of  each  rectangle  is ONE LESS than the
     width/height of the rectangle.

     For example a rectangle covering a complete ST low rez screen would be
     defined as 0,0,319,199 (but again you should use screen dimensions got
     from WORK_OUT - see above.)



     VRT_CPYFM (Raster Transparent CoPY ForM)
     ---------
     This function works as VRO_CPYFM except that the source form should be
     single plane (regardless of number of planes in destination).

     For one-plane (i.e. mono) images,  VRT_CPYFM  can  thus  be used as an
     alternative to VRO_CPYFM, with the advantage  that no fill planes have
     to be added before  transformation  (saving  memory). The disadvantage
     seems to be (without  blitter  at  least)  a  somewhat slower speed of
     operation.

     A difference that should  be  noted  is  that  the  copy  mode word is
     defined differently for VRO_CPYFM and VRT_CPYFM. While the former uses
     its own 16 modes, VRT_CPYFM  uses  the  standard four VDI write modes.
     This means that for plain copy you  should  use 3 with VRO_CPYFM but 1
     with VRT_CPYFM.

     As a special further  parameter  with  VRT_CPYFM  are added VDI colour
     numbers for the ones and zeros of the image data.

     Parameters of VRT_CPYFM:
             Write mode: word = 1 for plain copy  NOTE!!!
             Pointer to rectangle definition
             Pointer to source MFDB
             Pointer to destination MFDB
             (Pointer to) VDI colour numbers for ones and zeros.


     Colour numbers
     --------------
     As is well known the (Atari) VDI uses its own mixed-up colour numbers.
     These numbers should never be  used  as  indexes  to the colours of an
     image file palette (which are  ordered  according the numbers formed -
     for each pixel - by the colour  plane bits). Instead you should create
     a translation table: bitplane  numbers  ->  VDI  numbers. For this the
     function V_GET_PIXEL can be used - See  the file IMG_IFF for a further
     discussion.

