GfxLib - FreeBASIC graphics library overview
GfxLib is the built-in graphics and input library used by FreeBASIC programs that open a graphics screen with `Screen`, `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.
`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.
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.

Platform Differences

- 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 `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 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. 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.

Differences from QB

- 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, `ScreenLock`, `ScreenUnlock`, `ScreenPtr`, `ScreenSet`, and `ScreenCopy` rather than mixing GfxLib with target-specific raw video memory access.

See also

- GFX Functions Index
- `Screen (Graphics)` The QB-style way to set a graphics mode
- `ScreenRes` A more flexible way to open a graphics screen
- `ScreenList` Check display modes available to GfxLib
- `ScreenControl` Select drivers and query graphics state
- `ScreenLock`
- `ScreenUnlock`
- `ScreenPtr` Direct access to the active framebuffer
- `ScreenSet`
- `ScreenCopy`
- `ScreenInfo`
- `ScreenGLProc`
- `Internal pixel formats`