plucky (3) set_gfx_mode.3alleg4.gz

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)