home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 514b.lha / CITAS_v2.0 / CITAS.doc.pp / CITAS.doc
Text File  |  1991-06-08  |  10KB  |  252 lines
  1.  
  2.              **************************************************
  3.              *                                                *
  4.              *  CITAS (Convert ILBM To Assembler Source)      *
  5.              *                                                *
  6.              *       ---- A Max Bithead production ----       *
  7.              *                                                *
  8.              *        Release 1.0: 4/7/90                     *
  9.              *                                                *
  10.              *        Release 1.1: 6/2/90                     *
  11.              *                                                *
  12.              *        Release 2.0: 7/9/90                     *
  13.              *                                                *
  14.              **************************************************
  15.  
  16.  
  17. CHANGES:
  18. -------
  19.  
  20. V2.0:
  21. ----
  22.  
  23.     Well, I got my first bug report (I knew one would come sooner or later).
  24.   It seems that CITAS was choking on DPaint III 64 color pictures.  It blew
  25.   out a buffer when there were more than 32 colors in the file.  Well, you
  26.   know the old saying about assumptions...
  27.  
  28.     During Beta testing, one more bug was reported.  It seems I forgot to
  29.   update a routine to skip past a mask in the file (if it exists) during
  30.   preprocessing.  This caused a read error (which should never be seen 
  31.   unless the system actually has a problem reading the file).
  32.  
  33.     Other changes include:
  34.  
  35.       1) Now print an error message in the case of an unrecognized
  36.          compression format.
  37.       2) Added an option to output the mask supplied with the file instead of
  38.          generating one.  If using this option, and no mask is present in
  39.          the file, no mask will be generated.
  40.       3) CITAS now does 'C' source too!  I suppose the name has a little less
  41.          meaning now, but oh well, so does IBM.  If you're using the 'C' 
  42.          source option, options "-x" and "-s" won't do anything.
  43.  
  44.     Thanks go to Shawn Steele and Frank Weed for their helpful bug reports,
  45.   suggestions, and Beta testing.  Thanx guys!
  46.  
  47.     Enjoy!  And help support shareware.
  48.  
  49.  
  50. V1.1:
  51. ----
  52.  
  53.     I changed my blitter routines, which, unfortunately, meant changing
  54.   CITAS.  The DEPTH equate now reflects the number of bit planes from the
  55.   original image.  The reason being that if a bit plane is all zero's, it
  56.   has to be cleared (using the mask) when blitting the image to the screen.
  57.   This is a very minor change, but it makes life easier.
  58.  
  59.   Make sure you don't blit to a screen with less bit planes than your graphic
  60.   data!
  61.  
  62.  
  63. INTRO:
  64. -----
  65.  
  66.  
  67.     Ok all you assembler gurus out there.  This program's for you.
  68.   CITAS takes an ILBM file and converts it to assembler source for use
  69.   in your own programs (V2.0 can produce 'C' source instead).
  70.  
  71.     In the beginning... I wrote this program in assembler, for assembler,
  72.   because I wanted an easy way to draw graphics with a paint program and then
  73.   use them in my own assembly programs via blitter control.  Unfortunately, 
  74.   I can be somewhat of a perfectionist, and CITAS soon became a full featured
  75.   utility which took one full month (to the day) to complete and release.  I
  76.   gotta say I'm pleased with the results, though.  I gave CITAS a single
  77.   read buffer, and a single write buffer, but it's still pretty quick.  It
  78.   also uses less than 14K RAM while running, so converting in ram: is easy
  79.   to do.
  80.  
  81.     CITAS is my first official piece of software for the Amiga.  Hope you
  82.   like it!
  83.  
  84.   NOTE: CITAS will not waste memory by extracting a null plane.  The 
  85.   resultant "planes" labels will reflect what is actually used.  Also, should
  86.   you wish to stop CITAS while it's running, hit CTRL-C.
  87.  
  88.  
  89. SECTION 1, USAGE:
  90. ----------------
  91.  
  92.  
  93.     Ok, nuff chatter already.  At a CLI prompt (CITAS operates only from
  94.   CLI), type:
  95.  
  96.  
  97. CITAS ILBMfile [result_file] [-c] [-m] [-f] [-x] [-s] [-o] [-h] [$nn] ["sfx"]
  98.  
  99.  
  100.     The parameters in brackets are optional and may be supplied in any
  101.   order with the exception of the result_file parameter which, if supplied,
  102.   must follow the ILBM file name.  All parameters are seperated by blanks.
  103.   Type "CITAS" without any parameters for a brief description of its use.
  104.  
  105.  
  106.     The parameters:
  107.  
  108.     result_file = The name of the output file.  This output file name,
  109.          minus any extension (.whatever), will be used in generating
  110.          the labels for your data.  Labels allow you to set up and
  111.          assemble your code before actually using CITAS to create the
  112.          data.  It also allows you to modify the data without touching
  113.          the linkable code.
  114.  
  115.          If no output file name is given, the input file name, minus
  116.          any extension, will be used for the labels, and will be the
  117.          name of the output file plus a ".asm" or ".c" extension.  This
  118.                default file name will be placed in the current directory.
  119.  
  120.     -c = Inhibit generation of color table.  By default, CITAS will
  121.          include a color table in the output file.
  122.  
  123.     -m = Inhibit generation of image mask.  By default, CITAS will
  124.          include a mask plane in the output file.  This mask is
  125.          created by CITAS reguardless of whether or not the ILBM file
  126.          contains a mask, and is simply a logical OR of all bit planes.
  127.          It is meant to facilitate the use of the "cookie-cut" blitter
  128.          minterm, which requires an image mask (at least that's how
  129.          I use it).
  130.  
  131.     -f = Generate source for the mask supplied with the file.  If no
  132.                mask exists in the file, do not generate a mask.
  133.  
  134.     -x = Generate export definitions (XDEF) of labels for making 
  135.          linkable data.
  136.  
  137.     -s = Generate a "section" directive specifying chip RAM.  This
  138.          allows me to generate a hunk of data that will automatically
  139.          load into chip RAM.  Since the only assembler I am familiar
  140.          with on the Amiga is Devpac, I'm not sure if other assemblers
  141.          will appreciate this particular directive.
  142.  
  143.     -o = Allow an existing file to be overwritten by the output file.
  144.          By default, CITAS will abort with an error if the output
  145.          file already exists.  This is more or less a safety feature.
  146.  
  147.     -h = Generate 'C' source code instead of assembler.
  148.  
  149.     $nn = User supplied hex mask of planes to extract.  This allows
  150.           selection of only the bit planes you want extracted.
  151.           Normally the resultant "planes" label will contain a mask
  152.           of all planes that are not null (all zero).  This may be
  153.           further modified by entering your own mask.  Bit numbers
  154.           correspond to plane numbers (ie bit 0 corresponds to
  155.           plane 0).  Note, however, that if a plane specified by
  156.           your mask is null, it will not be extracted.  Thus if you
  157.           entered a mask of $03, and plane 0 of the ILBM file was
  158.           all zeros, the resultant "planes" label would be $02.
  159.           Entering $ff will simply give you all non-zero planes, which
  160.           is the default.
  161.  
  162.     "sfx" = Any suffix needed to follow labels.  I realize that some
  163.             assemblers require a suffix on their labels, such as ":".
  164.             This is for those weirdo assemblers.
  165.  
  166.  
  167. SECTION 2, LABELS:
  168. -----------------
  169.  
  170.  
  171.     CITAS inserts several labels into the resultant source file.  Some
  172.   of these labels are equates (EQU) and others mark the start of different
  173.   data segments.  The first part of a label, as described earlier, is the
  174.   output file name.  The remainder of the label will be standard in every
  175.   CITAS created file, and starts with an underscore character.
  176.  
  177.   NOTE: V2.0 'C' source files will contain "#define"'s and arrays instead
  178.   of equates and labels.
  179.  
  180.  
  181.     The equates:
  182.  
  183.     _height    = The height of the image in scan lines
  184.     _width    = The width of the image in words
  185.     _depth    = The depth of the image in planes
  186.     _planes    = Mask of which bit planes are used to display the image
  187.           (so we don't have to waste memory with null planes, and
  188.            to specify how to display the image planes in a bitmap)
  189.  
  190.     The labels:
  191.  
  192.     _color    = The address of the 1st byte of the color table (if
  193.           generated).  Also, the color values on each line
  194.                       represent red, green, and blue respectively, and
  195.                       pertain to color registers 0 at the top line, through
  196.                       31 at the last line of the color table.
  197.     _image    = The address of the 1st byte of the 1st generated
  198.           bit plane.
  199.     _mask    = The address of the 1st byte of the mask plane (if
  200.           generated)
  201.     _end    = The address of one byte past the last byte in the
  202.           generated file.  This is normally just past the
  203.           image mask, or just past the image data if no mask
  204.           is generated.  This is NOT generated in a 'C' source
  205.                       output file.  I myself don't use this label, but I
  206.                       stuck it in there in case someone might find a use
  207.                       for it.
  208.  
  209.  
  210. SECTION 3, THE DREADED SHAREWARE NOTICE:
  211. ---------------------------------------
  212.  
  213.  
  214.     That's right, CITAS is copyright Max Bithead (a.k.a. John Enright), and
  215.   and is considered shareware.  It is not for sale, nor may it be included
  216.   in any commercial product without my written permission.  It is, however,
  217.   an excellent tool for CREATING commercial products.  Have at it!
  218.  
  219.     CITAS may be freely distributed as long as this document accompanies it.
  220.   Finally, I claim no responsibility for any loss or penalty incurred by the
  221.   use of this program.
  222.  
  223.     Whew!  Ok, paranoia aside, I hope that you find this program useful
  224.   in developing great Amiga software.  I know it works wonders for me.
  225.   Graph paper was absolutely out of the question!  ha ha.  There are no
  226.   known bugs (again).
  227.  
  228.     I'm asking a measly $10 for CITAS if you intend to use it.  The cheapest
  229.   development software you'll ever buy.  Or, hey, send whatever you think
  230.   it's worth.  Support shareware for good, cheap stuff!
  231.  
  232.   Send any comments/suggestions/bug reports, and/or payment to me at:
  233.  
  234.         John Enright
  235.         2955 Glenwood Dr. #301
  236.         Boulder, Colorado, 80301  (USA)
  237.         (303) 938-9490
  238.  
  239.     You may also send electronic mail to Max Bithead on any of these great
  240.   BBS's:
  241.  
  242.     Reggae Land  (303) 699-2671
  243.     CD Players   (303) 825-0419
  244.     Arvada 68K   (303) 424-9831
  245.     BAUG         (303) 666-5221
  246.  
  247.  
  248.                       -------------- * * --------------
  249.                                       "
  250.                                      \_/
  251.  
  252.