Graphics modes



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 driver

The w and h parameters specify what screen resolution you want. Possible modes are:

The v_w and v_h parameters specify the minumum virtual screen size, in case you need a large virtual screen for hardware scrolling or page flipping. You should set them to zero if you don't care about the virtual screen size. Virtual screens can cause a lot of confusion, but they are really quite simple. Warning: patronising explanation coming up, so you may wish to skip the rest of this paragraph :-) Think of video memory as a rectangular piece of paper which is being viewed through a small hole (your monitor) in a bit of cardboard. Since the paper is bigger than the hole you can only see part of it at any one time, but by sliding the cardboard around you can alter which portion of the image is visible. You could just leave the hole in one position and ignore the parts of video memory that aren't visible, but you can get all sorts of useful effects by sliding the screen window around, or by drawing images in a hidden part of video memory and then flipping across to display them.

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).




Back to Contents