LWXGL (Lightweight X11 GUI Library) is a small, dependency-light C/C++ shared library that lets you open an X11 window, populate it with UI elements, draw graphics, and respond to user input — all through a straightforward procedural API. It targets Linux desktops running an X11 display server and wraps Xlib directly, so there is no heavy toolkit layer between your code and the display. If you need a self-contained GUI for a tool, demo, or small game without pulling in Qt, GTK, or similar frameworks, LWXGL is designed for that use case.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
Opens a fixed-size X11 window with a configurable background palette color. The window is non-resizable by design and uses a Pixmap backbuffer for flicker-free double-buffered rendering. Teardown is handled by a single
GTerminateWindow() call.ID-Based UI Elements
Six built-in element types — text label, button, text input, checkbox, filled rectangle, and image canvas — are each created and referenced by an integer ID. Elements are stored in a flat array and can be deleted individually with
GDeleteElement(id) or repositioned at runtime with GElemModifyBounds.Image Canvas & Drawing Primitives
GCreateImage allocates a per-pixel canvas element backed by an XImage. The canvas is written to using palette-indexed drawing primitives: GPrimitiveRect, GPrimitiveCircle, GPrimitiveLine, and GPrimitiveSprite (an RLE-encoded monochrome sprite renderer with configurable scale). Call GUpdateImage to flush dirty pixels to the display.Event System
Attach persistent callbacks with
GEventAttachKey, GEventAttachClick, and GEventAttachDelete. For polling-style input, GQueryMouse returns the current cursor position and button state, GQueryKeyboard returns an 8-slot array of currently held key codes, and GQueryKeyDown tests for a specific key. Arrow and function keys are exposed via named constants such as LWXGL_KEY_LEFT and LWXGL_KEY_FN.16-Color Palette
All colors are referenced by index 0–15, a CGA-inspired set ranging from black (0) through white (15). The palette can be inspected with
GPaletteQuery, overridden per-slot with GPaletteModify, and restored to defaults with GPaletteReset. Modifying a palette slot automatically redraws all image canvases when the redraw flag is set.FPS-Capped Game Loop
GSimpleWindowLoop(target_fps, on_every) runs a blocking loop that calls GHandleWindowEvents and GRenderWindow every frame, sleeps between frames to honour the target frame rate, and invokes your optional per-tick callback with the current tick counter. A built-in debug overlay (toggle with F12) shows live FPS and average frame-time in microseconds.How It Works
Every visible element in LWXGL is identified by a non-negative integer ID that you choose at creation time. When you callGCreateButton(1, ...), the library allocates an internal Element struct at index 1 in a flat vector and stores a pointer to the button’s state. If you call GCreateButton(1, ...) again, the previous element at index 1 is freed first. This ID-based model makes it straightforward to reference, update, or delete any element later without holding C-level pointers.
Colors throughout the API are palette indices 0–15. The default palette is a 16-entry CGA-like set: index 0 is black, index 7 is light gray, index 15 is white, and so on (see the full table in the source). For elements that carry two distinct color roles — a border color and a fill color — both are packed into a single int value as a byte: the low nibble (bits 3–0) holds the fill palette index and the high nibble (bits 7–4) holds the border palette index. For example, the value 0x78 means fill = index 8 (dark gray) and border = index 7 (light gray). The macros L(b) and H(b) are used internally to extract these nibbles.
Rendering is double-buffered via a Pixmap (bb) that is the same size as the window. Each call to GRenderWindow clears the backbuffer to the background color, iterates over every element in order, dispatches to the appropriate renderer, and then copies the finished backbuffer to the visible window with XCopyArea followed by XSync. Image canvas elements are handled slightly differently: GPrimitive* functions write into a byte array of palette indices, and GUpdateImage walks only the changed pixels (comparing against a previous-state copy) to push updates into the underlying XImage.
Requirements
LWXGL requires a Linux system with a running X11 display server. The following packages must be present:
- libX11 — the core Xlib runtime and development headers (package
libx11-devon Debian/Ubuntu). - The
9x15bitmap font — loaded at window creation time viaXLoadQueryFont. This font ships with thexfonts-basepackage on Debian/Ubuntu.GCreateWindowreturns error code2if the font cannot be found.
extern "C" block.