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


    Una biblioteca de funciones para programar videojuegos.

         Por Shawn Hargreaves, 1994/1999.
         Traducido por 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 crear videojuegos, escrita
   para el compilador djgpp en una mezcla de lenguaje C y ensamblador. Esto
   es la versin 3.11 para el compilador djgpp: lea el fichero NEWS para ver
   las diferencias respecto a la versin anterior. 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, http://www.talula.demon.co.uk/allegro/.

   Segn el suplemento de Msica del diccionario Oxford, Allegro es la
   palabra italiana para "rpido, vivo, brillante". Adems es un acrnimo
   recursivo para "Allegro Low Level Game Routines".



=========================================
============ 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, Ensoniq Soundscape 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 ============
===================================


   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, ESS Audiodrive y Ensoniq Soundscape.
   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. Las tarjetas SB PCI-64 y PCI-128 de Creative Labs estn
   basadas en el chip de Ensoniq, por lo que pueden ser usadas con el
   controlador de Soundscape y MPU-401. Sin embargo, tendr que seleccionar
   el MPU manualmente, ya que no ser autodetectado. Actualmente, muchas
   tarjetas de tabla de ondas emulan el MPU, por lo que intente esto y mire
   si funciona en su tarjeta. 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 ============
=================================================

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

   Hay tres listas de correo para discusiones relacionadas con Allegro, cada
   una con un propsito ligeramente diferente.

   [AL] - Allegro - allegro@canvaslink.com
      Esta lista es para cualquier discusin sobre Allegro, preguntas sobre
      Allegro, problemas con Allegro, sugerencias para nuevas
      caractersticas, anuncios de programas hechos con Allegro, etc. Regla
      general: Si tiene algo que ver con Allegro, puedes mandar un mensaje
      aqu. Si no, ve a otra parte (por ejemplo, comp.os.msdos.djgpp,
      comp.lang.c, o la lista AGP).

   [AGP] - Allegro Games Programming - agp@canvaslink.com
      Esta lista es para discutir problemas de carcter ms general que
      pueden surgir al escribir un juego que usa Allegro, pero que no estn
      directamente relacionados con la propia biblioteca de funciones. Por
      ejemplo, si quieres hablar sobre algoritmos para hacer un scroll de un
      mapa, eso sera off-topic en la lista de correo de Allegro, pero
      apropiado para discutir aqu.

   [AD] - Allegro Developers - conductors@canvaslink.com
      Esta lista es para las personas que trabajan en Allegro, que la usan
      para coordinar sus esfuerzos. Puedes usar esta direccin si necesitas
      contactar con un desarrollador directamente, por ejemplo, para
      proporcionar nuevo cdigo o para notificar de un fallo. A diferencia
      de las otras listas, seremos muy estrictos con la gente que mande
      material inapropiado a esta lista, por lo que no lo intentes! No nos
      mandes preguntas tcnicas de soporte a esta lista. No mandes
      notificaciones de error a no ser que ests seguro al 100% de que no es
      tu fallo (si tienes dudas, usa la lista de correo principal, a la que
      estn suscrictos la mayora de las personas de esta lista). El
      desarrollo de Allegro es un proceso completamente abierto, y
      cualquiera est invitado para pasar, escuchar los proyectos y comenzar
      contribuyendo nuevo cdigo. Sin embargo, esta lista es ms para
      trabajar que para hablar, por lo que no haga nada que pueda estar en
      nuestro camino.

   Para suscribirse a una de las listas, escriba a listserv@canvaslink.com
   con el texto "subscribe {lista} minombre" en el cuerpo del mensaje, donde
   {list} es allegro, agp o conductors.

   Para borrarse de la lista, escriba a listserv@canvaslink.com con el texto
   "unsubscribe {list}" en el cuerpo del mensaje, donde {list} es allegro,
   agp o conductors.

   Tenga en cuanta que la direccin de correo para suscribirse o borrarse de
   una lista no es el mismo que la direccin a la que manda mensajes. Por
   favor, recuerde mandar sus peticiones de administracin a listserv, en
   vez de a la propia lista.

   Para mandar un mensaje a una lista, escriba a allegro@canvaslink.com,
   agp@canvaslink.com, o conductors@canvaslink.com. No necesita estar en una
   lista para mandar un mensaje a stas, pero es buena idea hacerlo para
   leer las respuesta. Est bien mandar cdigo para contribuir a la lista de
   desarrolladores sin estar suscrito, siempre y cuando notifique que no
   est en la lista, para responderle personalmente en caso de que haga
   falta. Antes de mandar una pregunta tcnica o de soporte a la lista de
   correo de Allegro, por favor tmese un momento en leer las instrucciones
   de help.txt.

   Puede buscar en los archivos de las listas de correo usando el buscador
   de http://www.canvaslink.com/allegro/search.htm.

   Nota: por favor no mande mensajes en formato HTML. El incremento de
   tamao de stos innecesariamente carga al servidor, y muchos suscriptores
   tendrn problemas al leer su mensaje.

   Nota: por favor no mande mensajes cruzados a varias de estas listas a la
   vez. Elija cul es la ms apropiada para su mensaje, y mndelo slo a
   esa.

   Nota: por favor no mande ficheros binarios junto con su mensaje a ninguna
   de estas listas. Suba sus ficheros a una pgina web en un fichero
   comprimido, y luego notifique del enlace en la lista, o si no puede hacer
   eso, mande un mensaje solicitando que la gente se ponga en contacto con
   usted de forma privada, y entonces responda de forma individual a quien
   quiera que responda.

   Mi direccin personal es shawn@talula.demon.co.uk, pero por favor evite
   mandarme mensajes, a no ser que sean de carcter personal. Use la lista
   de correo de Allegro para preguntas sobre Allegro, y la de
   desarrolladores para mandar contribuciones de cdigo. Yo leo todas las
   listas de correo, y adems al usarlas, es ms probable que obtenga
   respuesta de otras personas incluso si no estoy yo o estoy ocupado con
   otra cosa en el momento.

   Para esa cade vez menor minora de personas sin acceso a internet, la
   direccin de mi domicilio es Flat 1, 71 Croham Road, Croydon, Surrey,
   England, CR2 7HG. Para es an ms pequea minora de personas que no
   pueden acceder a un servicio de correos, busque un camino a la estacion
   de trenes de South Croydon y baje la calle Croham Road, alejndose del
   pub Croham Arms. Justo despus del giro a Castlemaine Avenue, es la
   primera casa de la izquierda.
