void set_color_depth(int depth);
Sets the pixel format to be used by subsequent calls to set_gfx_mode()
and create_bitmap(). Valid depths are 8 (the default), 15, 16, 24, and 32
bits.
int set_gfx_mode(int card, int w, int h, int v_w, int v_h);
Switches into graphics mode. The card parameter should be one of the
values:
GFX_TEXT - return to text mode GFX_AUTODETECT - let Allegro pick an appropriate graphics driver GFX_VGA - select VGA mode 13h (320x200 or 320x100) GFX_MODEX - select a planar, tweaked VGA mode GFX_VESA1 - use the VESA 1.x driver GFX_VESA2B - use the VBE 2.0 banked mode driver GFX_VESA2L - use the VBE 2.0 linear framebuffer driver GFX_VBEAF - use the VBE/AF accelerator API (unfinished) GFX_XTENDED - use the unchained mode 640x400 driver GFX_ATI - use the ATI 18800/28800 driver GFX_MACH64 - use the ATI mach64 driver GFX_CIRRUS64 - use the Cirrus 64xx driver GFX_CIRRUS54 - use the Cirrus 54xx driver GFX_PARADISE - use the Paradise driver GFX_S3 - use the S3 driver GFX_TRIDENT - use the Trident driver GFX_ET3000 - use the Tseng ET3000 driver GFX_ET4000 - use the Tseng ET4000 driver GFX_VIDEO7 - use the Video-7 driverThe w and h parameters specify what screen resolution you want. Possible modes are:
"Some time ago, putting illegal or unsupported values or combinations of such into the video card registers might prove hazardous to both your monitor and your health. I have *never* claimed that bad things can't happen if you use TWEAK, although I'm pretty sure it never will. I've never heard of any damage arising from trying out TWEAK, or from general VGA tweaking in any case."
For example, you could select a 640x480 mode in which the monitor acts as a window onto a 1024x1024 virtual screen, and then move the visible screen around in this larger area. Initially, with the visible screen positioned at the top left corner of video memory, this setup would look like:
(0,0)------------(640,0)----(1024,0) | | | | visible screen | | | | | (0,480)----------(640,480) | | | | the rest of video memory | | | (0,1024)--------------------(1024,1024)What's that? You are viewing this with a proportional font? Hehehe.
When you call set_gfx_mode(), the v_w and v_h parameters represent the minimum size of virtual screen that is acceptable for your program. The range of possible sizes is usually very restricted, and Allegro is likely to end up creating a virtual screen much larger than the one you request. On an SVGA card with one megabyte of vram you can count on getting a 1024x1024 virtual screen (256 colors) or 1024x512 (15 or 16 bpp), and with 512k vram you can get 1024x512 (256 color). Other sizes may or may not be possible: don't assume that they will work. In mode-X the virtual width can be any multiple of eight greater than or equal to the physical screen width, and the virtual height will be set accordingly (the VGA has 256k of vram, so the virtual height will be 256*1024/virtual_width).
After you select a graphics mode, the physical and virtual screen sizes can be checked with the macros SCREEN_W(), SCREEN_H(), VIRTUAL_W(), and VIRTUAL_H().
If Allegro is unable to select an appropriate mode, set_gfx_mode() returns a negative number and stores a description of the problem in allegro_error. Otherwise it returns zero.
int scroll_screen(int x, int y);
Attempts to scroll the hardware screen to display a different part of the
virtual screen (initially it will be positioned at 0, 0, which is the top
left corner). Returns zero on success: it may fail if the graphics driver
can't handle hardware scrolling or the virtual screen isn't large enough.
This function will wait for a vertical retrace if the graphics card
requires it, so you don't need to call vsync() yourself. You can use this
to move the screen display around in a large virtual screen space, or to
page flip back and forth between two non-overlapping areas of the virtual
screen. Note that to draw outside the original position in the screen
bitmap you will have to alter the clipping rectangle: see below.
Mode-X scrolling is reliable and will work on any card. Unfortunately a lot of VESA implementations (including UniVBE!) can only handle horizontal scrolling in four pixel increments, so smooth horizontal panning is impossible. This is a shame, but I can't see any way round it. A significant number of VESA implementations seem to be very buggy when it comes to scrolling in truecolor video modes, so I suggest you don't depend on this routine working correctly in the truecolor resolutions unless you can be sure that UniVBE is installed.
Allegro will handle any necessary vertical retrace synchronisation when scrolling the screen, so you don't need to call vsync() before it. This means that scroll_screen() has the same time delay effects as vsync().
void request_modex_scroll(int x, int y);
This function can only be used in mode-X, and if the vertical retrace
interrupt simulator is active. It requests a hardware scroll to the
specified position, but returns immediately rather than waiting for a
retrace. The scroll will take place during the next vertical retrace.
This function is useful for implementing triple buffering (see
examples/ex20.c).
int poll_modex_scroll();
This function can only be used in mode-X, and if the vertical retrace
interrupt simulator is active. It returns non-zero if the hardware scroll
previously set by request_modex_scroll() is still waiting to take place,
and zero if it has already happened.
void split_modex_screen(int line);
This function is only available in mode-X. It splits the VGA display into
two parts at the specified line. The top half of the screen can be
scrolled to any part of video memory with the scroll_screen() function,
but the part below the specified line number will remain fixed and will
display from position (0, 0) of the screen bitmap. After splitting the
screen you will generally want to scroll so that the top part of the
display starts lower down in video memory, and then create two
sub-bitmaps to access the two sections (see examples/ex19.c for a
demonstration of how this could be done). To disable the split, call
split_modex_screen(0).