Screen (Graphics)
Initializes a graphics mode using QB-like mode numbers
Screen mode [, [ depth ] [, [ num_pages ] [, [ flags ] [, [ refresh_rate ]]]]]
mode
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 OpenGL 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:
New FreeBASIC modes:
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:
If flags are omitted, FreeBASIC uses QB-compatible graphics in windowed (except in DOS) mode. These constants are defined in fbgfx.bi. In the -lang fb dialect, these constants are part of the FB Namespace. Note that most of the flags are not supported in DOS.
Available flags:
graphic mode flags
Graphics mode console
Console commands (Locate, Print), input can be used both with standard QB Screen modes and with the extended ones too, provided the standard color depth is not modified by using the second argument of Screen. Where the table says more than one text resolution is available for the text mode, the required text resolution can be requested by using Width. Any characters Printed will erase the background around them; it does not use a transparent background.
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 and sets foreground and background colors to bright white and black respectively.
Syntax
Screen mode [, [ depth ] [, [ num_pages ] [, [ flags ] [, [ refresh_rate ]]]]]
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.
depthis 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_pagesis the number of video pages you want, see below. If omitted, it defaults to 1.
flagsAre used to select several things as graphics driver, fullscreen mode. There are constants predefined in the fbgfx.bi file ready to use. See below for available flags.
refresh_raterequests a refresh rate. If it is not available in the present card or the parameter is omitted, FreeBASIC chooses the rate automatically.
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 OpenGL 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 | 40x25 | 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:
If flags are omitted, FreeBASIC uses QB-compatible graphics in windowed (except in DOS) mode. These constants are defined in fbgfx.bi. In the -lang fb dialect, these constants are part of the FB Namespace. Note that most of the flags are not supported in DOS.
Available flags:
graphic mode flags
GFX_NULL: Starts a QB-on-GUI graphics mode. It creates a graphics buffer but not a window. User must implement the window, the events manager and and refresh screen as needed. This mode allows to mix FreeBASIC drawing functions with API-driven windows. This flag overrides all other mode flags. See an Example of GFX_NULL in Windows.
GFX_OPENGL: Initializes OpenGL to draw in a dumb window. FreeBASIC graphic functions can't be used. The screen is not automatically updated, Flip must be used. This option provides a portable way to initialize the OpenGL Library.
If none of the above options is specified, FreeBASIC enters the QB-only graphics mode: it creates a buffer and a dumb window and sets a thread that automatically updates the screen and manages keyboard and mouse. The FreeBASIC drawing functions can be used.
window mode flagsGFX_OPENGL: Initializes OpenGL to draw in a dumb window. FreeBASIC graphic functions can't be used. The screen is not automatically updated, Flip must be used. This option provides a portable way to initialize the OpenGL Library.
If none of the above options is specified, FreeBASIC enters the QB-only graphics mode: it creates a buffer and a dumb window and sets a thread that automatically updates the screen and manages keyboard and mouse. The FreeBASIC drawing functions can be used.
Window mode flags are meaningless if GFX_NULL mode is used
GFX_WINDOWED: If windowed mode is supported, FreeBASIC opens a window of the requested size in the present desktop
GFX_FULLSCREEN: The graphics card switch mode is switched to the requested mode and color depth and OS fullscreen mode is used. If the mode is not available in the present card FreeBASIC switches to windowed mode.
If GFX_FULLSCREEN is not specified, the behavior for GFX_WINDOWED is assumed.
GFX_NO_SWITCH: Prevents the user from changing to fullscreen or to windowed mode by pressing Alt-Enter.
GFX_NO_FRAME: Creates a window without a border.
GFX_SHAPED_WINDOW: Creates transparent regions wherever RGBA(255, 0, 255, 0) is drawn on the screen.
GFX_ALWAYS_ON_TOP: Creates a window that stays always on top.
option flagsGFX_WINDOWED: If windowed mode is supported, FreeBASIC opens a window of the requested size in the present desktop
GFX_FULLSCREEN: The graphics card switch mode is switched to the requested mode and color depth and OS fullscreen mode is used. If the mode is not available in the present card FreeBASIC switches to windowed mode.
If GFX_FULLSCREEN is not specified, the behavior for GFX_WINDOWED is assumed.
GFX_NO_SWITCH: Prevents the user from changing to fullscreen or to windowed mode by pressing Alt-Enter.
GFX_NO_FRAME: Creates a window without a border.
GFX_SHAPED_WINDOW: Creates transparent regions wherever RGBA(255, 0, 255, 0) is drawn on the screen.
GFX_ALWAYS_ON_TOP: Creates a window that stays always on top.
Flags working in any mode, they activate special behaviors
GFX_ALPHA_PRIMITIVES: Tells the graphics library to enable alpha channel support for all drawing primitives. This means the alpha specified in a color value (via either the RGBA macro or direct color in the form &hAARRGGBB) will always be used by all primitives.
GFX_HIGH_PRIORITY: Tells the graphics library to enable a higher priority for graphics processing. Only has an effect on gdi and DirectX drivers on Win32 platform.
OpenGL Buffer flagsGFX_ALPHA_PRIMITIVES: Tells the graphics library to enable alpha channel support for all drawing primitives. This means the alpha specified in a color value (via either the RGBA macro or direct color in the form &hAARRGGBB) will always be used by all primitives.
GFX_HIGH_PRIORITY: Tells the graphics library to enable a higher priority for graphics processing. Only has an effect on gdi and DirectX drivers on Win32 platform.
These flags work only in OpenGL graphics mode, must be combined with GFX_OPENGL
GFX_STENCIL_BUFFER: Forces OpenGL to use Stencil buffer
GFX_ACCUMULATION_BUFFER: Forces OpenGL to use Accumulation buffer
GFX_MULTISAMPLE: Requests fullscreen anti-aliasing through the ARB_multisample extension
Depending on whether the GFX_FULLSCREEN parameter is present or not, Screen will try to set the specified video mode in fullscreen or windowed mode, respectively. If fullscreen mode is set and the system cannot set specified mode in fullscreen, it'll try in windowed mode. If windowed mode is set and the system fails to open a window for specified mode, it will try fullscreen. If everything fails, Screen will have no effect and execution will resume from the statement following the Screen call. You should take care of checking if a graphics mode has been set or not, and behave accordingly; a way to check if Screen is successful is to test the return value of the ScreenPtr function; see its page for details.GFX_STENCIL_BUFFER: Forces OpenGL to use Stencil buffer
GFX_ACCUMULATION_BUFFER: Forces OpenGL to use Accumulation buffer
GFX_MULTISAMPLE: Requests fullscreen anti-aliasing through the ARB_multisample extension
Graphics mode console
Console commands (Locate, Print), input can be used both with standard QB Screen modes and with the extended ones too, provided the standard color depth is not modified by using the second argument of Screen. Where the table says more than one text resolution is available for the text mode, the required text resolution can be requested by using Width. Any characters Printed will erase the background around them; it does not use a transparent background.
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 and sets foreground and background colors to bright white and black respectively.
Example
' Sets screen mode 13 (320*200, 8bpp)
Screen 13
Print "Screen mode 13 set"
Sleep
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
#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, see also GfxLib overview
Dialect Differences
- In the -lang fb and -lang fblite dialects, the usage is:
Screen mode [, [ depth ] [, [ num_pages ] [, [ flags ] [, [ refresh_rate ]]]]]
- In the -lang qb dialect, the usage is:
Screen [mode] [,[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
