Skip to main content

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.

LWXGL windows are backed by a double-buffered Xlib pixmap. Each frame your code calls GHandleWindowEvents to drain the event queue, then GRenderWindow to composite all visible elements onto the backbuffer and blit it to the screen. GSimpleWindowLoop handles this automatically when you don’t need manual frame control.

​
GCreateWindow

int GCreateWindow(int w, int h, const char* name, int bgcol);
Opens the X11 display connection, allocates the 16-color palette, creates the window, loads the 9x15 bitmap font, and creates the backbuffer pixmap. The window is mapped immediately and is non-resizable by default — XSizeHints are set so that both the minimum and maximum size equal w × h. Call GEnableResizing afterward to lift that constraint.
​
w
int
required
Width of the window in pixels.
​
h
int
required
Height of the window in pixels.
​
name
const char*
required
Title string displayed in the window’s title bar. Passed directly to XStoreName.
​
bgcol
int
required
Background fill color as a palette index in the range 0–15. This is the color used to clear the backbuffer at the start of every GRenderWindow call.
Return values
ValueMeaning
0Success.
1XOpenDisplay failed — no X11 display available.
2Font load failed — the 9x15 bitmap font could not be found.
3A window already exists. Only one window is supported per process.
127 + iColor allocation failed for palette index i. All previously allocated colors are freed before returning.
Only one window may exist at a time. A second call to GCreateWindow without an intervening GTerminateWindow returns 3 immediately without touching the display.
Example 
#include "libLWXGL.h"
#include <stdio.h>

int main(void) {
    int rc = GCreateWindow(800, 600, "My App", 0);
    if (rc != 0) {
        fprintf(stderr, "GCreateWindow failed: %d\n", rc);
        return 1;
    }

    GSimpleWindowLoop(60, NULL);
    GTerminateWindow();
    return 0;
}

​
GTerminateWindow

void GTerminateWindow();
Tears down everything allocated by GCreateWindow. In order: deletes all registered UI elements, frees the font, frees the graphics context, frees the backbuffer pixmap, frees all 16 palette colors, destroys the window, and closes the display connection.
Always call GTerminateWindow after the main loop exits. Skipping it leaks X11 resources and may leave orphaned server-side objects.
Example 
GSimpleWindowLoop(60, NULL);
GTerminateWindow(); /* clean up before exit */

​
GWindowShouldClose

int GWindowShouldClose();
Returns the current value of the internal close flag. The flag is set by:
  • The WM sending a WM_DELETE_WINDOW client message.
  • A direct call to GDeleteWindow.
  • The user pressing Ctrl + Escape.
Use this function as the condition of a manual render loop. Returns 1 when the window should close, 0 otherwise. Example 
while (!GWindowShouldClose()) {
    GHandleWindowEvents();
    GRenderWindow();
    /* your per-frame logic */
}

​
GHandleWindowEvents

void GHandleWindowEvents();
Drains the Xlib event queue for the current frame using XPending / XNextEvent. Every pending event is dispatched to the appropriate internal handler before the function returns. Handles:
  • ButtonPress / ButtonRelease — mouse button state and UI element interaction.
  • MotionNotify — cursor position tracking.
  • LeaveNotify — resets cursor position to -1, -1 when the pointer leaves the window.
  • KeyPress / KeyRelease — keyboard state tracking and user key callback.
  • ConfigureNotify — window resize (coalesces multiple events, recreates the backbuffer, fires the resize callback).
  • ClientMessage — WM close protocol.
Call GHandleWindowEvents once per frame, before GRenderWindow. Calling it multiple times per frame is safe but redundant since all pending events are consumed in a single call.
Example 
while (!GWindowShouldClose()) {
    GHandleWindowEvents();
    GRenderWindow();
}

​
GRenderWindow

void GRenderWindow();
Composites the current frame onto the backbuffer pixmap and then presents it:
  1. Fills the entire backbuffer with the background color set by GSetWindowColor (or the bgcol passed to GCreateWindow).
  2. Draws every visible element whose screen field matches the active screen.
  3. If a modal is open, draws the modal dialog on top.
  4. If the debug overlay is enabled (toggled with F12), draws the FPS counter and frame-time graph.
  5. Blits the completed backbuffer to the window via XCopyArea.
GRenderWindow always clears the backbuffer first, so you do not need to manually erase previous frames.
Example 
while (!GWindowShouldClose()) {
    GHandleWindowEvents();
    GRenderWindow();
}

​
GSimpleWindowLoop

void GSimpleWindowLoop(int target_fps, void (*on_every)(int, float));
A ready-made main loop that calls GHandleWindowEvents and GRenderWindow every frame, then invokes on_every, and sleeps just long enough to honour target_fps. The loop exits when GWindowShouldClose returns 1. Frame timing uses std::chrono::steady_clock. If a frame runs long enough to fall two frame-periods behind, the internal time base is reset to prevent a catch-up spiral.
​
target_fps
int
required
Desired frame rate cap. For example, 60 caps the loop at approximately 60 Hz.
​
on_every
void (*)(int, float)
required
Callback invoked once per frame after events and rendering. Pass NULL if you need no per-frame logic.
  • tick — zero-indexed frame counter, incremented each frame.
  • delta_time — elapsed seconds since the previous frame (e.g. 0.01667 at 60 fps).
GSimpleWindowLoop enables the debug overlay data collection automatically. Press F12 at runtime to toggle the overlay.
Example 
void on_frame(int tick, float dt) {
    /* update game state, move elements, etc. */
    (void)tick;
    (void)dt;
}

int main(void) {
    GCreateWindow(800, 600, "Demo", 0);
    GSimpleWindowLoop(60, on_frame);
    GTerminateWindow();
    return 0;
}

​
GDeleteWindow

void GDeleteWindow();
Sets the close flag so that GWindowShouldClose returns 1 on the next check. Before setting the flag, if a delete handler was registered with GEventAttachDelete, it is called:
  • If the handler returns 1, the close proceeds.
  • If the handler returns 0, the close is blocked and the flag is not set.
If no delete handler is registered, the close is always allowed.
GDeleteWindow does not free any resources. Call GTerminateWindow after the loop exits to perform the actual cleanup.
Example 
/* Programmatically request a close (e.g. from a quit button) */
void on_quit_clicked(void) {
    GDeleteWindow();
}

​
GSetWindowTitle

void GSetWindowTitle(const char* title);
Updates the window title bar text at any time after the window has been created. Calls XStoreName directly.
​
title
const char*
required
Null-terminated string to display in the title bar.
Example 
GSetWindowTitle("My App — Level 2");

​
GSetWindowColor

void GSetWindowColor(int color);
Changes the palette index used to clear the backbuffer at the start of each GRenderWindow call. Takes effect on the very next rendered frame.
​
color
int
required
Palette index in the range 0–15.
Example 
/* Switch to a dark background */
GSetWindowColor(1);

​
GEnableResizing

void GEnableResizing(void (*Resize)(int w, int h));
Removes the PMinSize | PMaxSize size hints that GCreateWindow installs, allowing the window manager to resize the window freely. When the window is resized, GHandleWindowEvents detects the ConfigureNotify event, recreates the backbuffer pixmap at the new dimensions, and calls Resize with the new size.
​
Resize
void (*)(int w, int h)
Callback invoked whenever the window is resized. Receives the new width and height in pixels. Pass NULL to allow resizing without a callback.
Multiple rapid resize events within a single GHandleWindowEvents call are coalesced — only the final dimensions are used to recreate the pixmap and fire the callback.
Example 
void on_resize(int w, int h) {
    /* re-layout elements to fit new dimensions */
    (void)w; (void)h;
}

int main(void) {
    GCreateWindow(800, 600, "Resizable", 0);
    GEnableResizing(on_resize);
    GSimpleWindowLoop(60, NULL);
    GTerminateWindow();
    return 0;
}

​
GCaptureRegion

unsigned char* GCaptureRegion(int x, int y, int w, int h, int* size);
Captures a rectangular region of the current backbuffer and returns it as a raw PPM (P6) image in a heap-allocated buffer. The backbuffer reflects the most recently rendered frame; call this after GRenderWindow to capture a complete frame. The PPM header format is: 
P6\n<w> <h>\n255\n
followed by w × h × 3 bytes of raw RGB pixel data in row-major order.
​
x
int
required
Left edge of the capture rectangle in backbuffer coordinates.
​
y
int
required
Top edge of the capture rectangle in backbuffer coordinates.
​
w
int
required
Width of the capture rectangle in pixels.
​
h
int
required
Height of the capture rectangle in pixels.
​
size
int*
required
Output parameter. Set to the total byte count of the returned buffer (PPM header + pixel data).
Returns a malloc-allocated unsigned char* buffer containing the PPM file data. The caller is responsible for calling free() on the returned pointer.
The returned buffer is heap-allocated. Failing to free() it causes a memory leak.
Example — saving a screenshot to disk 
#include "libLWXGL.h"
#include <stdio.h>
#include <stdlib.h>

void save_screenshot(int win_w, int win_h) {
    int size = 0;
    unsigned char *ppm = GCaptureRegion(0, 0, win_w, win_h, &size);
    if (!ppm) return;

    FILE *f = fopen("screenshot.ppm", "wb");
    if (f) {
        fwrite(ppm, 1, size, f);
        fclose(f);
    }
    free(ppm);
}

​
GSpawnModal

void GSpawnModal(int type, const char* msg, void (*on_confirm)());
Opens a modal dialog rendered on top of all other content. While the modal is active, GHandleWindowEvents blocks all button clicks and key events from reaching UI elements or user callbacks — only the modal’s own click regions are active. The modal is dismissed when the user clicks a button.
​
type
int
required
Dialog style:
  • 0 — OK-only: a single “OK” button that invokes on_confirm and closes the modal.
  • 1 — Confirm/Cancel: two buttons. “Confirm” invokes on_confirm and closes the modal. “Cancel” closes the modal without invoking the callback.
​
msg
const char*
required
Message text displayed inside the dialog. Use \n for line breaks.
​
on_confirm
void (*)()
Callback invoked when the user clicks OK or Confirm. May be NULL if you only need to inform the user without triggering an action.
Example 
void do_delete(void) {
    /* perform the destructive action */
}

void prompt_delete(void) {
    GSpawnModal(1, "Delete this file?\nThis cannot be undone.", do_delete);
}

​
GQueryModalOpen

int GQueryModalOpen();
Returns the active state of the modal dialog. Returns 1 while a modal is displayed, 0 when no modal is open. Example 
void on_frame(int tick, float dt) {
    if (GQueryModalOpen()) {
        /* skip game logic while modal is blocking */
        return;
    }
    /* normal per-frame update */
}

Build docs developers (and LLMs) love

Get started for freeTalk to us