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


    Una biblioteca de funciones para programar videojuegos.

        Por Shawn Hargreaves, 10 de diciembre del 2001.

      Lea en el fichero AUTHORS un listado completo de los que han
      contribudo a Allegro, y en el fichero AUTORES un listado
      completo de los que han contribudo a la traduccin de 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 propia
    responsabilidad."



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

   Allegro es una librera multi plataforma para crear videojuegos y otros
   tipos de programas multimedia. Fue concebida inicialmente en un Atari ST,
   pero tristemente aquella plataforma muri durante el alumbramiento. Tras
   un breve periodo con Borland C, fue adoptada por el fantstico compilador
   djgpp, donde alcanz la madurez. Tras el paso del tiempo di a luz a sus
   propios hijos, que se fueron a vivir a lugares tan exticos como DirectX
   y el Servidor X, pero la familia entera est reunida de nuev, viviendo en
   armona en una nica entidad portable. Qu le parece eso como mezcla de
   metforas? :-)
   
   Tambin hay disponible un amplio rango de paquetes de extensin y mdulos
   add-on, que pueden ser encontrados en la seccin "Library Extensions" del
   web Allegro.cc, http://allegro.cc/.

   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".

   Al final de este fichero tiene unas notas/instrucciones sobre esta
   traduccin que le convendra leer al menos una vez.



================================================
============ Plataformas soportadas ============
================================================

   Para obtener instrucciones sobre cmo instalar Allegro, cmo enlazar sus
   programas con Allegro, y cualquier otra informacin adicional especfica
   de cada una de las plataformas soportadas, lea uno de estos ficheros:

   DOS/djgpp         - lea build/djgpp.txt
   DOS/Watcom        - lea build/watcom.txt
   Windows/MSVC      - lea build/msvc.txt
   Windows/MinGW32   - lea build/mingw32.txt
   Windows/Cygwin    - lea build/mingw32.txt
   Windows/Borland   - lea build/bcc32.txt
   Linux (console)   - lea build/linux.txt
   Unix (X)          - lea build/unix.txt
   BeOS              - lea build/beos.txt
   QNX               - lea build/qnx.txt
   MacOS/MPW         - lea build/macos.txt

   La informacin general sobre el API puede encontrarse en
   txt/allegro.txt, que tambin est disponible en formato HTML,
   TexInfo y RTF en el directorio docs.



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

   Soporte multiplataforma para DOS, Windows, Unix, BeOS, QNX y MacOS.

   Las funciones de dibujo incluyen putpixel, getpixel, lneas, rectngulos,
   polgonos con sombreado flat, goraud, texturizado y con z-buffer,
   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 (blitting), escalado y rotacin de bitmaps, efectos
   de translucidez/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.

   Los drivers para DOS soportan 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/).

   Los drivers para Windows usan DirectX a pantalla completa y en modos de
   ventana, y adems hay rutinas para dibujar sobre superficies GDI.

   Bajo Unix hay drivers para X, DGA, fbcon, SVGAlib, VBE/AF, modo-X, y VGA
   estndar.

   Los drivers para BeOS usan BWindowScreen a pantalla completa y
   BDirectWindow en modos de ventana.

   Soporte de scroll por hardware y triple buffering (donde est disponible),
   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. La versin DOS soporta Adlib, SB, SB Pro, SB16, AWE32,
   MPU-401, ESS AudioDrive, Ensoniq Soundscape y Windows Sound System. La
   versin Windows soporta las interfaces WaveOut y DirectSound, y los
   drivers MIDI del sistema. La versin Unix tiene drivers para OSS, ESD y
   ALSA. La versin BeOS soporta las interfaces BSoundPlayer y BMidiSynth.
   Todas las versiones proveen soporte de reproduccin MIDI por emulacin
   software wavetable (tablas de ondas).

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

   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, tablas
   trigonomtricas precalculadas y manipulacin de vectores/matrices/
   cuaternas 3d.

   Gestor de dilogos GUI y selector de ficheros.

   Soporte para formatos Unicode de carcteres 16-bit o UTF-8.



===================================
============ 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.



=======================================
============ 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.

   Bajo Unix y BeOS, las rutinas de configuracin tambin leen ~/allegro.cfg,
   ~/.allegrorc, /etc/allegro.cfg, y /etc/allegrorc, en ese orden, y los
   ficheros de mapas de teclado y lenguajes pueden almacenarse en su
   directorio home o en /etc/.

   Lea en txt/allegro.txt los detalles del formato de los ficheros de
   configuracin.



===============================================
============ Notas sobre el sonido ============
===============================================

   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://alleg.sourceforge.net/.

   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 txt/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.



=========================================================================
============ Instalando la documentacin espaola de Allegro ============
=========================================================================

   *** AVISO ***
   Si no consigue compilar Allegro correctamente, es probable que tampoco
   pueda crear la documentacin. Primero asegrese de que consigue compilar
   Allegro correctamente.

   - El primer paso, que es descomprimir el fichero que contiene la
     documentacin ya est hecho, o no sera capaz de leer esto :-) No
     obstante, si est usando el programa pkunzip de DOS, deber haber
     usado el parmetro -d para conservar la estructura de directorios
     durante la descompresin.

   - Entrando en el nuevo directorio creado teclee "make". Si todo va bien,
     debera ver un mensaje en el que se le indican los posibles comandos
     del make para generar un determinado tipo de documentacin. Por
     ejemplo, podra teclear "make html" para crear la documentacin slo
     en formato html.

   - Si desea crear la versin HTML de la documentacin como un slo fichero
     allegro.html, en vez de tener muchos sueltos, modifique el fichero
     src\allegro._tx, borre el comando @multiplefiles de las primeras lneas,
     y  ejecuta make otra vez.

   - Como podr apreciar, hay dos tipos de documentacin: la documentacin
     pregenerada (otros ficheros .txt del directorio principal y del
     directorio build) y la documentacin que debe generar (y es almacenada
     en los directorios del tipo indicado). La documentacin pregenerada
     contiene siempre una lnea inicial que indica el documento relativo
     ingls en la distribucin original de Allegro.



==================================================
============ Conflictos de carcteres ============
==================================================

   Cuando Microsoft dise su sistema operativo MS-DOS, pudo haber
   implementado en el juego de carcteres espaoles los mismos que dicta el
   estndar de la ISO. Sin embargo, para hacer las cosas aun ms difciles,
   Microsoft ignor el estndar y se cre su propia tabla de configuracin.
   Bueno, en realidad dos :-)

   Esto significa que en sistemas DOS probablemente est leyendo casi todos
   los textos sin acentos. Esto est hecho a propsito: por un lado es
   imposible autodetectar la pgina de cdigos que est usando (sin entrar
   en la problemtica de que tambin depende del programa que use para
   visualizar los textos), y por otro lado es menos doloroso leer palabras
   sin carcteres espaoles que con letras extraas que no se sabe de dnde
   vienen y entorpecen la lectura.

   El resultado final es que slamente la documentacin en formatos rtf y
   html puede ser leda con los carcteres espaoles, ya que slo hay una
   codificacin posible de cada letra representada.
   
