LWXGL Window API Reference

The window API covers creating and destroying the X11 window, running the frame loop, spawning modal dialogs, managing the 16-color palette, and forcing image redraws. All G* functions must be called after a successful GCreateWindow, except where noted.

`GCreateWindow`

int GCreateWindow(int w, int h, const char* name, int bgcol)

Opens an X11 window of the given size and title. Allocates the back-buffer pixmap, loads the 9x15 bitmap font, and allocates all 16 palette colors in the default X11 colormap. The window is fixed-size — it cannot be resized by the user. Must be called before any other G* function.

int

required

Width of the window in pixels.

int

required

Height of the window in pixels.

name

const char*

required

String displayed in the window title bar.

bgcol

int

required

Background palette index (0–15). This color fills the window each frame before elements are rendered.

Returns: 0 on success. Error codes:

Code	Meaning
`1`	`XOpenDisplay` failed — no X11 display available.
`2`	Font load failed — `9x15` bitmap font not found.
`3`	A window is already open.

int result = GCreateWindow(800, 600, "My App", 0); // black background
if (result != 0) {
    fprintf(stderr, "GCreateWindow failed: %d\n", result);
    return 1;
}

`GTerminateWindow`

void GTerminateWindow(void)

Frees all resources created by GCreateWindow and any subsequent element-creation calls. Specifically:

Deletes all registered UI elements.
Frees the X11 font, GC, back-buffer pixmap, and stipple pixmap.
Frees all 16 allocated X11 colors from the colormap.
Destroys the window and closes the display connection.

Call this after the main loop exits (i.e., after GSimpleWindowLoop returns, or after your manual loop ends).

GSimpleWindowLoop(60, on_frame);
GTerminateWindow();

`GWindowShouldClose`

int GWindowShouldClose(void)

Returns 1 when a window-close has been requested and accepted, 0 otherwise. Use this as the exit condition for a manual event loop. Returns: 1 if the window should close, 0 if it should keep running.

while (!GWindowShouldClose()) {
    GHandleWindowEvents();
    GRenderWindow();
}

`GHandleWindowEvents`

void GHandleWindowEvents(void)

Drains the X11 event queue, dispatching each pending event to the appropriate internal handler. Events processed include:

Expose — triggers an immediate render.
MotionNotify / LeaveNotify — updates the tracked cursor position.
ButtonPress / ButtonRelease — updates mouse_down, routes clicks to widgets or GEventAttachClick callback.
KeyPress / KeyRelease — updates the pressed_keys array, routes characters to input/console elements or GEventAttachKey callback.
ClientMessage — handles WM_DELETE_WINDOW (close button).

Call once per frame before GRenderWindow.

`GRenderWindow`

void GRenderWindow(void)

Performs a full frame render:

Fills the back-buffer pixmap with the background palette color.
Renders all non-NULL visible elements in ascending ID order.
Draws any active modal dialog on top.
If the debug overlay is enabled (toggled with F12 inside GSimpleWindowLoop), draws the FPS and frame-time graph.
Blits the back-buffer to the screen using XCopyArea and flushes with XSync.

Call once per frame after GHandleWindowEvents.

`GDeleteWindow`

void GDeleteWindow(void)

Requests that the window close. Behavior depends on whether a delete callback has been registered:

If GEventAttachDelete has been called, the registered on_exit() callback is invoked. Its return value becomes the close flag: return 1 to allow the close, 0 to cancel it.
If no delete callback is registered, the close flag is set to 1 immediately.

This function is called automatically by the internal WM_DELETE_WINDOW handler when the user clicks the window’s × button, and also on Ctrl+Escape. You can call it directly to trigger a programmatic close.

`GSimpleWindowLoop`

void GSimpleWindowLoop(int target_fps, void (*on_every)(int))

Runs the application’s main loop, blocking until GWindowShouldClose() returns 1. Each frame:

Calls GHandleWindowEvents().
Calls GRenderWindow().
Calls on_every(tick) if non-NULL, where tick is a monotonically incrementing counter starting at 0.

Timing uses std::chrono::steady_clock with sleep/yield to achieve the requested frame rate without busy-waiting. The F12 key toggles the debug overlay (FPS counter and 60-frame work-time graph) while the loop is running.

target_fps

int

required

Desired frames per second (e.g. 60).

on_every

void (*)(int)

required

Per-frame callback receiving the current tick count. Pass NULL to skip.

void on_frame(int tick) {
    // game/app logic here; tick increments each frame
}

GSimpleWindowLoop(60, on_frame);

`GSpawnModal`

void GSpawnModal(int type, const char* msg, void (*on_confirm)(void))

Displays a modal dialog over the window. While a modal is open, all keyboard and click events are consumed by the modal and are not forwarded to element callbacks or user-provided event handlers.

type

int

required

Dialog type: 0 = informational (OK button only); 1 = confirmation (OK + Cancel buttons).

msg

const char*

required

Message string shown in the dialog body. Use \n for line breaks.

on_confirm

void (*)(void)

required

Callback invoked when the user clicks OK. Pass NULL if no action is needed.

// Informational dialog
GSpawnModal(0, "File saved successfully.", NULL);

// Confirmation dialog with callback
void do_quit(void) { GDeleteWindow(); }
GSpawnModal(1, "Are you sure you want to quit?", do_quit);

`GQueryModalOpen`

int GQueryModalOpen(void)

Returns: 1 if a modal dialog is currently displayed, 0 otherwise. Useful for suppressing custom logic that should not run while the user is interacting with a dialog.

if (!GQueryModalOpen()) {
    // safe to update game state
}

`GRedrawAllImages`

void GRedrawAllImages(void)

Forces a full repaint of every image element on the next render pass by resetting each image’s dirty-pixel cache (sets all previous-pixel bytes to 255). This triggers GUpdateImage internally for each image element. Called automatically by GPaletteModify (when redraw is non-zero) and by GPaletteReset. You only need to call it directly if you modify image pixel data outside of those functions and need to guarantee a complete refresh.

`GPaletteQuery`

void GPaletteQuery(int idx, unsigned char* r, unsigned char* g, unsigned char* b)

Reads the current RGB values of palette entry idx back from the X11 colormap.

idx

int

required

Palette index to query, in the range 0–15.

unsigned char*

required

Output pointer for the red channel (0–255).

unsigned char*

required

Output pointer for the green channel (0–255).

unsigned char*

required

Output pointer for the blue channel (0–255).

unsigned char r, g, b;
GPaletteQuery(7, &r, &g, &b);
printf("Palette 7: rgb(%d, %d, %d)\n", r, g, b);

`GPaletteModify`

void GPaletteModify(int idx, unsigned char r, unsigned char g, unsigned char b, int redraw)

Replaces palette entry idx with a new RGB color. Frees the old X11 color allocation and allocates the new one in the default colormap.

idx

int

required

Palette index to modify, in the range 0–15.

unsigned char

required

New red channel value (0–255).

unsigned char

required

New green channel value (0–255).

unsigned char

required

New blue channel value (0–255).

redraw

int

required

Pass 1 to call GRedrawAllImages() after the update so image elements reflect the new color immediately. Pass 0 to skip.

// Change palette entry 4 to a custom red and repaint images
GPaletteModify(4, 220, 30, 30, 1);

`GPaletteReset`

void GPaletteReset(void)

Restores all 16 palette entries to their built-in default values (the CGA-style palette defined at library initialization) and calls GRedrawAllImages(). The default palette is:

Index	Name	RGB
0	Black	`(0, 0, 0)`
1	Dark Blue	`(3, 3, 173)`
2	Dark Green	`(0, 170, 0)`
3	Dark Cyan	`(0, 168, 168)`
4	Dark Red	`(186, 6, 6)`
5	Dark Magenta	`(168, 0, 168)`
6	Orange	`(230, 126, 34)`
7	Light Gray	`(168, 168, 168)`
8	Dark Gray	`(85, 87, 83)`
9	Light Blue	`(87, 87, 255)`
10	Light Green	`(85, 255, 85)`
11	Light Cyan	`(96, 240, 240)`
12	Light Red	`(255, 85, 85)`
13	Light Magenta	`(240, 84, 240)`
14	Yellow	`(244, 242, 54)`
15	White	`(255, 255, 255)`

Window

Elements

Events & Input

Primitives & Palette

LWXGL Window API Reference

`GCreateWindow`

`GTerminateWindow`

`GWindowShouldClose`

`GHandleWindowEvents`

`GRenderWindow`

`GDeleteWindow`

`GSimpleWindowLoop`

`GSpawnModal`

`GQueryModalOpen`

`GRedrawAllImages`

`GPaletteQuery`

`GPaletteModify`

`GPaletteReset`

Build docs developers (and LLMs) love

Window

Elements

Events & Input

Primitives & Palette

Documentation Index

​GCreateWindow

​GTerminateWindow

​GWindowShouldClose

​GHandleWindowEvents

​GRenderWindow

​GDeleteWindow

​GSimpleWindowLoop

​GSpawnModal

​GQueryModalOpen

​GRedrawAllImages

​GPaletteQuery

​GPaletteModify

​GPaletteReset

Build docs developers (and LLMs) love

`GCreateWindow`

`GTerminateWindow`

`GWindowShouldClose`

`GHandleWindowEvents`

`GRenderWindow`

`GDeleteWindow`

`GSimpleWindowLoop`

`GSpawnModal`

`GQueryModalOpen`

`GRedrawAllImages`

`GPaletteQuery`

`GPaletteModify`

`GPaletteReset`