LWXGL (Lightweight X11 Graphics Library) is a C/C++ shared library that wraps the low-level Xlib API into a clean, flat function interface for building windowed desktop applications and simple 2D games on Linux. Rather than requiring you to manage X11 display connections, graphics contexts, event loops, and double-buffered pixmaps yourself, LWXGL handles all of that internally and exposes a single-header API where you create windows, add UI elements by ID, and enter a frame-capped loop in a handful of function calls. It is aimed at developers who want a lightweight, dependency-minimal alternative to large GUI toolkits when building utilities, retro-style games, or embedded Linux UIs.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/dRessedAlarm184/LWXGL/llms.txt
Use this file to discover all available pages before exploring further.
Key Features
Window Management
Open a fixed-size X11 window with a title and background color in one call. LWXGL manages the display connection, graphics context, double-buffer pixmap, and WM delete protocol automatically.
Built-in UI Widgets
Six ready-to-use element types: Button (with click callback), Text label, Input field (with character limit), Checkbox, Rect (filled/bordered rectangle), and a scrolling Console widget for multi-line output.
Image Canvas & Pixel Manipulation
Create raw image surfaces by ID, read and write their pixel buffers directly with
GGetImageData, and push updates to the screen with GUpdateImage. Draw primitives — rectangles, circles, and lines — onto any canvas.Sprite Rendering
Render compact RLE-encoded sprites onto an image canvas with
GPrimitiveSprite, with configurable position, color, and integer scale factor.Event System
Attach callbacks for keyboard (
GEventAttachKey) and mouse click (GEventAttachClick) events, or poll the current mouse state with GQueryMouse and keyboard state with GQueryKeyboard / GQueryKeyDown for game-style input loops.16-Color Indexed Palette
All colors in LWXGL are referenced by an index (0–15) into a built-in 16-color palette, ranging from black (0) through standard CGA-style colors to white (15). The palette can be queried, modified per-slot at runtime, or fully reset.
FPS-Capped Loop Helper
GSimpleWindowLoop runs your application’s main loop at a target frame rate, handling event dispatch and rendering automatically each frame with precision sleep/yield scheduling. Pass an optional per-frame callback to run your own logic.Modal Dialogs & Debug Overlay
Spawn blocking modal dialogs with
GSpawnModal for confirmations and alerts. Press F12 at runtime to toggle a debug overlay displaying live FPS and a 60-frame work-time history.The Color System
LWXGL uses a 16-color indexed palette — every color argument throughout the API is an integer index from0 to 15 rather than an RGB value. The default palette is fixed at startup and covers the classic CGA color range:
| Index | Name | RGB |
|---|---|---|
| 0 | Black | #000000 |
| 1 | Dark Blue | #030373 |
| 2 | Dark Green | #00AA00 |
| 3 | Dark Cyan | #00A8A8 |
| 4 | Dark Red | #BA0606 |
| 5 | Dark Magenta | #A800A8 |
| 6 | Orange | #E67E22 |
| 7 | Light Gray | #A8A8A8 |
| 8 | Dark Gray | #555753 |
| 9 | Light Blue | #5757FF |
| 10 | Light Green | #55FF55 |
| 11 | Light Cyan | #60F0F0 |
| 12 | Light Red | #FF5555 |
| 13 | Light Magenta | #F054F0 |
| 14 | Yellow | #F4F236 |
| 15 | White | #FFFFFF |
GPaletteModify without changing any element definitions — all widgets that reference that index automatically render in the new color. Use GPaletteReset to restore the defaults.
Distribution Format
LWXGL is distributed as source and built into a compiled shared object (libLWXGL.so). The entire public API is declared in a single C header, libLWXGL.h, which uses extern "C" guards so it can be included from both C and C++ projects without any changes. Link against -lLWXGL at compile time.
LWXGL targets the X11 display protocol directly via Xlib. It is not natively compatible with Wayland compositors. On Wayland-based desktops, run your application through XWayland (
DISPLAY=:0 ./myapp or via your desktop’s XWayland compatibility layer) to use LWXGL windows.