Cuando las cosas van mal, a menudo parece buena idea pedir a otras personas ayuda. Afortunadamente para las personas en esta situaci�n, hay muchas personas (tanto desarrolladores de Allegro como usuarios) que est�n dispuestas a responder preguntas de este tipo, pero hay varias cosas que puede hacer para que este proceso sea m�s eficiente. Este documento describe algunos pasos que debe tomar cuando tiene un problema con un programa que use Allegro, sugiriendo modos de solucionar el problema usted mismo, y ense�ando trucos sobre cu�ndo y/o c�mo pedir ayuda. El seguir estas reglas har� la vida m�s sencilla para el que le ayude (porque toda la informaci�n relevante ser� presentada de modo conciso y �til), y para el ayudado (porque as� ser� m�s probable que reciba una respuesta r�pida y precisa).
�Es un problema de Allegro, o de su c�digo? Para descubrirlo, pruebe ejecutar los programas test de Allegro, en particular test.exe (si tiene problemas con los gr�ficos), play.exe (problemas de sonido), y el contenido completo del directorio examples (para cualquier cosa que vaya mal). Si no puede reproducir el problema con uno de �stos, entonces probablemente es un fallo suyo, por lo que salte a la parte 3 m�s abajo.
Si el problema tiene que ver con los modos gr�ficos, deber�a conseguir una copia de UniVBE de http://www.scitechsoft.com/. Si esto soluciona el problema, significa que su driver VESA original estaba estropeado de alguna manera. No estoy interesado en o�r problemas de este tipo: no hay nada que pueda hacer para solucionarlos, me temo que su �nica opci�n es conseguir un driver VESA mejor, obligando al fabricante de tu tarjeta a que solucione los fallos, comprando UniVBE, o escribiendo un driver FreeBE/AF para su tarjeta (mire en http://www.talula.demon.co.uk/freebe/).
Si sigue pensado que el problema es de Allegro, mande un email con las caracter�sticas del sistema que contenga una descripci�n del problema, qu� hardware tiene, que servidor DPMI est� usando (CWSDPMI, win95, etc), y una lista de los programas con los que pudo reproducir el problema (no s�lo es importante saber qu� programas fallaron, sino cuales funcionaron, si funcion� alguno).
Si el problema est� relacionado con modos gr�ficos, tambi�n deber�a mandar el resultado que muestran los programas afinfo y vesainfo (la versi�n reducida es suficiente a no se que se le pida usar expl�citamente el par�metro -v: normalmente esos datos extra no son necesarios). Pruebe ejecutar el programa test.exe con varios controladores de Allegro (cualquier controlador nativo que crea que pueda funcionar, y los controladores VESA 2.0 y VESA 1.x), y en varios modos de v�deo, y diga ex�ctamente qu� modos de v�deo con qu� profundidades de color causaron problemas. Si no es capaz de ejecutar ninguna resoluci�n SVGA, pruebe test.exe con la opci�n Autodetect y copie todo el texto que aparece en la mitad de la pantalla.
Si el problema est� relacionado con el sonido, pruebe usar el programa setup para configurar manualmente su tarjeta. Quiz�s deba introducir manualmente los par�metros de su hardware, y si tiene una tarjeta compatible SB, pruebe seleccionar una tarjeta SB m�s antigua de la que est� autodetectando (SB Pro, SB 2.0 o SB 1.0). Si no consigue que funcione el sonido, su mensaje deber� incluir el nombre y descripci�n de los controladores de sonido digital y MIDI que est�n siendo autodetectados (esta informaci�n la ense�a el programa play.exe).
Cuando un programa djgpp falla, normalmente volcar� el contenido de la pila que parecer� algo como esto:
Exiting due to signal SIGSEGV
General Protection Fault at eip=00001eca
[corte]
Call frame traceback EIPs:
0x00001eca
0x00001590
0x00001aea
Esta informaci�n le indica exactamente d�nde ocurri� el fallo. Para que
estos datos tengan sentido, debe compilar su programa con informaci�n de
depurado (usando el par�metro -g), y ejecutar "symify programa.exe" cuando
est� viendo el contenido de la pila en pantalla. Eso cambiar� los datos
a algo parecido a esto:
Call frame traceback EIPs:
0x00001eca _strcpy+14
0x00001590 _main+56, line 7 of t.c
0x00001aea ___crt1_startup+138
En este caso, puede ver que el bloqueo ocurri� en la funci�n strcpy(),
que fue llamada en la l�nea 7 de la funci�n main() del fichero fuente
t.c. Ahora s�lo tienes que ir a esa l�nea, mirar lo que est� haciendo
all�, y corregirlo :-)
Nota: si el bloqueo ocurre dentro de una funci�n de Allegro, esta informaci�n no resultar� tan �til. Cuando esto ocurre puede recompilar Allegro con informaci�n de depurado (en su directorio Allegro, ejecute "make clean", "set DEBUGMODE=1", y "make install", pero f�jese que debe tener el pack GNU fileutils instalado), y entonces recompile su programa para usar la biblioteca con informaci�n de depurado. No olvide reconstruir la versi�n normal de Allegro (como arriba, pero "set DEBUGMODE=") cuando haya acabado, porque la biblioteca con informaci�n de depurado es muy lenta.
Nota 2: incluso cuando el traceback apunta a una funci�n de Allegro, no significa que sea fallo de una rutina de Allegro. Cualquier rutina fallar� si le pasa par�metros inv�lidos, por lo que a no ser que pueda duplicar el problema con uno de los programas de ejemplo de Allegro, deber�a asumir que es un caso de error de operador y chequear dos veces qu� valores le est� pasando a la funci�n de Allegro.
Uno de los errores m�s comunes cometidos por los programadores es ignorar el valor de retorno de una funci�n que puede fallar. Tal error normalmente llevar� a otros errores inusuales e inesperados, convirtiendo la depuraci�n en una pesadilla. Hay muchas funciones dentro y fuera de Allegro que pueden funcionar o no dependiendo de las circunstancias. Sin embargo le har�n saber si funcionaron o no gracias a los valores de retorno documentados.
Siempre que llame a una funci�n que puede fallar (sobre todo set_gfx_mode(), install_sound(), y cualquier cosa que carga datos del disco), es _esencial_ que chequee el valor devuelto por la funci�n, y act�e en consecuencia.
Otra herramienta importante com�nmente olvidada es usar el par�metro -Wall al compilar su c�digo. Cualquier aviso proporcionado por esta opci�n casi seguramente ser� un error en su programa, y deber�a solucionarlo antes de continuar. Un truco �til es compilar tambi�n con el par�metro -O, porque obliga a gcc a examinar las acciones de su programa con m�s detenimiento, activando m�s avisos �tiles. Sin embargo deber�a desactivar las optimizaciones cuando depure un programa. A pesar de que dan mejores avisos al compilar, posiblemente confundir�n las herramientas de depuraci�n que quiera usar.
Bueno, as� que ha probado todo lo descrito arriba y su programa sigue sin funcionar. No tiene ni idea de qu� hacer ahora, por lo que es tiempo de aventurarse en las entra�as de la red, con la esperanza de encontrar alg�n hombre sabio, adivino u or�culo que tenga la respuesta a su pregunta...
El mejor lugar donde puede preguntar es probablemente la lista de correo de Allegro: m�s detalles en el fichero readme.txt. Sin embargo, recuerde que esta lista es espec�fica de Allegro. Los problemas relacionados con el lenguaje C o el compilador djgpp pertenecen a otros forums (comp.lang.c y comp.os.msdos.djgpp respectivamente).
Tanto la lista de emails de Allegro como la de djgpp son archivadas, y puede ojear los mensajes desde sus p�ginas web respectivas. Es muy probable que encuentre una soluci�n a su problema mirando las respuestas a preguntas previas, lo que le evitar� hacer la pregunta.
Seg�n la netiqueta usual, se asume que cuando hace una pregunta en cualquier forum de Internet al menos ya ha consultado primero la documentaci�n relevante, ley�ndola por completo. Si el problema que tiene merece ser planteado a cientos de personas para que lo resuelvan, seguramente merecer� la pena tomarse unos minutos extra para solucionar el problema usted mismo. Allegro est� documentado extensivamente y se considera un prerequisito para hacer una pregunta no s�lo el haber le�do la documentaci�n, sino tambi�n haber examinado los programas de ejemplo.
Qu� no hacer, Primera Parte:
"Mi programa se bloquea. Por favor, dime porqu�."
Si, a veces recibo preguntas como �sta :-) A pesar de a�os de pr�ctica,
todav�a no soy capaz de leer el pensamiento, por lo que es in�til este
tipo de pregunta. Para conseguir ayuda con un problema debe describirlo
con suficiente detalle como para que otras personas lo entiendan y puedan
reproducirlo: esto normalmente significa mandar parte de su c�digo.
Qu� no hacer, Segunda Parte:
"Tengo un problema con mi programa. Junto con este email mando un
fichero zip de 500k que contiene diez mil l�neas de c�digo y todos los
gr�ficos y sonidos necesarios: �por favor, puedes depurarlo y decirme
cual es el problema?"
Despu�s de desperdiciar tiempo y facturas de tel�fono para recibir un
fichero tan grande, es poco probable que nadie _quiera_ ayudarle, sin
olvidar el tiempo que se necesitar�a para leer y entender tal enorme
cantidad de informaci�n. Tiene que aislar una parte m�s peque�a de c�digo
que demuestre el problema: cuanto m�s corto sea, m�s probable ser� que
alguien le ayude. Recuerde que est� pidiendo a otros que le hagan un
favor, por lo que es su responsabilidad hacerles este proceso tan
sencillo como puedas.
La cosa m�s importante es incluir c�digo que puede ser compilado y comprobado por la persona que lee su mensaje. No mande simplemente todo su programa: extraiga una secci�n peque�a que incluya las l�neas espec�ficas que causan su problema, o reproduzca el problema de forma m�s simple (a menudo descubrir� que puede encontrar el error usted mismo al hacer una versi�n simplificada de su programa, por lo que es un buen ejercicio que puede hacer). Este c�digo deber�a ser un programa peque�o pero completo que puede ser compilado y ejecutado, ya que es muy dif�cil depurar fragmentos incompletos de c�digo.
Es mejor incluir el c�digo directamente en el texto de su email, porque a la gente le resultar� m�s sencillo leer esto que si tuviesen que extraer el c�digo de un attachment.
Idealmente su ejemplo deber�a evitar el uso de gr�ficos externos y ficheros de datos. Est� bien incluir un peque�o zip (m�x 2k) que contiene informaci�n, o si no puede hacerlo, de una descripci�n de qu� ficheros necesita (ej: "pon un fichero .pcx de 32x32 llamado "tile.pcx" en el mismo directorio que el programa). Si no hay modo alguno de simplificar las cosas, deber�a copiar su programa y sus datos a una p�gina web, y entonces dar la URL del fichero zip en su mensaje.
Deber�a decir que l�nea de comando gcc ha usado para crear el programa, y �sta deber�a incluir el par�metro -Wall.
Describa qu� es lo que intenta hacer el programa (puede no ser obvio instant�neamente para otras personas), y tambi�n qu� es lo que hace realmente cuando lo ejecuta. Normalmente no hace falta indicar el traceback de su programa cuando se bloquea (otras personas pueden duplicarlo por s� mismos siempre y cuando consigan compilar su c�digo), pero deber�a indicar si aparece este traceback, o se bloquea el programa, o si devuelve resultados incorrectos (si es as�, en qu� difieren estos de los que esperaba). Es �til marcar su c�digo con comentarios para indicar a qu� l�nea apunta el traceback del programa.
Otra informaci�n que pueda a�adir puede ser �til. Lo m�s importante es una descripci�n corta de su hardware, informaci�n relevante de sus controladores, y la versi�n de Allegro que est� usando (por favor no diga "WIP" a secas, sino la fecha exacta si est� usando una versi�n que no sea oficial).
Como referencia, aqu� tiene un ejemplo de lo que yo considerar�a un mensaje ideal:
Estoy teniendo problemas cuando uso los modos de v�deo hicolor en mi programa, a pesar de que funcionan bien con los tests de Allegro. Estoy usando Allegro 3.0 en un p166, corriendo bajo win95 y usando el driver VESA 2.0 de mi tarjeta, que el programa vesainfo describe como "Matrox Graphics Inc.".Este programa deber�a seleccionar una resoluci�n 640x480 de 16 bits, dibujar un rect�ngulo azul cerca de la esquina superior izquierda de la pantalla, y entonces esperar la pulsaci�n de una tecla antes de salir, pero simplemente recibo un General Protection Fault cuando lo ejecuto.
Lo compilo usando "gcc -Wall t.c -o t.exe -lalleg", y no obtengo ning�n mensaje de error.
--- corta aqu�, t.c ---#include <stdio.h> #include <allegro.h>
void main() { BITMAP *bmp = screen;
install_keyboard();
if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0) { printf("Error seleccionando modo de v�deo\n"); return; }
set_color_depth(16);
/* � se bloquea cuando llama rectfill ! */ rectfill(bmp, 32, 32, 64, 64, 0x001F);
readkey(); }