______ ___ ___ /\ _ \ /\_ \ /\_ \ \ \ \L\ \\//\ \ \//\ \ __ __ _ __ ___ \ \ __ \ \ \ \ \ \ \ /'__`\ /'_ `\/\`'__\/ __`\ \ \ \/\ \ \_\ \_ \_\ \_/\ __//\ \L\ \ \ \//\ \L\ \ \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/ \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/ /\____/ \_/__/ Versión 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 contribuído a Allegro, y en el fichero AUTORES un listado completo de los que han contribuído a la traducción de Allegro. #include "No me responsabilizo de ningún efecto, negativo, positivo u otro que este código pueda tener sobre usted, su ordenador, su salud, su perro, o cualquier otra cosa que pueda imaginar. Uselo bajo su propia responsabilidad." ====================================== ============ Introducción ============ ====================================== Allegro es una librería 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 fantástico 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 exóticos como DirectX y el Servidor X, pero la familia entera está reunida de nuev, viviendo en armonía en una única entidad portable. ¿Qué le parece eso como mezcla de metáforas? :-) También hay disponible un amplio rango de paquetes de extensión y módulos add-on, que pueden ser encontrados en la sección "Library Extensions" del web Allegro.cc, http://allegro.cc/. Según el suplemento de Música del diccionario Oxford, Allegro es la palabra italiana para "rápido, vivo, brillante". Además es un acrónimo recursivo para "Allegro Low Level Game Routines". Al final de este fichero tiene unas notas/instrucciones sobre esta traducción que le convendría leer al menos una vez. ================================================ ============ Plataformas soportadas ============ ================================================ Para obtener instrucciones sobre cómo instalar Allegro, cómo enlazar sus programas con Allegro, y cualquier otra información adicional específica 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 información general sobre el API puede encontrarse en txt/allegro.txt, que también está disponible en formato HTML, TexInfo y RTF en el directorio docs. ========================================= ============ Características ============ ========================================= Soporte multiplataforma para DOS, Windows, Unix, BeOS, QNX y MacOS. Las funciones de dibujo incluyen putpixel, getpixel, líneas, rectángulos, polígonos con sombreado flat, goraud, texturizado y con z-buffer, círculos, relleno de áreas, curvas bezier, rellenos de áreas con patrón, dibujado de sprites con máscara, codificados con RLE o compilados, copia de áreas de memoria (blitting), escalado y rotación de bitmaps, efectos de translucidez/iluminación, 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 tamaño. Los drivers para DOS soportan el modo 13h de la VGA, modo-X (veintitres resoluciones VGA trucadas más 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 aceleración por hardware VBE/AF si están disponibles. El soporte de hardware de vídeo 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 además hay rutinas para dibujar sobre superficies GDI. Bajo Unix hay drivers para X, DGA, fbcon, SVGAlib, VBE/AF, modo-X, y VGA estándar. 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 manipulación de paletas de color. Reproductor de animaciones FLI/FLC. Reproduce música MIDI de fondo y hasta 64 efectos de sonido simultáneos y puede grabar ondas de sonido o entrada MIDI. Los samples pueden ser repetidos (hacia delante, atrás o bidireccionalmente), y el volumen, la panoramización, la frecuencia, etc, de éstos puede ser reajustada mientras se reproducen. El reproductor MIDI responde a note on, note off, volumen principal, panoramización, modificación de frecuencia, y mensajes de cambio de programa usando el conjunto de instrumentos y tambores General MIDI. La versión DOS soporta Adlib, SB, SB Pro, SB16, AWE32, MPU-401, ESS AudioDrive, Ensoniq Soundscape y Windows Sound System. La versión Windows soporta las interfaces WaveOut y DirectSound, y los drivers MIDI del sistema. La versión Unix tiene drivers para OSS, ESD y ALSA. La versión BeOS soporta las interfaces BSoundPlayer y BMidiSynth. Todas las versiones proveen soporte de reproducción MIDI por emulación software wavetable (tablas de ondas). Fácil acceso al ratón, teclado, joystick y temporizadores de alta resolución, incluyendo una interrupción que simula el retrazo vertical en la versión DOS. Rutinas para leer y escribir ficheros con compresión LZSS. Ficheros de datos multi-objeto y la utilidad grabber. Funciones matemáticas incluyendo aritmética de punto fijo, tablas trigonométricas precalculadas y manipulación de vectores/matrices/ cuaternas 3d. Gestor de diálogos GUI y selector de ficheros. Soporte para formatos Unicode de carácteres 16-bit o UTF-8. =================================== ============ Copyright ============ =================================== Allegro es gift-ware (software-regalo). Fue creado por un número de personas trabajando en cooperación, 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 quizás simplemente distribuir libremente el código de su programa para que otras personas puedan aprender de él. Si redistribuye partes de este código o hace un juego con él, sería bonito que mencionase Allegro en alguna parte de los créditos, pero no está obligado a hacerlo. Confiamos en que no abuse de nuestra generosidad. ======================================= ============ Configuración ============ ======================================= Cuando Allegro inicializa las rutinas de teclado y sonido, lee información 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 configuración a mano con un editor de textos, o puede usar la utilidad setup. Normalmente setup.exe y allegro.cfg irán 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 podría 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 configuración también 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 configuración. =============================================== ============ Notas sobre el sonido ============ =============================================== El controlador wavetable DIGMID usa ficheros .pat con formato estándar GUS, y necesitará una colección de estos instrumentos antes de usarlos. Esta puede estar en el formato estándar GUS (un par de ficheros .pat y un índice default.cfg), o un fichero patches.dat creado con la utilidad pat2dat. También puede usar pat2dat para convertir bancos SoundFont de la AWE32 en el formato de patches.dat, y si indica algunos ficheros MIDI en la línea de comando, filtrará el conjunto de instrumentos para incluir sólo 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 página web de Allegro para encontrar enlaces a conjuntos de instrumentos. El controlador DIGMID normalmente carga sólo los patches necesarios para cada canción 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 función load_midi_patches(). El código 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 más 24 voces MIDI (un total de 32) si el controlador DIGMID está siendo usado. Pero cuantas más voces, peor será el volumen y la calidad del sonido, por lo que querrá cambiar esto llamando la función reserve_voices() o ajustando los parámetros digi_voices y midi_voices en allegro.cfg. ================================================= ============ Información de contacto ============ ================================================= Siempre puede conseguir la última versión de Allegro en la página web de Allegro, http://alleg.sourceforge.net/. Hay tres listas de correo para discusiones relacionadas con Allegro, cada una con un propósito ligeramente diferente. [AL] - Allegro - allegro@canvaslink.com. Esta lista es para cualquier discusión sobre Allegro, preguntas sobre Allegro, problemas con Allegro, sugerencias para nuevas características, 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 carácter más general que pueden surgir al escribir un juego que usa Allegro, pero que no están directamente relacionados con la propia biblioteca de funciones. Por ejemplo, si quieres hablar sobre algoritmos para hacer un scroll de un mapa, eso sería 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 dirección si necesitas contactar con un desarrollador directamente, por ejemplo, para proporcionar nuevo código 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 técnicas de soporte a esta lista. No mandes notificaciones de error a no ser que estés seguro al 100% de que no es tu fallo (si tienes dudas, usa la lista de correo principal, a la que están suscrictos la mayoría 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 código. Sin embargo, esta lista es más 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 dirección de correo para suscribirse o borrarse de una lista no es el mismo que la dirección a la que manda mensajes. Por favor, recuerde mandar sus peticiones de administración 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 código 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 técnica o de soporte a la lista de correo de Allegro, por favor tómese 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 tamaño de éstos innecesariamente carga al servidor, y muchos suscriptores tendrán problemas al leer su mensaje. Nota: por favor no mande mensajes cruzados a varias de estas listas a la vez. Elija cuál es la más apropiada para su mensaje, y mándelo sólo a esa. Nota: por favor no mande ficheros binarios junto con su mensaje a ninguna de estas listas. Suba sus ficheros a una página 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 dirección personal es shawn@talula.demon.co.uk, pero por favor evite mandarme mensajes, a no ser que sean de carácter personal. Use la lista de correo de Allegro para preguntas sobre Allegro, y la de desarrolladores para mandar contribuciones de código. Yo leo todas las listas de correo, y además al usarlas, es más 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 minoría de personas sin acceso a internet, la dirección de mi domicilio es Flat 1, 71 Croham Road, Croydon, Surrey, England, CR2 7HG. Para es aún más pequeña minoría 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, alejándose del pub Croham Arms. Justo después del giro a Castlemaine Avenue, es la primera casa de la izquierda. ========================================================================= ============ Instalando la documentación española de Allegro ============ ========================================================================= *** AVISO *** Si no consigue compilar Allegro correctamente, es probable que tampoco pueda crear la documentación. Primero asegúrese de que consigue compilar Allegro correctamente. - El primer paso, que es descomprimir el fichero que contiene la documentación ya está hecho, o no sería capaz de leer esto :-) No obstante, si está usando el programa pkunzip de DOS, deberá haber usado el parámetro -d para conservar la estructura de directorios durante la descompresión. - Entrando en el nuevo directorio creado teclee "make". Si todo va bien, debería ver un mensaje en el que se le indican los posibles comandos del make para generar un determinado tipo de documentación. Por ejemplo, podría teclear "make html" para crear la documentación sólo en formato html. - Si desea crear la versión HTML de la documentación como un sólo fichero allegro.html, en vez de tener muchos sueltos, modifique el fichero src\allegro._tx, borre el comando @multiplefiles de las primeras líneas, y ejecuta make otra vez. - Como podrá apreciar, hay dos tipos de documentación: la documentación pregenerada (otros ficheros .txt del directorio principal y del directorio build) y la documentación que debe generar (y es almacenada en los directorios del tipo indicado). La documentación pregenerada contiene siempre una línea inicial que indica el documento relativo inglés en la distribución original de Allegro. ================================================== ============ Conflictos de carácteres ============ ================================================== Cuando Microsoft diseñó su sistema operativo MS-DOS, pudo haber implementado en el juego de carácteres españoles los mismos que dicta el estándar de la ISO. Sin embargo, para hacer las cosas aun más difíciles, Microsoft ignoró el estándar y se creó su propia tabla de configuración. Bueno, en realidad dos :-) Esto significa que en sistemas DOS probablemente esté leyendo casi todos los textos sin acentos. Esto está hecho a propósito: por un lado es imposible autodetectar la página de códigos que está usando (sin entrar en la problemática de que también depende del programa que use para visualizar los textos), y por otro lado es menos doloroso leer palabras sin carácteres españoles que con letras extrañas que no se sabe de dónde vienen y entorpecen la lectura. El resultado final es que sólamente la documentación en formatos rtf y html puede ser leída con los carácteres españoles, ya que sólo hay una codificación posible de cada letra representada.