     ______   ___    ___
    /\  _  \ /\_ \  /\_ \
    \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___
     \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
      \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
       \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
        \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
                                       /\____/
                                       \_/__/     Versin 3.0


      Una biblioteca de programacin de juegos para el djgpp

      Por Shawn Hargreaves, 1994/97
      Traduccin Grzegorz Adam Hankiewicz (gregorio@jet.es)
      y Ernesto Domato, 1997



#include <std_disclaimer.h>

   "No me hago responsable por ningn efecto, adverso u otro, que este
    cdigo pueda tener en usted, su computadora, su cordura, su perro,
    o cualquier otra cosa que pueda pensar. Uselo bajo su propio riesgo."



======================================
============ Introduccin ============
======================================

   Allegro es una biblioteca de funciones para usar en videojuegos, escrita
   para el compilador djgpp en una mezcla de lenguaje C y ensamblador. Esto
   es la versin 3.0: lee el fichero NEWS para obtener una lista de
   diferencias sobre versiones previas.

   Segn el suplemento de Msica del diccionario Oxford, Allegro es la
   palabra italiana para "rpido, vivo, brillante". Hace mucho tiempo
   tambin fue el acrnimo de "Atari Low Level Game Routines", pero hace
   mucho que no he programado en un Atari, y el nombre es lo nico que queda
   del cdigo original.



=========================================
============ Caractersticas ============
=========================================

   Soporta el modo 13h de la VGA, modo-X (veintids resoluciones VGA
   trucadas ms el modo lineal 640x400 Xtended), y modos SVGA de 8, 15, 16,
   24, y 32 bits de profundidad. Usa framebufers lineales VESA 2.0 si estn
   presentes, y tambin contiene drivers a nivel de registros para las
   tarjetas de vdeo ATI, Cirrus, Paradise, S3, Trident, Tseng, y Video-7.

   Las funciones de dibujo incluyen putpixel, getpixel, lneas, rectngulos,
   polgonos con sombreado flat, goraud o texturizado, crculos, relleno de
   reas, curvas bezier, rellenos de reas con patrn, dibujado de sprites
   con mscara, codificados con RLE o compilados, copia de reas de memoria,
   escalado y rotacin de bitmaps, efectos de traslucencia/iluminacin, y
   salida de texto con fuentes proporcionales. Soporta clipping, y puede
   dibujar directamente en la pantalla o en bitmaps de memoria de cualquier
   tamao.

   Scroll por hardware, pantallas partidas del modo-X y manipulacin de
   paletas de color.

   Reproductor de animaciones FLI/FLC.

   Reproduce msica MIDI de fondo y hasta 32 efectos de sonido simultneos.
   Los samples pueden ser repetidos (hacia delante, atrs o
   bidireccionalmente), y el volumen, la panoramizacin, la frecuencia, etc,
   de stos puede ser reajustada mientras se reproducen. El reproductor MIDI
   responde a note on, note off, volumen principal, panoramizacin,
   modificacin de frecuencia, y mensajes de cambio de programa usando el
   conjunto de instrumentos y tambores General MIDI. Actualmente soporta
   Adlib, SB, SB Pro, SB16, AWE32, MPU-401 y emulacin de wavetable MIDI por
   software.

   Fcil acceso al ratn, teclado, joystick y temporizadores de alta
   resolucin, incluyendo una interrupcin que simula el retrazo vertical.

   Rutinas para leer y escribir ficheros con compresin LZSS.

   Ficheros de datos multi-objeto y la utilidad grabber.

   Funciones matemticas incluyendo aritmtica de punto fijo, tabla
   precalculada trigonomtrica y manipulacin de vectores/matrices 3d.

   Mnager de dilogos GUI y selector de ficheros.



===================================
============ Copyright ============
===================================

   Allegro es swap-ware. Puedes usarlo, modificarlo, redistribuirlo y en
   general hackearlo como desees, pero si lo haces debes mandarme algo a
   cambio. Esto podra ser una copia de tu juego, una mejora de Allegro,
   encontrar un fallo de Allegro, algo de dinero (esto es lo ideal si usas
   Allegro en un producto comercial), o simplemente una copia de tu
   autoexec.bat si no tienes nada mejor. Si redistribuyes partes de Allegro
   o haces un juego utilizndolo, sera bueno que me mencionases en alguna
   parte de los crditos, pero si simplemente necesitabas un par de rutinas,
   eso tambin est bien. Confiar en que no abuses de mi.



============================================
============ Hardware soportado ============
============================================

   Lo mnimo que necesitas para usar Allegro es un 386 con una tarjeta de
   vdeo VGA, pero un 486 es fuertemente recomendado. Para alcanzar los
   modos SVGA necesitars una tarjeta compatible SVGA, es decir, una tarjeta
   de vdeo que est soportada directamente, o cualquiera que funcione con
   un driver VESA. Si tienes una implementacin VESA 2.0 como UniVBE (que
   puedes conseguir del enlace Display Doctor en
   http://www.scitechsoft.com/), todo ir bien. Si no, ten cuidado. Por un
   lado, todo ir ms lento si no puedes usar las caractersticas VBE 2.0.
   Por otro lado, podra pasarme todo el da contndote historias de terror
   sobre implementaciones VESA errneas o patticas que me he encontrado. Si
   tienes problemas con los modos SVGA, prueba una copia de UniVBE y mira si
   eso los soluciona (normalmente lo hace: SciTech suele solucionar estas
   cosas).

   En la parte de sonido, Allegro soporta la reproduccin de samples en la
   SB (mono), SB Pro (estreo) y SB16. Tiene drivers MIDI para el
   sintetizador FM OPL2 (tarjetas Adlib y SB), OPL3 (Adlib Gold, SB Pro-II y
   superiores), el par de chips OPL2 de la SB Pro-I, el chip EMU8000 de la
   AWE32, la salida MIDI SB pura, y el interfaz MPU-401, y adems puede
   emular un sintetizador MIDI wavetable por software, corriendo sobre
   cualquiera de las tarjetas digitales soportadas. Si tienes ganas de
   aportar ms drivers para otro hardware, sern bienvenidos.

   Te dars cuenta que esta versin tiene algo de cdigo para crear una
   versin Linux, pero no te molestes en probarla: no funcionar! Falta
   _mucho_ ms trabajo antes de que Allegro funcione bajo Linux.

   Tambin se incluye una primera parte del driver VBE/AF en este pack.
   VBE/AF es una extensin del API VBE 2.0 que provee un acceso estndar a
   las posibilidades de aceleracin por hardware. Mi driver implementa todas
   las funciones bsicas para activar el modo y cambiar de bancos, por lo
   que funciona igual que un driver VESA regular, pero todava no hay
   soporte para operaciones de dibujo aceleradas. Esto es porque, por ahora,
   SciTech slo las han implementado en la ATI Mach64, y no tengo acceso a
   una Mach64. Acabar el driver tan pronto como implementen VBE/AF en la
   Matrox Mystique.



============================================
============ Instalando Allegro ============
============================================

   Para conservar espacio, decid hacer una distribucin de cdigo fuente,
   por lo que tendrs que compilar Allegro antes de usarlo. Para hacerlo,
   deberas:

   - Ir a donde desees poner tu copia de Allegro (tu directorio djgpp sera
     una buena opcin, pero puedes ponerlo en otro lado si prefieres), y
     descomprime todo. Allegro contiene varios subdirectorio, por lo que
     tienes que especificar el parmetro -d si usas pkunzip.

   - Si ests usando PGCC, activa la definicin de PGCC en la parte superior
     del fichero makefile, o activa la variable de entorno "PGCC=1".

   - Teclea "cd allegro", seguido por "make". Entonces haz algo interesante
     mientras todo se compila. Si todo va segn el plan, acabars con un par
     de programas de test, algunas herramientas como el grabber, y la
     librera, liballeg.a.

     Si tienes algn problema con la compilacin, mira en faq.txt para leer
     soluciones a los problemas ms comunes.

   - Si quieres usar las rutinas de sonido o un teclado que no sea el
     americano, sera buena idea crear un fichero allegro.cfg: mira ms
     abajo.

   - Si quieres leer la documentacin de Allegro con el visor Info o el
     sistema de ayuda online de Rhide, edita el fichero djgpp\info\dir, y en
     la seccin de men aade las lneas:

	 * SPAllegro: (spallegr.inf).
       Documentacin espaola de Allegro

   - Si quieres crear la documentacin HTML como un largo fichero
     allegro.html en vez de separarlo en secciones, edita src\ernesto._tx, y
     elimina el comando @multiplefiles de la lnea 8, y ejecuta make otra
     vez.

   Para usar Allegro en tu programa deberas:

   - Poner la siguiente lnea al comienzo de todos tus ficheros C o C++ que
     usen Allegro:

	 #include <allegro.h>

   - Si compilas de la lnea de comando o con un makefile, aade '-lalleg'
     al final del comando gcc, ejemplo:

	 gcc foo.c -o foo.exe -lalleg

   - Si ests usando Rhide, ve al men Options/Libraries, teclea 'alleg' en
     el primer espacio vaco, y asegrate de que la caja de al lado est
     activada.

   Mira allegro.txt para ms detalles sobre cmo usar las funciones de
   Allegro y sobre cmo compilar una versin para depurar de la librera.



=======================================
============ Configuracin ============
=======================================

Cuando Allegro inicializa las rutinas de teclado y sonido, lee informacin
sobre tu hardware desde un fichero llamado allegro.cfg o sound.cfg. Si estos
ficheros no existen, autodetectar el hardware (supongo :-) Puedes escribir
tu fichero de configuracin a mano con un editor de textos, o puedes usar la
utilidad setup.

Normalmente setup.exe y allegro.cfg irn en el mismo directorio que el
programa Allegro que controlan. Esto est bien para el usuario, pero puede
ser un dolor para el programador de Allegro porque podras tener diferentes
programas en diferentes directorios y querrs usar un solo allegro.cfg para
todos ellos. Si este es el caso, puedes hacer que la variable de entorno
ALLEGRO apunte al directorio que contiene tu allegro.cfg, y Allegro mirar
ah si no hay un fichero allegro.cfg en el directorio actual.

Las tablas usadas para almacenar diferentes mapas de teclados son
almacenadas en un fichero llamado keyboard.dat. Esto debe estar en el mismo
directorio que tu programa de Allegro, o en el directorio apuntado por la
variable ALLEGRO. Si quieres soporte para diferentes mapas de teclado
internacionales, debes distribuir una copia de keyboard.dat junto con tu
programa.

Mira allegro.txt para detalles sobre el formato del fichero de
configuracin.



==============================================
============ Notas pare el msico ============
==============================================

El chip sinttico OPL2 puede manejar nueve voces en polifona o seis voces
ms 5 canales de tambores. El cmo hacer que la msica suene bien en un OPL2
se deja como ejercicio al lector :-) En una SB Pro o superior, tendrs
dieciocho voces, o quince ms tambores. Allegro decide si usar el modo con
tambores individualmente para cada fichero MIDI, basndose en si ste
contiene tambores o no. Si tienes una pieza orquestral con el tpico
platillo, sera buena idea quitarlo para que Allegro use el modo sin
tambores para darte tres notas extra de polifona.

Cuando Allegro est reproduciendo un fichero MIDI en modo loop, salta al
comienzo del fichero cuando llega al final. Para controlar exactamente el
punto de loop, necesitars insertar una marca de evento como un mensaje de
control en un canal que no usas.

Todos los chips OPL tienen una capacidad estreo muy limitada. En un OPL2,
todo es reproducido en mono. En la SB Pro-I, los sonidos slo pueden
panoramizarse totalmente a la izquierda o a la derecha. Con el chip OPL3 de
la SB Pro-II y superiores, el sonido puede panoramizarse a la izquierda,
derecha o centro. Podra usar dos voces por nota para proveer una
panoramizacin ms flexible, pero eso reducira la polifona y no deseo
hacer eso. Por lo que no intentes mover el sonido en estreo con mensajes de
control de panoramizacin, porque darn unos saltos horribles. Tambin
merece la pena considerar la panoramizacin cada canal para que la msica
suene bien en tarjetas SB Pro-I y OPL3. Si quieres un sonido panoramizado a
la izquierda o derecha, usa un valor de pan menor de 48 o mayor de 80. Si lo
quieres centrado, usa un valor de pan entre 48 y 80, pero ponlo ligeramente
en un lado del centro 64, para controlar qu altavoz ser usado si la
panoramizacin central no es posible.

El driver wavetable DIGMID usa ficheros .pat con formato estndar GUS, y
necesitars una coleccin estos instrumentos antes de usarlos. Esta puede
estar en el formato estndar GUS (un ser de ficheros .pat y un ndice
default.cfg), o un fichero patches.dat creado con la utilidad pat2dat.
Tambin puedes usar pat2dat para convertir bancos SoundFont de la AWE32 en
el formato de patches.dat, y si indicas algunos ficheros MIDI en la lnea de
comando, filtrar el conjunto de instrumentos para incluir slo aquellos que
son usados por las canciones, por lo que puede resultar til para deshacerte
de instrumentos innecesarios cuando vas a distribuir un juego. Mira en la
pgina web de Allegro para encontrar links a conjuntos de instrumentos.

El driver DIGMID normalmente carga slo los patches necesarios para cada
cancin cuando la reproduces por primera vez. Esto reduce el uso de memoria,
pero puede resultar en un retraso cuando vayas a reproducir cada fichero
MIDI. Si prefieres cargar el conjunto de instrumentos entero de una sola
vez, llama la funcin load_midi_patches().

El cdigo de mezcla por CPU puede soportar entre 1 y 32 voces, en
incrementos de potencia de dos (es decir: 1, 2, 4, 8, 16, o 32 canales). Por
defecto provee 8 voces digitales, u 8 digitales ms 24 voces MIDI (un total
de 32) si el driver DIGMID est siendo usado. Pero cuantas ms voces, peor
ser el volumen y la calidad del sonido, por lo que querrs cambiar esto
llamando la funcin reserve_voices() o ajustando los parmetros digi_voices
y midi_voices en allegro.cfg.



=================================================
============ Informacin de contacto ============
=================================================

   WWW:                 http://www.talula.demon.co.uk/allegro/

   Lista de email:      allegro@canvaslink.com. Para aadirte a la lista,
                        escribe a listserv@canvaslink.com con el texto
                        "subscribe allegro tunombre" o "unsubscribe allegro"
                        en el cuerpo de tu mensaje.

   Usenet:              Prueba el grupo de noticias, comp.os.msdos.djgpp

   IRC:                 Canal #allegro en EFnet

   Mi email:            shawn@talula.demon.co.uk (escribe en ingls!)

   Por carta:           Shawn Hargreaves, (escribe en ingls!)
               			1 Salisbury Road,
               			Market Drayton,
               			Shropshire,
               			England, TF9 1AJ.

   Telfono:            UK 01630 654346

   A pi:               Viniendo por la calle de Shrewsbury desde el centro
                        de la ciudad, gira en la calle de Salisbury y es la
                        primera casa de la izquierda.

   Si todo falla:       52 deg 54' N
                        2 deg 29' W

   Siempre puedes conseguir la ltima versin de Allegro desde la pgina web
   de Allegro, http://www.talula.demon.co.uk/allegro/.
