{{fbdoc item="title" value="GfxLib - FreeBASIC graphics library overview"}}----
""GfxLib"" is the built-in graphics and input library used by ""FreeBASIC"" programs that open a graphics screen with ##[[KeyPgScreengraphics|Screen]]##, ##[[KeyPgScreenres|ScreenRes]]##, or related commands.  It implements the built-in drawing commands, graphics pages, palette handling where the target supports it, keyboard input, mouse input, touch input on targets that expose it, and the platform-specific code needed to display the program's framebuffer.

GfxLib is not one single display driver.  The common runtime owns the program-visible framebuffer and dispatches presentation, input, mode enumeration, window handling, and OpenGL entry points to a driver selected for the current target.

##[[KeyPgScreencontrol|ScreenControl]]## can be used with ##SET_DRIVER_NAME## before the first graphics screen is opened to request a specific driver.  The same choice can be made from the environment by setting ##FBGFX##.  Driver names are matched case-insensitively.  ##ScreenControl## with ##GET_DRIVER_NAME## can be used after a graphics screen has opened to see which driver was selected.

Several modern backends can present a low-resolution GfxLib framebuffer inside a larger display area by using centered integer scaling.  This keeps the program's logical screen size unchanged while avoiding blurry fractional scaling.  Mouse and touch coordinates are mapped back to the logical framebuffer so ##[[KeyPgGetmouse|GetMouse]]## and touch queries still point at the same pixel the program sees.  Builds that define ##GFXLIB_NEVERSCALE## disable this presentation scaling for users who want a ##320x200## screen to remain exactly ##320x200## on the physical display or inside a maximized window.

The available driver names depend on the target and build configuration:

	- All targets:
		- **##Null##** - keeps the GfxLib framebuffer in memory without opening a real display.  This is useful for headless tests, image processing code, or targets where no display driver can be initialized.

	- Windows:
		- **##Direct2D##** - preferred by normal Win32 builds when enabled and available.
		- **##DirectX##** - the DirectDraw based driver.
		- **##GDI##** - the Win32 GDI fallback driver.
		- **##OpenGL##** - the Win32 OpenGL driver.
		- Cygwin builds use the Win32-compatible path but do not necessarily include every native Windows driver.

	- Unix/X11 family:
		- **##X11##** - the normal X11 driver.
		- **##OpenGL##** - OpenGL through X11/GLX when enabled.
		- **##FBDev##** - Linux framebuffer device support when enabled on Linux.

	- Darwin/macOS:
		- **##Darwin##** - the native Darwin graphics backend.
		- **##Null##** - fallback.

	- Haiku:
		- **##Haiku##** - the native Haiku graphics backend.
		- **##Null##** - fallback.

	- Android:
		- **##AndroidModern##** - the normal Android native-window driver.
		- **##AndroidLegacy##** - compatibility path for older Android behavior.

	- JavaScript/Emscripten:
		- **##asmjs##** - browser canvas driver.
		- **##WebGL##** - browser WebGL driver for OpenGL requests.

	- Wii:
		- **##wii##** - libogc based TV framebuffer driver.

	- Xbox:
		- **##xbox##** - original Xbox/nxdk framebuffer driver.

	- DOS:
		- **##VESA linear##** - VESA 2.0 linear framebuffer driver.
		- **##VESA banked##** - banked VESA compatibility driver.
		- **##VGA##** - standard VGA driver.
		- **##ModeX##** - tuned 320x240x8bpp VGA mode.
		- **##BIOS##** - BIOS graphics fallback.

{{fbdoc item="target"}}
	- Driver availability is a compile-time and run-time property.  A driver can be present in the binary but still fail to initialize if the operating system, display server, hardware, emulator, or browser environment does not provide what it needs.
	- On DOS, windowing and OpenGL-related options are not available.  The refresh-rate setting is also not generally available.  Programs should check whether the requested screen was opened successfully before using ##[[KeyPgScreenptr|ScreenPtr]]## or drawing into the screen.
	- On DOS, the requested resolution must match a mode supported by the video hardware or emulator.  Safe fallback modes such as 640x480 or 800x600 are more portable than vendor-specific modes.
	- On desktop/windowed backends such as Windows, X11, OpenGL-on-X11, Darwin/macOS, and Haiku, resizing or maximizing a window can keep the GfxLib framebuffer centered and integer-scaled instead of stretching it fractionally.
	- On Linux fbdev, if the driver cannot switch the real framebuffer to the exact requested mode but the current framebuffer mode is large enough, GfxLib can keep the current mode and present the requested logical screen centered at the largest integer scale that fits.
	- On JavaScript targets, the browser owns the real window, event loop, and presentation timing.  GfxLib presents through browser canvas/WebGL rather than a native desktop window.
	- On console-style targets such as Wii and Xbox, the backend presents to the target's video output and scales the GfxLib framebuffer as needed unless the runtime was built with ##GFXLIB_NEVERSCALE##.  Controller input is exposed through the target-specific input functions instead of pretending every controller is a PC keyboard.
	- On Android, touch input is available through the GfxLib touch functions, and mouse-style compatibility is provided where it makes sense.

{{fbdoc item="diff"}}
	- QuickBASIC graphics code wrote directly to VGA memory.  FreeBASIC keeps a GfxLib framebuffer and lets the selected driver copy or present that framebuffer using the current platform's display API.
	- Multiple graphics pages are still exposed to the program, but the runtime manages those pages internally instead of relying on the video card to provide QB-style page memory.
	- Some drivers update the visible screen from an event loop, timer, callback, explicit unlock, or input polling boundary.  Portable graphics code should use the normal GfxLib drawing commands, ##[[KeyPgScreenlock|ScreenLock]]##, ##[[KeyPgScreenunlock|ScreenUnlock]]##, ##[[KeyPgScreenptr|ScreenPtr]]##, ##[[KeyPgScreenset|ScreenSet]]##, and ##[[KeyPgScreencopy|ScreenCopy]]## rather than mixing GfxLib with target-specific raw video memory access.

{{fbdoc item="see"}}
	- [[CatPgGfx|GFX Functions Index]]
	- ##[[KeyPgScreengraphics|Screen (Graphics)]]## The QB-style way to set a graphics mode
	- ##[[KeyPgScreenres|ScreenRes]]## A more flexible way to open a graphics screen
	- ##[[KeyPgScreenlist|ScreenList]]## Check display modes available to GfxLib
	- ##[[KeyPgScreencontrol|ScreenControl]]## Select drivers and query graphics state
	- ##[[KeyPgScreenlock|ScreenLock]]##
	- ##[[KeyPgScreenunlock|ScreenUnlock]]##
	- ##[[KeyPgScreenptr|ScreenPtr]]## Direct access to the active framebuffer
	- ##[[KeyPgScreenset|ScreenSet]]##
	- ##[[KeyPgScreencopy|ScreenCopy]]##
	- ##[[KeyPgScreeninfo|ScreenInfo]]##
	- ##[[KeyPgScreenglproc|ScreenGLProc]]##
	- ##[[GfxInternalFormats|Internal pixel formats]]##

{{fbdoc item="back" value="CatPgProgrammer|Programmer's Guide"}}
{{fbdoc item="back" value="DevToc|FreeBASIC Developer Information"}}
{{fbdoc item="back" value="DocToc|Table of Contents"}}
