home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 375.lha / CITAS_v1.0 / CITAS.doc < prev    next >
Text File  |  1990-05-02  |  8KB  |  193 lines
  1.  
  2.              **************************************************
  3.              *                                                *
  4.              *  CITAS 1.0 (Convert ILBM To Assembler Source)  *
  5.              *                                                *
  6.              *       ---- A Max Bithead production ----       *
  7.              *                                                *
  8.              *                     4/7/90                     *
  9.              *                                                *
  10.              **************************************************
  11.  
  12. INTRO:
  13. -----
  14.  
  15.  
  16.     Ok all you assembler gurus out there.  This program's for you.
  17.   CITAS takes an ILBM file and converts it to assembler source for use
  18.   in your own programs.  If you're familiar with NGI, CITAS does basically
  19.   the same thing, only without the gadgets, and the output is assembly
  20.   source instead of 'C'.  It also has a few nice features that NGI doesn't
  21.   have.
  22.  
  23.     In the beginning... I wrote this program in assembler, for assembler,
  24.   because I wanted an easy way to draw graphics with a paint program and then
  25.   use them in my own assembly programs via blitter control.  Unfortunately, 
  26.   I can be somewhat of a perfectionist, and CITAS soon became a full featured
  27.   utility which took one full month (to the day) to complete and release.  I
  28.   gotta say I'm pleased with the results, though.  I gave CITAS only a single
  29.   read buffer, and a single write buffer, but this baby smokes!  What a nice
  30.   surprise.  It also uses only about 12K RAM while running.
  31.  
  32.     CITAS is my first official piece of software for the Amiga.  Hope you
  33.   like it!
  34.  
  35.   NOTE: CITAS will not waste memory by extracting a null plane.  The 
  36.   resultant "depth" and "planes" labels will reflect what is actually used.
  37.   Also, should you wish to stop CITAS while it's running, hit CTRL-C.
  38.  
  39.  
  40. SECTION 1, USAGE:
  41. ----------------
  42.  
  43.  
  44.     Ok, nuff chatter already.  At a CLI prompt (CITAS operates only from
  45.   CLI), type:
  46.  
  47.  
  48.       CITAS ILBM_file [result_file] [-c] [-m] [-x] [-s] [-o] [$nn] ["sfx"]
  49.  
  50.  
  51.     The parameters in brackets are optional and may be supplied in any
  52.   order with the exception of the result_file parameter which, if supplied,
  53.   must follow the ILBM file name.  All parameters are seperated by blanks.
  54.   Type "CITAS" without any parameters for a brief description of its use.
  55.  
  56.  
  57.     The parameters:
  58.  
  59.     result_file = The name of the output file.  This output file name,
  60.          minus any extension (.whatever), will be used in generating
  61.          the labels for your data.  This allows you to set up and
  62.          assemble your code before actually using CITAS to create the
  63.          data.  It also allows you to modify the data without touching
  64.          the linkable code.
  65.  
  66.          If no output file name is given, the input file name, minus
  67.          any extension, will be used for the labels, and will be the
  68.          name of the output file plus a ".asm" extension.  This default
  69.          file name will be placed in the current directory.
  70.  
  71.     -c = Inhibit generation of color table.  By default, CITAS will
  72.          include a color table in the output file.
  73.  
  74.     -m = Inhibit generation of image mask.  By default, CITAS will
  75.          include a mask plane in the output file.  This mask is
  76.          created by CITAS reguardless of whether or not the ILBM file
  77.          contains a mask, and is simply a logical OR of all bit planes.
  78.          It is meant to facilitate the use of the "cookie-cut" blitter
  79.          minterm, which requires an image mask (at least that's how
  80.          I use it).
  81.  
  82.     -x = Generate export definitions (XDEF) of labels for making 
  83.          linkable data.
  84.  
  85.     -s = Generate a "section" directive specifying chip RAM.  This
  86.          allows me to generate a hunk of data that will automatically
  87.          load into chip RAM.  Since the only assembler I am familiar
  88.          with on the Amiga is Devpac, I'm not sure if other assemblers
  89.          will appreciate this particular directive.
  90.  
  91.     -o = Allow an existing file to be overwritten by the output file.
  92.          By default, CITAS will abort with an error if the output
  93.          file already exists.  This is more or less a safety feature.
  94.  
  95.     $nn = User supplied hex mask of planes to extract.  This allows
  96.           selection of only the bit planes you want extracted.
  97.           Normally the resultant "planes" label will contain a mask
  98.           of all planes that are not null (all zero).  This may be
  99.           further modified by entering your own mask.  Bit numbers
  100.           correspond to plane numbers (ie bit 0 corresponds to
  101.           plane 0).  Note, however, that if a plane specified by
  102.           your mask is null, it will not be extracted.  Thus if you
  103.           entered a mask of $03, and plane 0 of the ILBM file was
  104.           all zeros, the resultant "planes" label would be $02.
  105.           Entering $ff will simply give you all non-zero planes.
  106.  
  107.     "sfx" = Any suffix needed to follow labels.  I realize that some
  108.             assemblers require a suffix on their labels, such as ":".
  109.             This is for those weirdo assemblers.
  110.  
  111.  
  112. SECTION 2, LABELS:
  113. -----------------
  114.  
  115.  
  116.     CITAS inserts several labels into the resultant assembler file.  Some
  117.   of these labels are equates (EQU) and others mark the start of different
  118.   data segments.  The first part of a label, as described earlier, is the
  119.   output file name.  The remainder of the label will be standard in every
  120.   CITAS created file, and starts with an underscore character.
  121.  
  122.  
  123.     The equates:
  124.  
  125.     _height    = The height of the image in scan lines
  126.     _width    = The width of the image in words
  127.     _depth    = The depth of the image in planes
  128.     _planes    = Mask of which bit planes are used to display the image
  129.           (so we don't have to waste memory with null planes, and
  130.            to specify how to display the image planes in a bitmap)
  131.  
  132.     The labels:
  133.  
  134.     _color    = The address of the 1st byte of the color table (if
  135.           generated)
  136.     _image    = The address of the 1st byte of the 1st generated
  137.           bit plane.
  138.     _mask    = The address of the 1st byte of the mask plane (if
  139.           generated)
  140.     _end    = The address of one byte past the last byte in the
  141.           generated file.  This is normally just past the
  142.           image mask, or just past the image data if no mask
  143.           is generated.
  144.  
  145.  
  146. SECTION 3, THE DREADED SHAREWARE NOTICE:
  147. ---------------------------------------
  148.  
  149.  
  150.     That's right, CITAS is copyright Max Bithead (a.k.a. John Enright), and
  151.   and is considered shareware.  It is not for sale, nor may it be included
  152.   in any commercial product without my written permission.  It is, however,
  153.   an excellent tool for CREATING commercial products.  Have at it!
  154.  
  155.     CITAS may be freely distributed as long as this document accompanies it.
  156.   Finally, I claim no responsibility for any loss or penalty incurred by the
  157.   use of this program.
  158.  
  159.     Whew!  Ok, paranoia aside, I hope that you find this program useful
  160.   in developing great Amiga software.  I know it works wonders for me.
  161.   Graph paper was absolutely out of the question!  ha ha.  There are no
  162.   known bugs, and I haven't been able to crash my system under any
  163.   circumstances by using it.  It will not blow out a disk should it become
  164.   become full (including the RAM: disk), etc., CITAS simply aborts with an
  165.   error.  I believe CITAS covers all possible errors, but time will tell.
  166.  
  167.     I'm asking a measly $10 for CITAS if you intend to use it.  The cheapest
  168.   development software you'll ever buy.  Send any comments/suggestions/bug
  169.   reports, and oh yea, payment (if you like it) to me at:
  170.  
  171.         John Enright
  172.         2955 Glenwood Dr. #301
  173.         Boulder, Colorado, 80301  (USA)
  174.         (303) 938-9490
  175.  
  176.     You may also send electronic mail to Max Bithead on any of these great
  177.   BBS's:
  178.  
  179.     Reggae Land  (303) 699-2671
  180.     CD Players   (303) 825-0419
  181.     Arvada 68K   (303) 424-9831
  182.     BAUG         (303) 494-4470
  183.  
  184.  
  185.                       -------------- * * --------------
  186.                                       "
  187.                                      \_/
  188.  
  189.  
  190.   A special howdy to all friends from Mankato State University, in Minnesota!
  191.  
  192.  
  193.