00 Usando Allegro

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.

Relacionado con: allegro_init, allegro_exit.
int allegro_init();
Macro que inicia la librería Allegro. Esta función es equivalente a la llamada install_allegro(SYSTEM_AUTODETECT, &errno, atexit).
Relacionado con: install_allegro, allegro_exit.
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.
Relacionado con: allegro_init.
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.

Relacionado con: set_gfx_mode, install_sound.
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      - MacOS
Relacionado con: allegro_init.
extern int os_version;
extern int os_revision;
La versión mayor y menor del Sistema Operativo usado. Ajustado por allegro_init(). Si Allegro por alguna razón no es capaz de obtener la versión de su Sistema Operativo, os_version y os_revision valdrán -1. Por ejemplo: bajo Win98 SE (v4.10.2222) os_version valdrá 4 y os_revision valdrá 10.
Relacionado con: os_type, os_multitasking.
extern int os_multitasking;
Ajustado por allegro_init() a TRUE o FALSE dependiendo de si su Sistema Operativo es multitarea o nó.
Relacionado con: os_type, os_version.
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.

Relacionado con: set_window_close_hook, set_window_title.
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.

Relacionado con: set_window_close_button, set_window_title, get_config_text, three_finger_flag.
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.
Relacionado con: get_desktop_resolution.
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.
Relacionado con: desktop_color_depth.
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.

Relacionado con: cpu_vendor, cpu_family, cpu_model, cpu_capabilities.
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.
Relacionado con: check_cpu, cpu_family, cpu_model, cpu_capabilities.
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.
Relacionado con: check_cpu, cpu_vendor, cpu_model, cpu_capabilities.
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.
Relacionado con: check_cpu, cpu_vendor, cpu_family, cpu_capabilities.
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.

Puede verificar múltiples características haciendo una OR de los bits. Por ejemplo, para ver si la CPU tiene una FPU y un conjunto de instrucciones MMX podría hacer: 

      if ((cpu_capabilities & (CPU_FPU | CPU_MMX)) == (CPU_FPU | CPU_MMX))
         printf("¡La CPU tiene tanto una FPU como instrucciones MMX!\n");
Relacionado con: check_cpu, cpu_vendor, cpu_family, cpu_model, cpu_capabilities.
Volver al Indice