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


      Una biblioteca de funciones para programar videojuegos

         Por Shawn Hargreaves, 1994/98
         Traduccin Grzegorz Adam Hankiewicz.

      Lea en el fichero AUTHORS un listado
      completo de los que han contribudo a Allegro.


#include <std_disclaimer.h>

   "No me responsabilizo de ningn efecto, negativo, positivo u otro que
    este cdigo pueda tener sobre usted, su ordenador, su salud, su perro, o
    cualquier otra cosa que pueda imaginar. Uselo bajo su propio
    responsabilidad."



======================================
============ 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 original DOS para el compilador djgpp, pero tambin hay
   versiones para win32 usando DirectX, y para X-Windows: lea ms en
   http://www.talula.demon.co.uk/allegro/ sobre estas versiones. Una gran
   gama de paquetes de extensin y mdulos add-on estn disponibles, y
   pueden ser encontrados en la seccin "Library Extensions" de la pgina
   web de Allegro.

   Esto es una versin beta que hojal se convertir pronto en la versin
   3.1. Lea el fichero NEWS para ver las diferencias respecto a la versin
   anterior.

   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 (veintitres resoluciones VGA
   trucadas ms el modo lineal 640x400 Xtended), y modos SVGA de 8, 15, 16,
   24, y 32 bits de profundida, usando las ventajas de los framebuffers
   lineales VBE 2.0 y el API de aceleracin por hardware VBE/AF si estn
   disponibles. El soporte de hardware de vdeo adicional est disponible
   con el projecto FreeBE/AF (http://www.talula.demon.co.uk/freebe/).

   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 reas de recorte, 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 64 efectos de sonido simultneos y
   puede grabar ondas de sonido o entrada MIDI. 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, ESS AudioDrive y emulacin de tabla de ondas 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 ============
===================================

   Nota: los trminos de licencia han sido modificados recientemente! Lea
   en la pgina de Allegro una explicacin de por qu se necesitaba una
   nueva licencia.

   Allegro es gift-ware (software-regalo). Fue creado por un nmero de
   personas trabajando en cooperacin, y se le da a usted libremente como
   regalo. Puede usar, modificar, redistribuir, y generalmente modificarlo
   de cualquier forma que desee, y no debe darnos nada a cambio. Sin
   embargo, si le gusta este producto, le animamos a que nos lo agradezca
   haciendo un regalo a la comunidad de Allegro. Esto puede ser escribir un
   pack adicional para Allegro, contribuir con un mensaje de error (bug)
   til, hacer mejoras en la biblioteca, o quizs simplemente distribuir
   libremente el cdigo de su programa para que otras personas puedan
   aprender de l. Si redistribuye partes de este cdigo o hace un juego con
   l, sera bonito que mencionase Allegro en alguna parte de los crditos,
   pero no est obligado a hacerlo. Confiamos en que no abuse de nuestra
   generosidad.



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

   Lo mnimo que necesita para usar Allegro es un 386 con una tarjeta de
   vdeo VGA, pero un 486 es muy recomendado. Para alcanzar los modos SVGA
   necesitar una tarjeta compatible SVGA, es decir, una tarjeta que
   funcione con un controlador VESA o VBE/AF.

   Idealmente debera usar VBE/AF, ya que permite a Allegro usar las
   funciones de aceleracin por hardware para dibuajar. El proyecto
   FreeBE/AF (http://www.talula.demon.co.uk/freebe/) da un nmero de
   controladores VBE/AF gratis (los voluntarios siempre pueden hacer ms
   controladores!), y un nmero grande de controladores acelerados por
   hardware estn disponibles comercialmente como parte del pack SciTech
   Display Doctor (http://www.scitechsoft.com/).

   Si tiene un controlador VBE 2.0 o VBE 3.0 quizs no necesite ms, pero no
   tendr aceleracin por hardware como la que permite el controlador
   VBE/AF. Si tiene una implementecin VESA antigua (ej: VESA 1.2), tenga
   cuidado. Por un lado, todo ser mucho ms lento que cuando Allegro puede
   usar las caractersticas sexys del controlador VBE 2.0. Por otro lado,
   podra hablarle todo el da de historias horribles sobre las
   implementaciones con fallos y generalmente patticas que me he
   encontrado. Si tiene problemas con los modos SVGA, pruebe conseguir una
   copia del SciTech Display Doctor y mire si soluciona sus problemas
   (seguramente lo har: SciTech suele hacer estas cosas bien).

   Tenga en cuenta que los controladores de chipsets SVGA nativos se han
   borrado de la biblioteca Allegro. Todava estn disponibles como un
   paquete adicional que puede conseguir del mismo sitio que Allegro, pero
   ya no son necesarios porque puede obtener el mismo cdigo en un formato
   ms flexible como parte del proyecto FreeBE/AF.

   En la parte de sonido, Allegro soporta la reproduccin de samples en la
   SB (mono), SB Pro (estreo), SB16 y ESS Audiodrive. Tiene controladores
   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 tiene
   ganas de aportar ms controladores para otro hardware, sern bienvenidos.

   La grabacin de audio est soportada por todas las SB, pero slo en modo
   unidireccional, es decir, no puede grabar y reproducir samples a la vez.
   La entrada MIDI se consique con los controladores MPU-401 y SB MIDI, pero
   hay ciertas restricciones con esto. La interfaz SB MIDI no puede ser
   usada al mismo tiempo que un sistema de sonido digital, y MPU slo
   funcionar si hay un IRQ libre (esto ser el caso si tienes una SB16 o
   superior, o si no instala ningn controlador de sonido digital tipo SB, o
   si su interfaz MIDI usa un IRQ diferente al de la SB).

   Se dar cuenta de que esta versin tiene algo de cdigo para crear una
   versin Linux, pero no se molestes en probarla: no funcionar! Falta
   _mucho_ ms trabajo antes de que Allegro funcione bajo Linux. Mire la
   seccin "work in progress" de la pgina web de Allegro para obtener
   informacin actualizada sobre la versin para Linux.


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

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

   - Ir a donde desee poner su copia de Allegro (su directorio djgpp sera
     una buena opcin, pero puede ponerlo en otro lado si prefiere), y
     descomprimir todo. Allegro contiene varios subdirectorio, por lo que
     tiene que especificar el parmetro -d si usa pkunzip.

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

   - Teclee "cd allegro", seguido por "make". Entonces haga algo interesante
     mientras todo se compila. Si todo va segn el plan, acabar con un par
     de programas de test, algunas herramientas como el grabber, y el
     fichero de biblioteca, liballeg.a.

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

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

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

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

   - Si quiere leer la documentacin de Allegro con el sistema de ayuda
     online de Rhide, vaya al menu "Help / Syntax help / Files to search", y
     aada "spallegr" despus de la entrada existente "libc" (separada por un
     espacio)

   - Si quiere crear la documentacin HTML como un largo fichero
     allegro.html en vez de separarlo en secciones, edite src\allegro._tx,
     elimine el comando @multiplefiles de la lnea 8, y ejecute make otra
     vez.

   - Una vez compilado todo, puede recuperar algo de espacio de disco
     ejecutando "make compress" (que usa el programa DJP o UPX para
     comprimir los ficheros ejecutables), y/o "make clean" (para librarse de
     todos los ficheros temporales y la documentacin en formato HTML).

   Para usar Allegro en su programa debera:

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

    #include <allegro.h>

   - Si compila desde la lnea de comando o con un makefile, aada '-lalleg'
     al final del comando gcc, ejemplo:

    gcc foo.c -o foo.exe -lalleg

   - Si est usando Rhide, vaya al men Options/Libraries, teclee 'alleg' en
     el primer espacio vaco, y asegrese de que la caja al lado est
     activada.

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



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

Cuando Allegro inicializa las rutinas de teclado y sonido, lee informacin
sobre su hardware desde un fichero llamado allegro.cfg o sound.cfg. Si estos
ficheros no existen, autodetectar el hardware (supongo :-) Puede escribir
su fichero de configuracin a mano con un editor de textos, o puede 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 podra tener diferentes
programas en diferentes directorios y querr usar un solo allegro.cfg para
todos ellos. Si este es el caso, puede hacer que la variable de entorno
ALLEGRO apunte al directorio que contiene su 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. Este debe estar en el mismo
directorio que su programa de Allegro, o en el directorio apuntado por la
variable ALLEGRO. Si quiere soporte para diferentes mapas de teclado
internacionales, debe distribuir una copia de keyboard.dat junto con su
programa.

Varias traducciones de cosas como el systema de mensajes de error estan
almacenadas en un fichero llamado language.dat. Este debe estar en el mismo
directorio que su programa Allegro, o en un directorio apuntado por la
variable de entorno ALLEGRO. Si quiere soportar versiones no Inglesas de
estos textos, debe distribuir una copia de language.dat junto con su
programa.

Mire 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 cinco canales de tambores. El cmo hacer que la msica suene bien en un
OPL2 se deja a ejercicio del lector :-) En una SB Pro o superior, tendr
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 darle 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, necesitar insertar una marca de evento como un mensaje de
control en un canal que no usa.

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 intente mover el sonido en estreo con mensajes de
control de panoramizacin, porque darn unos saltos horribles. Tambin
merece la pena considerar la panoramizacin sw cada canal para que la msica
suene bien en tarjetas SB Pro-I y OPL3. Si quiere un sonido panoramizado a
la izquierda o derecha, usa un valor de pan menor de 48 o mayor de 80. Si lo
quiere centrado, use un valor de pan entre 48 y 80, pero pngalo ligeramente
en un lado del centro 64, para controlar qu altavoz ser usado si la
panoramizacin central no es posible.

El controlador wavetable DIGMID usa ficheros .pat con formato estndar GUS,
y necesitar una coleccin de estos instrumentos antes de usarlos. Esta
puede estar en el formato estndar GUS (un par de ficheros .pat y un ndice
default.cfg), o un fichero patches.dat creado con la utilidad pat2dat.
Tambin puede usar pat2dat para convertir bancos SoundFont de la AWE32 en el
formato de patches.dat, y si indica 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 deshacerse
de instrumentos innecesarios cuando va a distribuir un juego. Mire en la
pgina web de Allegro para encontrar enlaces a conjuntos de instrumentos.

El controlador DIGMID normalmente carga slo los patches necesarios para
cada cancin cuando la reproduce por primera vez. Esto reduce el uso de
memoria, pero puede significar un retraso cuando vaya a reproducir cada
fichero MIDI. Si prefiere cargar el conjunto de instrumentos entero de una
sola vez, llame la funcin load_midi_patches().

El cdigo de mezcla por CPU puede soportar entre 1 y 64 voces, en
incrementos de potencia de dos (es decir: 1, 2, 4, 8, 16, 32 o 64 canales).
Por defecto provee 8 voces digitales, u 8 digitales ms 24 voces MIDI (un
total de 32) si el controlador DIGMID est siendo usado. Pero cuantas ms
voces, peor ser el volumen y la calidad del sonido, por lo que querr
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/

   Listas de correo:    allegro@canvaslink.com y agp@canvaslink.com. Mire en
                        http://www.talula.demon.co.uk/allegro/maillist.html
                        informacin sobre cmo suscribirse, en help.txt
                        podr leer instrucciones sobre cmo mandar mensajes
                        a las listas.

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

   IRC:                 Canal #allegro en EFnet

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

   Por carta:           Shawn Hargreaves, (escriba en ingls!)
                        Flat 1, 71 Croham Road,
                        Croydon, Surrey,
                        England, CR2 7HG

   Telfono:            UK 0181 6863666

   A pie:               Viniendo de la calle Croham desde al pub Croham Arms
                        (que est al lado de la estacin de trenes South
                        Croydon), justo despus del giro a la Avenida
                        Castlemaine, es la primera casa por la izquierda.

   Pariente prximo:    John Hargreaves,
                        1 Salisbury Road,
                        Market Drayton,
                        Shropshire,
                        England, TF9 1AJ.

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

