Window Management API Reference — LWXGL C Library

The window API covers all functions that manage the X11 window itself — creation, the render loop, window properties, screen management, modal dialogs, and region capture. Every other LWXGL function depends on a successfully created window, so GCreateWindow must always be the first call in your program.

GCreateWindow

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

Creates and maps the X11 window, allocates the back-buffer pixmap, loads the default 9x15 bitmap font, and allocates all 16 palette colors from the default colormap. Must be called before any other LWXGL function.

int

required

Width of the window in pixels.

int

required

Height of the window in pixels.

name

const char*

required

Initial window title bar text.

bgcol

int

required

Background fill color as a palette index (0–15). This is the color the back-buffer is cleared to on every call to GRenderWindow.

Return values

Value	Meaning
`0`	Success.
`1`	Could not open the X display — the `DISPLAY` environment variable is likely not set.
`2`	Could not load the default font (`9x15`).
`3`	A window is already open; `GCreateWindow` was called twice without an intervening `GTerminateWindow`.
`127 + i`	Could not allocate palette color `i` from the X colormap. Any colors allocated before the failure are freed before returning.

GTerminateWindow

void GTerminateWindow(void);

Shuts down the LWXGL session completely. Deletes every live element, frees all allocated TGA resources, releases the GC, back-buffer pixmap, font, and all 16 palette colors, then destroys the window and closes the X display connection. Call this once after GWindowShouldClose() returns 1 and your main loop exits.

GDeleteWindow

void GDeleteWindow(void);

Signals the window to close by setting the internal closing flag, which causes GWindowShouldClose() to return 1 on the next check. If a delete callback has been registered with GEventAttachDelete, that callback is invoked first; its return value determines whether closing is actually allowed (1 = allow, 0 = block). This function is called automatically by the library when the user clicks the window manager’s close button (the WM_DELETE_WINDOW protocol message), but you can also call it directly — for example from a quit button’s onclick handler.

GWindowShouldClose

int GWindowShouldClose(void);

Returns 1 when the window has been signaled to close, 0 otherwise. Use this as the condition of a manual render loop:

while (!GWindowShouldClose()) {
    GHandleWindowEvents();
    GRenderWindow();
    // your per-frame logic here
}
GTerminateWindow();

GHandleWindowEvents

void GHandleWindowEvents(void);

Drains the X11 event queue and dispatches every pending event to the appropriate internal handler. Processed event types include mouse button press/release, pointer motion, key press/release, ConfigureNotify (resize), and ClientMessage (window close). Call this once per frame, before GRenderWindow, so that input state and element focus are up to date when rendering begins.

GRenderWindow

void GRenderWindow(void);

Performs a full frame render into the back-buffer pixmap, then blits the result to the visible window with XCopyArea. The render sequence is:

Clear the back-buffer to the current background color.
Draw all elements whose screen field matches the active screen, or whose screen is -1 (visible on all screens).
Draw the active modal dialog, if one is open.
Draw the debug performance overlay, if enabled (toggled by pressing F12 at runtime).

GSimpleWindowLoop

void GSimpleWindowLoop(int target_fps, void (*on_every)(int tick, float delta_time));

A blocking, high-level render loop that manages frame timing automatically. Internally it calls GHandleWindowEvents and GRenderWindow each frame, then calls on_every with the current frame counter and delta time. The loop exits when GWindowShouldClose() returns 1. Frame pacing uses std::chrono monotonic timing. When the work time is shorter than the target frame duration, the loop sleeps the remaining time (minus 1 ms as a scheduling margin) and yields to other threads when the slack is very small.

target_fps

int

required

Desired frames per second. The loop targets a frame interval of 1 000 000 / target_fps microseconds.

on_every

void (*)(int tick, float delta_time)

required

Callback invoked once per frame after rendering. tick is the zero-based frame counter incremented each frame. delta_time is the elapsed time in seconds since the previous frame. Pass NULL if no per-frame callback is needed.

GSimpleWindowLoop(60, NULL); // 60 fps, no per-frame callback

// — or —

void update(int tick, float dt) {
    // game logic here
}
GSimpleWindowLoop(60, update);

GSetWindowTitle

void GSetWindowTitle(const char* title);

Updates the window title bar text by calling XStoreName. Takes effect immediately; no redraw is required.

title

const char*

required

New null-terminated title string.

GSetWindowColor

void GSetWindowColor(int color);

Sets the background clear color used by GRenderWindow. The change takes effect on the next rendered frame.

color

int

required

Palette index (0–15) to use as the new background color.

GEnableResizing

void GEnableResizing(void (*Resize)(int w, int h));

Removes the fixed-size WM hints set by GCreateWindow (which lock min and max dimensions to the initial width and height), allowing the user to freely resize the window. Registers a resize callback that is invoked after the back-buffer pixmap has been recreated for the new dimensions. Must be called after GCreateWindow.

Resize

void (*)(int w, int h)

required

Callback invoked whenever the window is resized. w and h are the new width and height in pixels. Use this callback to reposition or rescale elements that depend on window dimensions.

void on_resize(int w, int h) {
    // reposition layout elements for new w x h
}
GEnableResizing(on_resize);

GScreenActive

int* GScreenActive(void);

Returns a pointer to the internal active-screen integer. Dereference the pointer to read or write the current screen. Only elements assigned to the active screen (or to screen -1) are rendered by GRenderWindow.

int current = *GScreenActive();   // read the current screen index
*GScreenActive() = 2;             // switch to screen 2

GScreenApply

void GScreenApply(int s, int ids[], int count);

Assigns a list of elements to screen s. After this call, those elements are only rendered (and interactive) when *GScreenActive() == s. Elements with a screen value of -1 are always visible regardless of the active screen.

int

required

Screen index to assign the elements to.

ids

int[]

required

Array of element IDs to reassign.

count

int

required

Number of entries in ids.

int screen1_elems[] = {0, 1, 2};
int screen2_elems[] = {3, 4};
GScreenApply(1, screen1_elems, 3);
GScreenApply(2, screen2_elems, 2);
*GScreenActive() = 1; // show screen 1

GSpawnModal

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

Displays a blocking modal dialog rendered on top of all other elements. While a modal is active, all click and key events are consumed by the modal and not forwarded to elements or user callbacks.

type

int

required

0 — show an OK button only. 1 — show both OK and Cancel buttons.

msg

const char*

required

Message text displayed inside the modal dialog.

on_confirm

void (*)()

required

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

void do_delete(void) {
    // perform the destructive action
}
GSpawnModal(1, "Delete this file?", do_delete);

GQueryModalOpen

int GQueryModalOpen(void);

Returns 1 if a modal dialog is currently displayed, 0 otherwise. Useful for suppressing application actions that should not run while a dialog is on screen.

GCaptureRegion

unsigned char* GCaptureRegion(int x, int y, unsigned short w, unsigned short h);

Captures a rectangular region from the back-buffer and encodes it as a type-1 (color-mapped) TGA file in a heap-allocated buffer. The TGA contains an 18-byte header, a 48-byte palette (16 entries × 3 bytes BGR), and w × h bytes of palette-index pixel data. The caller is responsible for freeing the returned buffer with free().

int

required

Left edge of the capture region in back-buffer coordinates.

int

required

Top edge of the capture region in back-buffer coordinates.

unsigned short

required

Width of the region in pixels.

unsigned short

required

Height of the region in pixels.

Returns a pointer to a heap-allocated buffer of size 66 + w * h bytes containing a complete TGA file. Free with free() when done.

unsigned char* tga = GCaptureRegion(0, 0, 320, 240);
// write tga to disk or process the pixel data
free(tga);

Window

Elements

Events & Input

Palette & TGA

Window Management API Reference — LWXGL C Library

GCreateWindow

GTerminateWindow

GDeleteWindow

GWindowShouldClose

GHandleWindowEvents

GRenderWindow

GSimpleWindowLoop

GSetWindowTitle

GSetWindowColor

GEnableResizing

GScreenActive

GScreenApply

GSpawnModal

GQueryModalOpen

GCaptureRegion

Build docs developers (and LLMs) love

Window

Elements

Events & Input

Palette & TGA

Documentation Index

​GCreateWindow

​GTerminateWindow

​GDeleteWindow

​GWindowShouldClose

​GHandleWindowEvents

​GRenderWindow

​GSimpleWindowLoop

​GSetWindowTitle

​GSetWindowColor

​GEnableResizing

​GScreenActive

​GScreenApply

​GSpawnModal

​GQueryModalOpen

​GCaptureRegion

Build docs developers (and LLMs) love

GCreateWindow

GTerminateWindow

GDeleteWindow

GWindowShouldClose

GHandleWindowEvents

GRenderWindow

GSimpleWindowLoop

GSetWindowTitle

GSetWindowColor

GEnableResizing

GScreenActive

GScreenApply

GSpawnModal

GQueryModalOpen

GCaptureRegion