Screen (Graphics)

Initializes a graphics mode using QB-like mode numbers

Syntax
   -lang fb|fblite dialects:
      Screen mode [, [ depth ] [, [ num_pages ] [, [ flags ] [, [ 
      refresh_rate ]]]]]
      Screen , [ active_page ] [, [ visible_page ]]
   -lang qb dialect:
      Screen [ mode ] [, [ colormode ] [, [ active_page ] [, [ visible_page 
      ]]]]
 
Parameters
   mode 
      is a QB style graphics screen mode number (see below).  If mode is 0, 
      then any currently set graphics mode is closed, and all functions 
      resume their normal console-mode functionality.  See below for 
      available modes.
   depth
      is the color depth in bits per pixel.  This only has an effect for 
      modes 14 and higher.  Values of 8, 16 and 32 are allowed.  15 and 24 
      are also allowed as aliases for 16 and 32, respectively.  If omitted, 
      it defaults to 8.
   num_pages
      is the number of video pages you want, see below.  If omitted, it 
      defaults to 1.
   flags
      Are used to select several things as graphics driver priority, 
      fullscreen mode. There are constants predefined in the fbgfx.bi file 
      ready to use.  See the page ScreenRes for available flags.
   refresh_rate
      requests a refresh rate.  If it is not available in the present card 
      or the parameter is omitted, FreeBASIC chooses the rate 
      automatically.
   active_page
      Used to set the active page, where printing/drawing commands take 
      effect
   visible_page
      Used to set the visible page, which is shown to the user
   colormode
      Unused - allowed for compatibility with the QB syntax

Description
   Screen tells the compiler to link the GfxLib and initializes a QB-only, 
   QB-on-GUI or OpenGL graphics mode, depending on the flags setting.

   In QB-only modes a dumb window or fullscreen resolution is set, one or 
   more buffers in standard memory are created, console commands are 
   redirected to their graphic versions, a default palette is set and an 
   automatic screen refresh thread is started.  QB-like graphics and 
   console statements can be used.

   In QB-on-GUI modes one or more buffers in standard memory are created, 
   console commands are redirected to their graphic versions and a 
   default palette is set.  QB-like graphics and console statements can be 
   used.  It is up to the user to create a window and to refresh it with 
   the contents of the graphics buffers.

   In OpenGL modes a dumb window or fullscreen resolution is set, one or 
   more buffers in standard memory are created, and the OS's OpenGL library 
   is initialized.  From here only OpenGL commands can be used; QB-like and 
   console commands are forbidden.  This allows to initialize OpenGL in a 
   portable way; you can then also use ScreenControl to properly customize 
   the GL pixel format to be used before Screen is called or to retrieve 
   the list of supported OpenGL extensions after a mode has been set, and 
   ScreenGLProc to obtain extension function pointers.

   Any buffer that is created in standard memory uses one of three 
   supported internal pixel formats, depending on the desired color depth; 
   see Internal pixel formats for details.

   If Screen fails to set the required mode, an "Illegal function call" 
   error is issued and the screen pointer is set to 0. Thus Screen failures 
   can be detected using standard On Error processing or retrieving the 
   screen pointer with ScreenPtr.

   Before setting a fullscreen mode the program should check if that mode 
   is available in the graphics card using ScreenList.

mode details
   Available modes list:
   QB compatibility modes:
   +-------+----------+---------+--------------+-----------+----------------------------------------+
   |Mode nr|Resolution|Emulation|Text          |char size  |colors on screen                        |
   |1      |320x200   |CGA      |40X25         |8x8        |16 background, 1 of four sets foreground|
   |2      |640x200   |CGA      |80x25         |8x8        |16 colors to 2 attributes               |
   |7      |320x200   |EGA      |40x25         |8x8        |16 colors to 16 attributes              |
   |8      |640x200   |EGA      |80x25         |8x8        |16 colors to 16 attributes              |
   |9      |640x350   |EGA      |80x25 0r 80x43|8x14 or 8x8|16 colors to 16 attributes              |
   |11     |640x480   |VGA      |80x30 or 80x60|8x16 or 8x8|256K colors to 2 attributes             |
   |12     |640x480   |VGA      |80x30 or 80x60|8x16 or 8x8|256K colors to 16 attributes            |
   |13     |320x200   |MCGA     |40X25         |8X8        |256K colors to 256 attributes           |
   +-------+----------+---------+--------------+-----------+----------------------------------------+

   New FreeBASIC modes:
   +-------+----------+---------+-----------------+-----------+---------------------------------------------+
   |Mode nr|Resolution|Emulation|Text             |char size  |colors on screen                             |
   |14     |320x240   |         |40x30            |8x8        |256K colors to 256 attributes or direct color|
   | 15    |400x300   |         |50x37            |8x8        |256K colors to 256 attributes or direct color|
   | 16    |512x384   |         |64x24 or 64x48   |8x16 or 8x8|256K colors to 256 attributes or direct color|
   |17     |640x400   |         |80x25 or 80x50   |8x16 or 8x8|256K colors to 256 attributes or direct color|
   |18     |640x480   |         |80x30 or 80x60   |8x16 or 8x8|256K colors to 256 attributes or direct color|
   | 19    |800x600   |         |100x37 or 100x75 |8x16 or 8x8|256K colors to 256 attributes or direct color|
   |20     |1024x768  |         |128x48 or 128x96 |8x16 or 8x8|256K colors to 256 attributes or direct color|
   | 21    |1280x1024 |         |160x64 or 160x128|8x16 or 8x8|256K colors to 256 attributes or direct color|
   +-------+----------+---------+-----------------+-----------+---------------------------------------------+
 

depth details
   For modes 14 and up, the depth parameter changes the color depth to the 
   specified new one; if depth is not specified, these modes run in 8bpp.  
   For modes 13 and below, depth has no effect.

num_pages details
   You can request any number of pages for any video mode; if you omit the 
   parameter, only the visible page (number 0) will be available.  A page 
   is either the visible screen or an offscreen buffer, you can show a page 
   while working on another one; see the ScreenSet statement for details.  
   All pages are created in standard memory, the video card memory is never 
   used for video buffering.

flags details:
   (documented at the page ScreenRes)

Other details
   While in windowed mode, clicking on the window close button will add a 
   keypress of (Chr(255) & "k") to the Inkey buffer.  Clicking on the 
   Maximize window button will switch to fullscreen mode if possible.  A 
   successful Screen call sets currently visible and working pages both to 
   page number 0, resets the palette to the specified mode one (see 
   Default palettes), resets the clipping region to the size of the screen, 
   disables custom coordinates mappings, moves the graphics cursor to the 
   center of the screen, moves the text cursor to the top-left corner of 
   the screen (but never visible on any graphics screen), and sets 
   foreground and background colors to bright white and black respectively.

Note on using Screen 0
   Screen 0 closes any graphics window, but also clears the console window 
   if it exists.
   Screen 0, , , GFX_SCREEN_EXIT (with GFX_SCREEN_EXIT=&h80000000) also 
   closes any graphics window, but does not clear the console window if it 
   exists (previous text is preserved).

Example
   ' Sets screen mode 13 (320*200, 8bpp)
   Screen 13
   Print "Screen mode 13 set"

   Sleep

   #include "fbgfx.bi"
   #if __FB_LANG__ = "fb"
   Using FB '' Screen mode flags are in the FB namespace in lang FB
   #endif

   ' Sets screen mode 18 (640*480) with 32bpp color depth and 4 pages, in windowed mode; switching disabled
   Screen 18, 32, 4, (GFX_WINDOWED Or GFX_NO_SWITCH)

   ' Check to make sure Screen was opened successfully
   If ScreenPtr = 0 Then
      Print "Error setting video mode!"
      End
   End If

   Print "Successfully set video mode"
   Sleep

Platform Differences
   * In DOS, Windowing and OpenGL related switches are not available, and 
     other issues, see GfxLib overview

Dialect Differences
   * In the -lang fb and -lang fblite dialects, the usage is:
      Screen mode [, [depth] [, [num_pages] [, [flags] [, [refresh_rate
      ]]]]]
   or:
      Screen , [active_page] [, [visible_page]]]

   * In the -lang qb dialect, the usage is:
      Screen [mode] [, [colormode] [, [active_page] [, [visible_page]]]]

Differences from QB
   * None in the -lang qb dialect.
   * In QB the syntax was Screen mode,colormode,active_page,visible_page. 
     Of those parameters FreeBASIC supports only mode and redefines the 
     rest. The use of Screen , , apage,vpage to swap screen pages is only 
     available in the -lang qb dialect.
   * ScreenSet should be used in the -lang fb and -lang fblite dialects.

See also
   * Screen (Console)
   * ScreenRes More flexible alternative to Screen
   * ScreenList Check display modes available for FB GfxLib to use
   * ScreenControl Select driver and more 
   * ScreenLock
   * ScreenUnlock
   * ScreenPtr Semi-low level access
   * ScreenSet
   * ScreenCopy
   * ScreenInfo
   * ScreenGLProc
   * Internal pixel formats

