NAME

       set_gfx_mode - Sets a graphic video mode. Allegro game programming library.

SYNOPSIS

       #include <allegro.h>

       int set_gfx_mode(int card, int w, int h, int v_w, int v_h);

DESCRIPTION

       Switches into graphics mode. The card parameter should usually be one of the Allegro magic
       drivers (read introduction of chapter "Graphics  modes")  or  see  the  platform  specific
       documentation  for  a  list  of the available drivers. The w and h parameters specify what
       screen resolution you want.  The color depth of the  graphic  mode  has  to  be  specified
       before calling this function with set_color_depth().

       The  v_w  and  v_h  parameters specify the minimum 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.

       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 may end up creating a virtual screen much larger than the one
       you request.  Allowed sizes are driver dependent and some drivers  do  not  allow  virtual
       screens  that  are  larger  than the visible screen at all: don't assume that whatever you
       pass will always 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).

       Currently, using a big virtual screen for page flipping is considered bad practice.  There
       are  platforms which don't support virtual screens bigger than the physical screen but can
       create different video pages to flip back and forth. This means that,  if  you  want  page
       flipping  and  aren't going to use hardware scrolling, you should call set_gfx_mode() with
       (0,0) as the virtual  screen  size  and  later  create  the  different  video  pages  with
       create_video_bitmap().  Otherwise your program will be limited to the platforms supporting
       hardware scrolling.

       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.

RETURN VALUE

       Returns  zero on success. On failure returns a negative number and stores a description of
       the problem in allegro_error.

SEE ALSO

       set_color_depth(3alleg4),         request_refresh_rate(3alleg4),          screen(3alleg4),
       gfx_capabilities(3alleg4),      allegro_error(3alleg4),      create_video_bitmap(3alleg4),
       get_desktop_resolution(3alleg4), SCREEN_W(3alleg4), SCREEN_H(3alleg4), VIRTUAL_W(3alleg4),
       VIRTUAL_H(3alleg4)