void set_color_depth(int depth);
Especifica el formato gráfico que será usado en las siguientes llamadas a
set_gfx_mode() y create_bitmap(). Las profundidades válidas son 8 (por
defecto), 15, 16, 24 y 32 bits.
void request_refresh_rate(int rate);
Solicita que en la siguiente llamada a set_gfx_mode() se intente usar la
velocidad de refresco especificada, si es posible. No todos los
controladores son capaces de esto, e incluso cuando pueden, no todas las
velocidades serán posibles en cualquier hardware, por lo que el resultado
puede diferir de lo que haya pedido. Tras la llamada a set_gfx_mode(),
puede usar get_refresh_rate() para saber qué velocidad de refresco fue
seleccionada. Por el momento, sólo el driver DOS VESA 3.0, X DGA 2.0 y
algunos drivers de DirectX soportan esta función. La velocidad es
especificada en Hz, ej: 60, 70. Para volver a la velocidad por defecto,
pase el valor cero.
int get_refresh_rate(void);
Devuelve la velocidad de refresco actual, si es conocida (no todos los
controladores pueden devolver esta información). Devuelve cero si la
velocidad de refresco actual es desconocida.
GFX_MODE_LIST *get_gfx_mode_list(int card);
Intenta crear una lista de todos los modos de vídeo soportados por un
driver gráfico GFX determinado. Esta función devuelve un puntero a una
lista de estructuras del tipo GFX_MODE_LIST que estan definidas como:
typedef struct GFX_MODE_LIST { int num_modes; GFX_MODE *mode; } GFX_MODE_LIST;Si esta función devuelve NULL, significa que la llamada no tuvo éxito. El puntero mode apunta a la verdadera lista de modos de vídeo.
typedef struct GFX_MODE { int width, height, bpp; } GFX_MODE;Esta lista termina con un elemento { 0, 0, 0 }.
void destroy_gfx_mode_list(GFX_MODE_LIST *mode_list);
Borra de la memoria la lista de modos creada por get_gfx_mode_list().
int set_gfx_mode(int card, int w, int h, int v_w, int v_h);
Cambia a modo gráfico. El parámetro card normalmente debería ser
GFX_AUTODETECT, GFX_AUTODETECT_FULLSCREEN o GFX_AUTODETECT_WINDOWED, o
puede mirar la documentación específica de su plataforma para tener una
lista los drivers disponibles. Los parámetros w y h especifican que
resolución de pantalla quiere.
Los parámetros v_w y v_h especifican el tamaño mínimo de la pantalla virtual, en caso de que necesite una pantalla virtual grande para hacer scroll por hardware o intercambio de páginas. Debería ponerlos a cero si no le importa la pantalla virtual. Las pantallas virtuales crean mucha confusión, pero en realidad son muy simples. Aviso: ahora viene una explicación condescendiente, por lo que quizás quiera saltarse el resto del párrafo :-) Imagínese la memoria de vídeo como una pieza rectangular de papel que es vista a través de un pequeño agujero (su monitor) hecho sobre cartón. Ya que el papel es más grande que el agujero, sólo puede ver una parte de él cada vez, pero moviendo el cartón puede alterar qué porción está visualizando. Puede dejar el agujero en una posición e ignorar el resto de la memoria de vídeo no visible, pero puede conseguir una gran variedad de útiles efectos desplazando la ventana de visualización, o dibujando en una parte de la memoria de vídeo no visible, y entonces intercambiar páginas para visualizar la nueva pantalla.
Por ejemplo, puede seleccionar el modo 640x480 en el cual el monitor actúa como una ventana sobre la pantalla virtual de 1024x1024, y entonces mover la pantalla visible dentro del área grande. Inicialmente, la parte visible está posicionada en la parte superior izquierda de la memoria de vídeo. Esta configuración sería así:
(0,0)------------(640,0)----(1024,0) | | | | pantalla visible | | | | | (0,480)----------(640,480) | | | | resto de la memoria de vídeo | | | (0,1024)--------------------(1024,1024)¿Qué es eso? ¿Está viendo esto con una fuente proporcional? Jejeje.
Cuando llama set_gfx_mode(), los parámetros v_w y v_h representan el tamaño mínimo de la pantalla virtual que es aceptable para su programa. El rango de tamaños posibles es normalmente muy restringido, y es posible que Allegro acabe creando una pantalla virtual más grande que la que solicitó. En una SVGA con una mega de vram cuente con conseguir una pantalla virtual de 1024x1024 (256 colores) o 1024x512 (15 o 16 bpp), y con 512k de ram puede conseguir 1024x512 (256 colores). Otros tamaños pueden ser y no ser posibles: no asuma que vayan a funcionar. En modo-X la anchura virtual puede ser cualquier múltiplo de 8 mayor o igual a la anchura de la pantalla, y la altura virtual se ajustará de la misma forma (la VGA tiene 256k de vram, por lo que la altura virtual será 256*1024/virtual_width).
Después de seleccionar el modo gráfico, los tamaños físicos y virtuales de la pantalla pueden obtenerse mediante las macros SCREEN_W, SCREEN_H, VIRTUAL_W, y VIRTUAL_H.
Si Allegro no es capaz de seleccionar un modo apropiado, set_gfx_mode() devuelve un modo negativo y almacena la descripción del problema en allegro_error. De otro modo devuelve cero.
Como caso especial, si usa el código de driver mágico GFX_SAFE, Allegro garantizará que el modo siempre será establecido correctamente. Intentará seleccionar la resolución que pidió, y si falla, usará aquella resolución que sea fiable en la plataforma actual (esto es modo VGA a 320x200 bajo DOS, una resolución de 640x480 bajo Windows, la resolución actual del framebuffer bajo Linux si está soportada, etc). Si no puede establecer ningún modo gráfico de ninguna manera, devolverá un valor negativo indicando que debería abortar inmediatamente su programa, posiblemente tras informar al usuario de este hecho mediante allegro_message. Este driver falso es útil para situaciones en las que quiere establecer un modo gráfico que funcione, y no puede perder el tiempo probando diferentes resoluciones y haciendo la comprobación de errores. Tenga en cuenta, que tras una llamada con éxito a set_gfx_mode con este driver, no puede hacer ninguna asunción sobre el ancho o alto de la pantalla o su profundidad de color: su código deberá tratar con este pequeño detalle.
int set_display_switch_mode(int mode);
Establece de qué forma el programa debe manejar el hecho de ser enviado a
un segundo plano si el usuario cambia a otro programa. No todos los modos
posibles serán soportados por cada driver gráfico en cada plataforma:
debe llamar a esta rutina tras iniciar el modo gráfico y si pide un modo
que no es posible, esta rutina devolverá -1. Los modos disponibles son:
int set_display_switch_callback(int dir, void (*cb)());
Instala una función de notificación para el cambio de modo que fue
previamente seleccionado por set_display_switch_mode(). El parámetro
direction puede ser SWITCH_IN o SWITCH_OUT, dependiendo de si quiere ser
avisado cuando se deje su programa o cuando se vuelva a él. A veces puede
instalar funciones para las dos direcciones, pero no todas las plataformas
las soportan, así esta función puede devolver -1 si su petición es
imposible. Puede instalar diferentes funciones de cambio de modo al mismo
tiempo.
void remove_display_switch_callback(void (*cb)());
Elimina una función de notificación que fue previamente instalada mediante
set_display_switch_callback(). Todas las funciones serán eliminadas
automáticamente cuando llame a set_display_switch_mode().
int get_display_switch_mode();
Devuelve el modo de cambio de pantalla, en el mismo formato que se pasa a
set_display_switch_mode().
extern int gfx_capabilities;
Campo de bits describiendo las capacidades del controlador gráfico y el
hardware de video actuales. Puede contener cualquiera de los siguientes
bits:
GFX_CAN_SCROLL:
Indica que la función scroll_screen() puede ser usada con este
controlador.
GFX_CAN_TRIPLE_BUFFER:
Indica que las funciones request_scroll() y poll_scroll() se pueden
usar con este driver. Si este bit no está activado es posible que la
función enable_triple_buffer() sea capaz de activarlo.
GFX_HW_CURSOR:
Indica que un puntero de ratón por hardware está siendo usado. Cuando
este bit esté activado, puede dibujar sin problemas en la pantalla sin
tener que ocultar antes el puntero del ratón. Tenga en cuenta que no
todo cursor gráfico puede ser implementado via hardware: en particular,
VBE/AF sólo soporta imágenes de 2 colores y de hasta 32x32 pixels,
donde el segundo color es un inverso exacto del primero. Esto significa
que Allegro puede necesitar alternar entre cursores por hardware o
software en cualquier punto durante la ejecución de su programa, por lo
que no debe asumir que este bit será constante durante largos periodos
de tiempo. Sólo le dice si un cursor hardware está siendo usado ahora,
y puede cambiar cuando oculte/enseñe el puntero.
GFX_HW_HLINE:
Indica que la versión opaca normal de la función hline() está
implementada usando aceleración por hardware. Esto incrementará el
rendimiento, no sólo de hline(), sino también de otras funciones que
la usen internamente, por ejemplo circlefill(), triangle(), y
floodfill().
GFX_HW_HLINE_XOR:
Indica que la versión XOR de la función hline(), y cualquier otra que
la use, estan implementadas usando aceleración por hardware.
GFX_HW_HLINE_SOLID_PATTERN:
Indica que los modos sólidos y con patrones de la función hline(), y
cualquier otra función que la use, estan implementadas usando
aceleración por hardware (lea nota abajo).
GFX_HW_HLINE_COPY_PATTERN:
Indica que el modo copia de patrón de la función hline(), y cualquier
otra función que la use, estan implementadas usando aceleración por
hardware (lea nota abajo).
GFX_HW_FILL:
Indica que la versión opaca de las funciones rectfill(), clear_bitmap()
y clear_to_color(), están implementadas usando aceleración por
hardware.
GFX_HW_FILL_XOR:
Indica que la versión XOR de la función rectfill() está implementada
usando aceleración por hardware.
GFX_HW_FILL_SOLID_PATTERN:
Indica que los modos sólidos y con patrones de la función rectfill()
están implementados usando aceleración por hardware (lea nota abajo).
GFX_HW_FILL_COPY_PATTERN:
Indica que el modo copia de patrón de la función rectill() está
implementado usando aceleración por hardware (lea nota abajo).
GFX_HW_LINE:
Indica que la versión opaca de las funciones line() y vline() está
implementada usando aceleración por hardware.
GFX_HW_LINE_XOR:
Indica que la versión XOR de las funciónes line() y vline() está
implementada usando aceleración por hardware.
GFX_HW_TRIANGLE:
Indica que la versión opaca de la función triangle() está implementada
usando aceleración por hardware.
GFX_HW_TRIANGLE_XOR:
Indica que la versión XOR de la función triangle() está implementada
usando aceleración por hardware.
GFX_HW_GLYPH:
Indica que la expansión de carácter monocromo (para dibujo de texto)
está implementada usando aceleración hardware.
GFX_HW_VRAM_BLIT:
Indica que hacer un blit desde una parte de la pantalla a otra está
implementado usando aceleración por hardware. Si este bit está
activado, hacer blits dentro de la memoria de vídeo será ciertamente
el modo más rápido para enseñar una imagen, por lo que sería útil
almacenar parte de sus gráficos más usados en una posición oculta de
la memoria de vídeo.
GFX_HW_VRAM_BLIT_MASKED:
Indica que la rutina masked_blit() es capaz de hacer una copia de una
parte de vídeo a otra usando aceleración por hardware, y que
draw_sprite() usará copia por hardware cuando un sub-bitmap de la
pantalla o un bitmap de memoria de vídeo sea la imagen origen. Si este
bit está activado, el copiar desde la memoria de vídeo será casi
seguramente el modo más rápido para visualizar una imagen, por lo que
podría ser rentable almacenar algunos de sus sprites más usados en una
porción no visible de la memoria de vídeo.
Aviso: ísi esta bit no está activado, masked_blit() y draw_sprite() no funcionarán correctamente cuando los use con la memoria de vídeo como bitmap origen! Sólo puede usar estas funciones para copiar memoria de vídeo si están soportadas por el hardware.
GFX_HW_MEM_BLIT:
Indica que hacer un blit desde un bitmap de memoria a la pantalla usa
aceleración por hardware.
GFX_HW_MEM_BLIT_MASKED:
Indica que masked_blit() y draw_sprite() usan aceleración por hardware
cuando la imagen fuente es un bitmap de memoria, y la imagen destino
es la pantalla física.
GFX_HW_SYS_TO_VRAM_BLIT:
Indica que hacer un blit desde un bitmap de sistema a la pantalla está
acelerado por hardware. Note que puede haber alguna aceleración incluso
si este bit no está activado, porque los bitmaps de sistema también se
pueden beneficiar del blit de memoria normal a la pantalla. Este bit
sólo estará activado si los bitmaps de sistema una aceleración mayor
que la proporcionada por GFX_HW_MEM_BLIT.
GFX_HW_SYS_TO_VRAM_BLIT_MASKED:
Indica que las funciones masked_blit() y draw_sprite() están siendo
aceleradas por hardware cuando la imagen fuente es un bitmap de sistema
y el destino es la pantalla física. Note que puede haber alguna
aceleración incluso si este bit no está activado, porque los bitmaps de
sistema también se pueden beneficiar del blit de memoria normal a la
pantalla. Este bit sólo estará activado si los bitmaps de sistema
una aceleración mayor que la proporcionada por GFX_HW_MEM_BLIT_MASKED.
Nota: incluso cuando la información diga que el dibujo con patrón está soportado usando aceleración por hardware, no será posible para cualquier tamaño de patrón. El controlador VBE/AF sólo soporta patrones de hasta 8x8 pixels, y usará la versión original no acelerada por hardware de las rutinas de dibujo siempre que use patrones más grandes.
Nota2: estas características de aceleración por hardware sólo surtirán efecto cuando dibuje directamente sobre la pantalla física, o un sub-bitmap de ésta. La aceleración por hardware es útil sobre todo con una configuración de cambio de páginas o triple buffer, y probablemente no habrá diferencia de rendimiento con el sistema "dibuja en un bitmap de memoria, entonces cópialo a la pantalla".
int enable_triple_buffer();
Si el bit GFX_CAN_TRIPLE_BUFFER de la variable gfx_capabilities no está
activado, puede intentar activarlo llamando esta función. En particular,
si está trabajando en modo-X bajo DOS puro, esta rutina activará el
simulador de retrazo temporizado, el cual entonces activará las funciones
de triple buffering. Devuelve cero si el triple buffering está activado.
int scroll_screen(int x, int y);
Intenta hacer un scroll de la pantalla para mostrar una parte diferente de
la pantalla virtual (que inicialmente se posicionará en 0,0, que es la
esquina superior izquierda). Devuelve cero si ha tenido éxito: puede
fallar si el controlador gráfico no soporta scroll por hardware o la
pantalla virtual no es lo suficientemente grande. Puede usar esta función
para mover la pantalla por un espacio de pantalla virtual grande, o para
hacer un intercambio de páginas entre dos áreas de pantalla virtual que
no estén solapadas. Tenga en cuenta que para dibujar fuera de la posición
original de la pantalla deberá alterar el área de recorte: mire abajo.
El scroll en Modo-X es de fiar y funcionará en cualquier tarjeta. Desafortunadamente la mayoría de las implementaciones VESA sólo pueden hacer scroll horizontal en incrementos de cuatro pixels, así que hacer un scroll suave en modos SVGA es imposible. Es vergonzoso, pero no veo forma de solucionarlo. Un numero significativo de implementaciones VESA parecen tener muchos fallos cuando hay que hacer scroll en modos truecolor, por lo que recomiendo no usar esta rutina en modos truecolor a menos que esté seguro de que Scitech Display Doctor está instalado.
Allegro se ocupará de cualquier sincronización del retrazo vertical cuando hago un scroll de pantalla, así que no necesita llamar a vsync() antes. Esto significa que scroll_screen() tiene los mismos efectos de retraso que vsync().
int request_scroll(int x, int y);
Esta función es usada para el triple buffering. Hace una petición de
scroll por hardware a la posición especificada, pero vuelve inmediatamente
en vez de esperar un retrazo. El scroll tendrá lugar durante el siguiente
retrazo vertical, pero puede seguir ejecutando su código mientras y usar
la rutina poll_scroll() para detectar cuando ha ocurrido el cambio por
scroll (vea examples/ex3buf.c). El triple buffering sólo es posible en
cierto hardware: funcionará en cualquier resolución de modo-X si el
simulador de retrazo esta activo(pero no funciona bien bajo win95), y está
suportado por los controladores VBE 3.0 y VBE/AF para un número limitado
de tarjetas gráficas de alto nivel. Puede mirar el bit
GFX_CAN_TRIPLE_BUFFER del campo de bits gfx_capabilities para ver si
funcionará con el controlador actual. Esta función devuelve cero si no
hubo problemas.
int poll_scroll();
Esta función es usada con triple buffering. Comprueba el estado de un
scroll por hardware iniciado previamente por la rutina request_scroll(),
devolviendo no-cero si todavía está esperando a que ocurra, y cero si ya
ha ocurrido.
int show_video_bitmap(BITMAP *bitmap);
Solicita intercambiar la página de pantalla hardware para visualizar el
objeto bitmap de vídeo especificado, que debe tener el mismo tamaño que
la pantalla física, y debe haber sido obtenido usando la función
create_video_bitmap(). Devuelve cero si no hubo problemas. Esta función
esperará un retrazo vertical si su tarjeta de vídeo lo requiere, por lo
que no hace falta que llame vsync() manualmente.
int request_video_bitmap(BITMAP *bitmap);
Esta función se usa con triple buffering. Solicita intercambiar la página
de pantalla al objeto bitmap de vídeo especificado, pero retorna
inmediatamente en vez de esperar el retrazo. El intercambio tendrá lugar
con el siguiente retrazo vertical, pero puede mientras puede seguir
ejecutando su código y usar la rutina poll_scroll() para detectar cuándo
ocurre el intercambio realmente. Triple buffering sólo es posible en
determinado hardware: mire los comentarios de request_scroll(). Devuelve
cero si no hubo problemas.