@html_text_substitution=readme.txt|<a href="../readme.html">readme.txt</a>
@html_text_substitution=docs/txt/faq.txt|<a href="../faq.html">docs/txt/faq.txt</a>
@external-css=../allegro.css
@document_title=Allegro DJGPP-specific information
@<pre>
     ______   ___    ___
    /\  _  \ /\_ \  /\_ \
    \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___ 
     \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
      \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
       \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
	\/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
				       /\____/
				       \_/__/


		DJGPP-specific information.

	 See readme.txt for a more general overview.
@</pre>



@heading
djgpp notes

   Status: complete. This is the original Allegro version, and has had 
   plenty of time to become nice and stable. However, under Windows NT,
   2000, or XP you will very likely experience problems and should consider
   using the native Windows version of Allegro instead, less likely to give
   you problems under such environments.



@heading
Required software

   <ul><li>DJGPP 2.01 or later (<tt>djdev*.zip</tt>).
   <li>GCC compiler 2.91.x or later (<tt>gcc*b.zip</tt>).
      Note: gcc 3.0.x (0 &lt;= x &lt;= 1) doesn't properly compile Allegro.
   <li>Binutils 2.9.x or later (<tt>bnu*b.zip</tt>).
   <li>GNU make (<tt>mak*b.zip</tt>).
   <li>Texinfo (<tt>txi*b.zip</tt>).
   <li>Optional: sed (<tt>sed*b.zip</tt>). Used by "<tt>make depend</tt>".
</ul>
   All of the above can be downloaded from your nearest SimTel mirror site, 
   in the <tt>/pub/simtelnet/gnu/djgpp/</tt> directory, or you can use the zip picker
   on <link>http://www.delorie.com/djgpp/</a>. Please make sure that you have
   installed djgpp according to the instructions in <tt>readme.1st</tt>, and that you
   aren't mixing it with any files from different compilers (eg. the Borland 
   version of make).
   


@heading
Allegro SVN Notes

   If you are using a SVN version of Allegro, then you will need to do some
   extra things to ensure that your copy of Allegro will compile correctly.
   These are covered in detail below, but briefly:
<blockquote>
   1. You must run the `<tt>fix</tt>' script (either the batch file, under
      command.com, or the .sh file under bash). You must supply the
      argument `<tt>djgpp</tt>'.

   2. You must regenerate the dependency files: a simple `<tt>make depend</tt>'
      will do this. However, please note that you must have sed installed
      to do this.
</blockquote>


@heading
Installing Allegro

   This is a source-only distribution, so you will have to compile Allegro 
   before you can use it. To do this you should:

   Go to wherever you want to put your copy of Allegro (your main djgpp 
   directory would be fine, but you can put it somewhere else if you 
   prefer), and unzip everything. Allegro contains several subdirectories, 
   so you must specify the <tt>-d</tt> flag if you are using pkunzip.

   If you are running under Linux, and want to cross-compile the djgpp 
   version of Allegro, set the environment variable "<tt>CROSSCOMPILE=1</tt>", set 
   <tt>DJDIR</tt> to the directory where your djgpp cross-compiler is installed,
   set <tt>PATH</tt> to access to the cross-compiler, and set <tt>NATIVEPATH</tt> to a path
   that will use your native version of gcc instead (_not_ the djgpp 
   cross-compiler!) so that this can be invoked when converting the 
   documentation. You might like to edit and use `<tt>xmake.sh</tt>'; there are
   further instructions in comments in the file. You must also run
   '<tt>fix.sh djgpp</tt>' as detailed above - it is required to properly configure
   Allegro for building with djgpp.

   Type "<tt>cd allegro</tt>", followed by "<tt>make</tt>". Then go do something interesting 
   while everything compiles. When it finishes compiling, type "<tt>make 
   install</tt>" to set the library up ready for use. If you have any trouble 
   with the build, look at <tt>docs/txt/faq.txt</tt> for the solutions to some of the
   more common problems.

   If you also want to install a debugging version of the library (highly 
   recommended), now type "<tt>make install DEBUGMODE=1</tt>". Case is important, so 
   it must be <tt>DEBUGMODE</tt>, not <tt>debugmode</tt>!

   If you also want to install a profiling version of the library, now type 
   "<tt>make install PROFILEMODE=1</tt>".

   If you want to read the Allegro documentation with the Rhide online help 
   system, go to the "<tt>Help / Syntax help / Files to search</tt>" menu, and add 
   "<tt>allegro</tt>" after the existing "<tt>libc</tt>" entry (separated by a space).

   If you want to create the HTML documentation as one large allegro.html 
   file rather than splitting it into sections, edit <tt>docs/allegro._tx</tt>,
   remove the @multiplefiles statement from line 8, and run make again.

   Once the build is finished you can recover some disk space by running 
   "<tt>make compress</tt>" (which uses the DJP or UPX programs to compress the 
   executable files), and/or "<tt>make clean</tt>" (to get rid of all the temporary 
   files and HTML format documentation).

   If your copy of Allegro is set up for use with some different compiler 
   (if you downloaded a tar.gz archive or a SVN version), you will have to 
   run '<tt>fix.bat djgpp</tt>' before compiling it. If you are using bash you can run
   '<tt>fix.sh djgpp</tt>' instead.

   If your copy of Allegro doesn't include the makefile.dep dependency files 
   (if you have run "<tt>make veryclean</tt>" or you have the SVN version), you can 
   regenerate them by running "<tt>make depend</tt>".

   If `<tt>make</tt>' tells you that you need to download a new package, or if you
   need the `<tt>sed</tt>' package to generate dependencies, you can find these at
   <link>ftp://ftp.demon.co.uk/pub/mirrors/simtelnet/gnu/djgpp/</a>.
 
   A list of all the available options:
<blockquote><dl>
      <dt><tt>CROSSCOMPILE</tt></dt><dd>
	 Set this if you are crosscompiling; it implies <tt>UNIX_TOOLS</tt>.</dd>

      <dt><tt>WARNMODE</tt></dt><dd>
	 Set this if you want Allegro to display and stop on nearly all
	 warnings issued by the compiler. Allegro should compile fine with
	 this set.</dd>

      <dt><tt>TARGET_ARCH_COMPAT</tt>
	 or
      <tt>TARGET_ARCH_EXCL</tt></dt><dd>
	 These affect the level of processor dependant optimisation that
	 Allegro uses. You can set either of these to the processor type you
	 want to optimize for. The difference between these two is that
	 <tt>TARGET_ARCH_COMPAT</tt> optimise for the given processor so that the code
	 will still run on older processors, while <tt>TARGET_ARCH_EXCL</tt> will
	 generate code that will run exclusively on the given processor and of
	 course newer ones. Example: set <tt>TARGET_ARCH_COMPAT=i686</tt></dd>

      <dt><tt>TARGET_OPTS</tt></dt><dd>
	 Affects the general optimisations that Allegro uses.</dd>

      <dt><tt>UNIX_TOOLS</tt></dt><dd>
	 If your system does not have the usual DOS tools available (`<tt>md</tt>',
	 `<tt>rd</tt>', `<tt>copy</tt>', etc., and commands which understand the <tt>\</tt> character),
	 then set this to 1 to use the Unix equivalents. This is set
	 implicitly when you set <tt>CROSSCOMPILE</tt>, and is also set automatically
	 when you are running under bash.</dd>
</dl></blockquote>
   To activate any of these, type (for example) "<tt>make WARNMODE=1</tt>".



@heading
Using Allegro

   All the Allegro functions, variables, and data structures are defined in 
   <tt>allegro.h</tt>. You should include this in your programs, and link with either
   the optimised library <tt>liballeg.a</tt>, the debugging library <tt>liballd.a</tt>, or the
   profiling library <tt>liballp.a</tt>. To do this you should:

   Put the following line at the beginning of all C or C++ files that use 
   Allegro:
<codeblock>
      #include &ltallegro.h&gt
<endblock>
   If you compile from the command line or with a makefile, add either 
   '<tt>-lalleg</tt>' (for the optimised version), '<tt>-lalld</tt>' (debugging version), or
   '<tt>-lallp</tt>' (profiling version) to the end of the gcc command, eg:
<textblock>
      gcc foo.c -o foo.exe -lalleg
<endblock>
   If you are using Rhide, go to the Options/Libraries menu, type either 
   '<tt>alleg</tt>' (for the optimised version), '<tt>alld</tt>' (debugging version), or
   '<tt>allp</tt>' (profiling version) into the first empty space, and make sure the
   box next to it is checked.



@heading
Supported hardware

   The bare minimum you need to use Allegro is a 386 with a VGA graphics 
   card, but a 486 is strongly recommended. To get into SVGA modes you will 
   need a compatible SVGA card, which means something that has a working 
   VESA or VBE/AF driver.

   Ideally you should use VBE/AF, because it allows Allegro to use hardware 
   acceleration functions to speed up the drawing. The FreeBE/AF project 
   (<link>http://www.talula.demon.co.uk/freebe/</a>) provides a number of free VBE/AF
   drivers (volunteers to write more are always welcome!), and accelerated 
   drivers for a large number of cards are available commercially as part of 
   the SciTech Display Doctor package (<link>http://www.scitechsoft.com/</a>).

   If you have a VBE 2.0 or VBE 3.0 driver you are probably fine just using 
   that, although unlike VBE/AF it won't provide any hardware acceleration. 
   If you have an older VESA BIOS implementation (eg. VESA 1.2), beware. For 
   one thing, everything will be much slower if Allegro can't use the sexy 
   VBE 2.0 features. For another, I could go on all day telling horror 
   stories about the buggy and generally just pathetic VESA implementations 
   that I've come across. If you are having trouble with the SVGA modes, try 
   getting a copy of the SciTech Display Doctor and see if that clears 
   things up (it probably will: SciTech usually get these things right).

   Note that the native SVGA chipset drivers from Allegro 3.0 and earlier 
   have been removed. These are still available as an optional add-on 
   package from the same sites as Allegro, but are not needed any more 
   because you can get the same code in a more flexible format as part of 
   the FreeBE/AF project.

   On the sound front, Allegro supports sample playback on the SB (mono), 
   the SB Pro (stereo), the SB16, the ESS AudioDrive, the Ensoniq 
   Soundscape, and the Windows Sound System. It has MIDI drivers for the 
   OPL2 FM synth (Adlib and SB cards), the OPL3 (Adlib Gold, SB Pro-II and 
   above), the pair of OPL2 chips found in the SB Pro-I, the AWE32 EMU8000 
   chip, the raw SB MIDI output, and the MPU-401 interface, plus it can 
   emulate a wavetable MIDI synth in software, running on top of any of the 
   supported digital soundcards. The Creative Labs SB PCI-64 and PCI-128 
   cards are actually based on the Ensoniq chipset, so they can be used with 
   the Soundscape and MPU-401 drivers. You'll have to manually select the 
   MPU, though, because it won't be autodetected. Actually, quite a lot of 
   wavetable boards emulate the MPU, so give this a try and see if it works 
   on your card. If you feel like coming up with drivers for any other 
   hardware, they would be much appreciated.

   Audio recording is supported for all SB cards, but only in unidirectional 
   mode, ie. you cannot simultaneously record and playback samples. MIDI 
   input is provided by the MPU-401 and SB MIDI drivers, but there are some 
   restrictions on this. The SB MIDI interface cannot be used at the same
   time as the digital sound system, and the MPU will only work when there 
   is an IRQ free for it to use (this will be true if you have an SB16 or 
   greater, or if no SB-type digital driver is installed, or if your MIDI 
   interface uses a different IRQ to the SB).



@heading
Notes for the musician

   The OPL2 synth chip can provide either nine voice polyphony or six voices 
   plus five drum channels. How to make music sound good on the OPL2 is left 
   as an exercise for the reader :-) On an SB Pro or above you will have 
   eighteen voices, or fifteen plus drums. Allegro decides whether to use 
   drum mode individually for each MIDI file you play, based on whether it 
   contains any drum sounds or not. If you have an orchestral piece with 
   just the odd cymbal crash, you might be better removing the drums 
   altogether as that will let Allegro use the non-drum mode and give you an 
   extra three notes polyphony.

   When Allegro is playing a MIDI file in looped mode, it jumps back to the 
   start of the file when it reaches the end of the piece. To control the 
   exact loop point, you may need to insert a dummy marker event such as a 
   controller message on an unused channel.

   All the OPL chips have very limited stereo capabilities. On an OPL2, 
   everything is of course played in mono. On the SB Pro-I, sounds can only 
   be panned hard left or right. With the OPL3 chip in the SB Pro-II and 
   above, they can be panned left, right, or centre. I could use two voices 
   per note to provide more flexible panning, but that would reduce the 
   available polyphony and I don't want to do that. So don't try to move 
   sounds around the stereo image with streams of pan controller messages, 
   because they will jerk horribly. It is also worth thinking out the 
   panning of each channel so that the music will sound ok on both SB Pro-I 
   and OPL3 cards. If you want a sound panned left or right, use a pan value 
   less than 48 or greater than 80. If you want it centred, use a pan value 
   between 48 and 80, but put it slightly to one side of the exactly central 
   64 to control which speaker will be used if the central panning isn't 
   possible.

