         ______      ____     ______
        /\  _  \    /  __ \  /\  ___\
        \ \ \L\ \  /\  \ \_\ \ \ \__/
         \ \  __ \ \ \  \/_L_ \ \  _\
          \ \ \/\ \ \ \  \_\ \ \ \ \/___
           \ \_\ \_\ \ \_____/  \ \_____\
            \/_/\/_/  \_____/    \/_____/   Version 0.1 beta

                 (Allegro Con Eiffel)

                       By Peter Monks, 1997


#include <std_disclaimer.h>

   "I do not accept responsibility for any effects, adverse or otherwise, 
    that this code may have on you, your computer, your sanity, your dog, 
    and anything else that you can think of. Use it at your own risk."


======================================
============ What is ACE? ============
======================================

ACE (Allegro Con Eiffel) is a port of the excellent Allegro game programming
library to the SmallEiffel Eiffel compiler.  Both of these products are
currently available for free from various sites on the Web (see problems.txt
for details).

ACE is not a true port, in that it doesn't replace any code in Allegro, it
merely "packages" it into a form usable from Eiffel.  I've also placed an
object structure on top of Allegro's procedural structure, to help support
the concept of Design by Contract etc. (see design.txt for more detail).


================================================
============ What Does ACE Include? ============
================================================

ACE currently includes:

* Information operations (Allegro version etc.)

* Most 2D graphics operations (blits, lines, triangles, rectangles, clipping
  etc.)

* Most 8 bit colour functionality (setting and getting of hardware palettes,
  retrieval of individual colours etc.)

* Most timer functionality

* All mouse functionality

* All keyboard functionality

* All joystick functionality

* Some FLIC functionality

* All font functionality

* All sample functionality

* All midi functionality

* All compressed file functionality (but currently difficult to use!)

* Datafile operations on standard object types (bitmaps, RLE sprites,
  compiled sprites, palettes, fonts, samples, midi sequences)

* All fixed point math functionality


===================================================
============ What Doesn't ACE Include? ============
===================================================

ACE does not yet include:

* Polygon drawing functionality

* Custom timer interrupt handlers

* 15, 16, 24 or 32 bit colour functionality

* GUI functionality

* 3D functionality

* Matrix math functionality

* Looped MIDI sequences

* Looped samples

* FLIC callbacks, detailed FLIC control or looped FLICs

* Custom datafile object types


===================================
============ Using ACE ============
===================================

The best documentation for ACE will always be the short form of the classes
you wish to use in your program.  Since SmallEiffel doesn't yet provide the
short tool as part of the standard distribution, you'll have to wade through
the code for each class to see what operations are supported.

I've tried to remain faithful to the original Allegro API, but have taken
the liberty of changing some function names where I didn't think they were
clear (sorry, Shawn!).

Hopefully this document will contain a description of all classes and their
features if I ever get around to finishing it!!  :-)


================================================
============ Compiling ACE Programs ============
================================================

1. Ensure you've installed ACE correctly (refer to install.txt).

2. Copy LIBACE.A, ACE.H and the modified ALLEGRO.H to the directory in which
   your source is stored.  This is so that the linker (ld) can find the
   supporting C code for ACE.  Alternatively, you could copy LIBACE.A to the
   LIB directory, and ACE.H and ALLEGRO.H to the INCLUDE directory of your
   DJGPP installation.  Note that this may clash with other C libraries.

3. Compile your program using the SmallEiffel "compile" command.  You will
   need to include at least the following command-line options (in the order
   shown):

   -D SMALLEIFFEL        #define the SMALLEIFFEL symbol so that the C source
                         knows we're compiling an Eiffel program

   -include ace.h        #include the ace.h file, which prototypes all of the
                         support routines

   -lace                 instruct the linker to link in the support routines

   -include allegro.h    #include the allegro.h file, which prototypes all of
                         the Allegro routines

   -lalleg               instruct the linker to link in the Allegro routines

   In addition, you will probably find that the following option is also
   required:

   -no_split             instruct SmallEiffel to only create a single file
                         to contain the C source form of your project,
                         otherwise the command line to gcc can easily become
                         longer than 127 characters, and cause errors during
                         C compilation

   For full assertion checking, use the following option:

   -debug_check          instruct SmallEiffel to turn on all assertion
                         checking

   For a fully optimised version of your program, include the following
   options (note that no assertion checking will be done with these options
   in effect):

   -boost                instruct SmallEiffel to optimise to the hilt

   -m486                 instruct DJGPP to produce code optimised for 486s
                         and up - will still work on 386s, however

   -O3                   instruct DJGPP to optimise to level 3

   -ffast-math           instruct DJGPP to violate some IEEE/ANSI floating
                         point rules in the interest of speed

   -fomit-frame-pointer  instruct DJGPP to omit a frame pointer, freeing up
                         an additional CPU register for program variables

   If you are compiling a program that uses a callback from C (currently
   only if you are using class FILE_ITERATOR), you'll also need to create
   a cecil file and add the following command line option:

   -cecil filename.se    instruct SmallEiffel to produce a callback stub
                         according to the information provided in the
                         specified file

   For more information on cecil and callbacks, see the FILE_TEST example in
   the TESTS directory, look up the cecil help and examples included with the
   SmallEiffel package, or peruse chapter 24 of Eiffel The Language.

4. It is obviously much easier to create a batch file to supply these options
   than to type them in each time you need to compile.  Place this batch file
   in the BIN directory of the SmallEiffel installation.


=======================================
============ Contacting Me ============
=======================================

If you have any problems, comments, grievances etc. about ACE I want to
hear about them!!  At least then I'll know that this little project was
worth the time I spent on it.

Since I move around a bit, e-mail is the only reliable way to get in
contact with me.  My address is pmonks@iname.com.

Happy Eiffeling!
