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