Puede leer en readme.txt una introducción general, detalles de copyright e información sobre cómo instalar Allegro y enlazar su programa con la biblioteca.
int install_allegro(int system_id, int *errno_ptr, int (*atexit_ptr)());
Inicializa Allegro. Debe llamar a esta función o a allegro_init() antes de
hacer otra cosa que no sea usar las rutinas Unicode. Si quiere usar un
formato de texto diferente al UTF-8, puede ajustarlo con set_uformat()
antes de llamar a esta función. Los identificadores de sistema disponibles
(system_id) variarán dependiendo de la plataforma utilizada, pero casi
siempre querrá usar SYSTEM_AUTODETECT. Alternativamente, SYSTEM_NONE
instalará una versión reducida de Allegro que no intentará realizar
accesos directos al hardware ni operaciones que sean particulares a una
plataforma específica: esto puede resultar útil para situaciones en las
que solamente quiera manipular bitmaps de memoria, como en una utilidad
que maneje ficheros de datos o las funciones de interfaz con el GDI de
Windows. Los parámetros errno_ptr y atexit_ptr deben apuntar a la variable
errno y la función atexit() de su librería C respectivamente. Estos
parámetros son requeridos ya que cuando Allegro es enlazado como una DLL
no tiene acceso directo a los datos locales de su librería C. atexti_ptr
puede ser NULL, en cuyo caso será su responsabilidad llamar allegro_exit
manualmente. Por ahora esta función siempre devuelve cero. Si no se puede
usar ningún driver de sistema, el programa será abortado.
int allegro_init();
Macro que inicia la librería Allegro. Esta función es equivalente a la
llamada install_allegro(SYSTEM_AUTODETECT, &errno, atexit).
void allegro_exit();
Cierra el sistema Allegro. Esto incluye devolver el sistema al modo texto
y desinstalar todas las rutinas de ratón, teclado o temporización que
estuviesen instaladas. Normalmente no tiene que molestarse en hacer una
llamada explícita a esta función, ya que allegro_init() la instala como
una función atexit(), por lo que será llamada automáticamente cuando su
programa finalice.
extern char allegro_id[];
Cadena de texto que contiene la fecha y número de versión de Allegro, en
caso de que quiera enseñar estos datos en alguna parte.
extern char allegro_error[ALLEGRO_ERROR_SIZE];
Cadena de texto usada por set_gfx_mode() e install_sound() para indicar
mensajes de error. Si éstas funciones fallan y quiere decirle al usuario
porqué, éste es el lugar en el que se encuentra una descripción del
problema.
extern int os_type;
Variable ajustada por allegro_init() a uno de los siguientes valores:
OSTYPE_UNKNOWN - desconocido, o MSDOS normal OSTYPE_WIN3 - Windows 3.1 o versiones anteriores OSTYPE_WIN95 - Windows 95 OSTYPE_WIN98 - Windows 98 OSTYPE_WINME - Windows ME OSTYPE_WINNT - Windows NT OSTYPE_WIN2000 - Windows 2000 OSTYPE_WINXP - Windows XP OSTYPE_OS2 - OS/2 OSTYPE_WARP - OS/2 Warp 3 OSTYPE_DOSEMU - Linux DOSEMU OSTYPE_OPENDOS - Caldera OpenDOS OSTYPE_LINUX - Linux OSTYPE_FREEBSD - FreeBSD OSTYPE_UNIX - variante Unix desconocida OSTYPE_BEOS - BeOS OSTYPE_QNX - QNX OSTYPE_MACOS - MacOSextern int os_version;
extern int os_multitasking;
Ajustado por allegro_init() a TRUE o FALSE dependiendo de si su Sistema
Operativo es multitarea o nó.
void allegro_message(char *msg, ...);
Muestra un mensaje usando una cadena con formato printf(). Esta función
sólo debe ser utilizada cuando no esté en un modo gráfico, es decir, antes
de llamar a set_gfx_mode() o después de llamar a set_gfx_mode(GFX_TEXT).
En plataformas que tengan una consola en modo texto (DOS, Unix y BeOS),
mostrará la cadena en la consola reduciendo los carácteres acentuados a
aproximaciones en 7 bits de códigos ASCII, evitando en lo posible los
problemas con las diferentes páginas de códigos. Bajo Windows, el mensaje
aparecerá en un ventana de mensajes.
void set_window_title(const char *name);
En las plataformas que sean capaces de ello, esta rutina cambia el título
de la ventana utilizada para su programa. Tenga en cuenta que Allegro no
es capaz de modificar el título de la ventana cuando ejecute una ventana
DOS en Windows.
int set_window_close_button(int enable);
En las plataformas que sean capaces de ello, esta rutina activa o
desactiva el botón de cerrar ventana de su programa Allegro. Si lo
desea, puede llamar esta rutina antes de que la ventana sea creada. Si el
botón de cerrar ventana es desactivado con éxito, esta función devolverá
cero.
En plataformas en las que el botón de cerrado no existe o no puede ser desactivado, la función devolverá -1. Si esto ocurre, quizás le interese usar set_window_close_hook() para manejar manualmente el evento de cierre de la ventana.
Cuando active el botón de cierre, la función devolverá el mismo valor que devolvió su plataforma al desactivarlo. Esto significa que devolverá distinto de cero si el botón no se puede desacivar, a pesar de que no esté intentando desactivarlo.
Tenga en cuenta que Allegro no puede manipular el botón de cerrado de una ventana DOS bajo Windows.
void set_window_close_hook(void (*proc)());
En las plataformas que tengan botón de cierre, esta rutina instala una
función de enganche en el evento de cierre. En otras palabras, cuando el
usuario pinche en el botón que cerraría la ventana de su programa, se
llamará a la función que especifique aquí. Puede usar esta función para
mostrar un diálogo ofreciendo salvar los datos o verificar que el usuario
realmente desea salir, o puede usarla para salvar los datos, liberar
memoria y salir.
Esta función generalmente no debería intentar salir del programa o salvar datos por sí misma. Esta función podría ser llamada en cualquier momento, y hay peligro de que los datos que intente salvar sean inválidos en ese momento. Por eso, debería activar una variable durante esta función, y verificar esta variable regularmente en su programa principal.
Pase NULL a esta función para recuperar la funcionalidad por defecto del botón de cierre. En Windows y BeOS, el siguiente mensaje aparecerá:
Aviso: forzar la finalización del programa puede ocasionar pérdidas de datos y resultados inesperados. Es preferible que use el comando de salir dentro de la ventana.
¿Desea continuar de todas maneras?
[Si] [No]
Este mensaje será traducido al lenguaje seleccionado si hay una traducción dispobible en language.dat (vea get_config_text()).
Si el usuario selecciona [Si], el programa finalizará inmediatamente en el mismo estilo que cuando el usuario pulsa Ctrl+Alt+End (vea three_finger_flag).
En otros sistemas operativos, el programa saldrá inmediatamente sin preguntar nada al usuario.
Tenga en cuenta que Allegro no puede interceptar el botón de cierre de una ventana DOS bajo Windows.
int desktop_color_depth();
En plataformas que pueden ejecutar programas de Allegro en una ventana
de un escritorio existente, devuelve la profundidad de color usada por
el escritorio en ese momento (su programa posiblemente correrá más si
usa la misma profundidad de color. En plataformas donde esta
información no es disponible o no tiene sentido, devuelve cero.
int get_desktop_resolution(int *width, int *height);
En plataformas que pueden ejecutar programas de Allegro en una ventana
de un escritorio existente, permite obtener la resolución actual usada
por el escritorio (ej: le itneresará llamar a esta función antes de crear
una gran ventana, porque en algunos drivers de modo ventana, ésta no
puede ser creada si es mayor que el escritorio). Devuelve cero si hubo
éxito, o un número negativo si la información no está disponible o no es
aplicable a su situación, en cuyo caso los valores almacenados en width
y heigth serán indefinidos.
void yield_timeslice();
En los sistemas que lo soportan, libera el resto de la "rebanada
temporal" (timeslice) que la CPU le había asignado. Esta opción también
es conocida como "pórtate bien con la multitarea".
void check_cpu();
Detecta el tipo de CPU, asignando valores a las siguientes variables
globales. Normalmente no necesita llamar a esta función, ya que
allegro_init() lo hará por usted.
extern char cpu_vendor[];
Contiene el nombre del proveedor de la CPU si éste es conocido. En
plataformas no-Intel, contiene una cadena vacía.
extern int cpu_family;
Contiene el tipo de CPU Intel, en las CPUs donde sea aplicable: 3=386,
4=486, 5=Pentium, 6=PPro, etc.
extern int cpu_model;
Contiene el submodelo de una CPU Intel, en las CPUs donde sea aplicable.
En un 486 (cpu_family=4), cero o uno indica un chip DX, 2 un SX, 3 indica
la presencia de un coprocesador matemático (486 SX + 487 ó 486 DX), 4 un
SL, 5 un SX2, 7 un DX2 write-back enhanced, 8 un DX4 o un overdrive DX4,
14 un Cyrix y 15 desconocido. En un chip Pentium (cpu_family=5), 1 indica
un Pentium (510\66, 567\66), 2 un Pentium P54C, 3 un procesador Pentium
overdrive, 5 un Pentium overdrive para IntelDX4, 14 un Cyrix y 15
desconocido.
extern int cpu_capabilities;
Contiene bits de la CPU que indican qué características están disponibles.
Los bits pueden ser una combinación de:
CPU_ID - Indica que la instrucción "cpuid" está disponible. Si este bit está activo, entonces todas las variables CPU de Allegro son fiables al 100%, en caso contrario podría haber fallos. CPU_FPU - Hay disponible una FPU x87. CPU_MMX - Conjunto de instrucciones Intel MMX disponible. CPU_MMXPLUS - Conjunto de instrucciones Intel MMX+ disponible. CPU_SSE - Conjunto de instrucciones Intel SSE disponible. CPU_SSE2 - Conjunto de instrucciones Intel SSE2 disponible. CPU_3DNOW - Conjunto de instrucciones AMD 3DNow! disponible. CPU_ENH3DNOW - Conjunto de instrucciones AMD Enhanced 3DNow! disponible. CPU_CMOV - Instrucción "cmov" del Pentium Pro disponible.
if ((cpu_capabilities & (CPU_FPU | CPU_MMX)) == (CPU_FPU | CPU_MMX)) printf("íLa CPU tiene tanto una FPU como instrucciones MMX!\n");