LWXGL Window Management API — CreateWindow Reference

The window management API is the entry point for every LWXGL application. These functions handle creating the X11 window, running the frame loop, and tearing everything down cleanly. All other elements and events operate within the context established by CreateWindow and driven by MainWindowLoop.

Constants

FLAG_* — Window Flags

Pass these as a bitmask to the f parameter of CreateWindow.

Constant	Value	Description
`FLAG_NONE`	`0`	Default — no special behaviour.
`FLAG_BYPASS`	`1 << 0`	Skips the back-buffer rendering pipeline; your `on_every` callback is called directly with `XSync`, useful for custom rendering.
`FLAG_CANVAS`	`1 << 1`	Automatically creates a full-window image element at ID 0, giving you a raw pixel canvas.
`FLAG_RESIZE`	`1 << 2`	Allows the window to be resized by the user. Without this flag, WM resize hints lock the window to its creation dimensions.

CLR_* — Color Palette Indices

LWXGL maintains a 16-color palette (indices 0–F) allocated from the X colormap at startup. Use these constants wherever a color parameter is required.

Constant	Index	Color
`CLR_BLACK`	`0x0`	Black
`CLR_BLUE`	`0x1`	Blue
`CLR_GREEN`	`0x2`	Green
`CLR_CYAN`	`0x3`	Cyan
`CLR_RED`	`0x4`	Red
`CLR_MAGENTA`	`0x5`	Magenta
`CLR_ORANGE`	`0x6`	Orange
`CLR_LGRAY`	`0x7`	Light gray
`CLR_GRAY`	`0x8`	Gray
`CLR_LBLUE`	`0x9`	Light blue
`CLR_LGREEN`	`0xA`	Light green
`CLR_LCYAN`	`0xB`	Light cyan
`CLR_LRED`	`0xC`	Light red
`CLR_LMAGENTA`	`0xD`	Light magenta
`CLR_YELLOW`	`0xE`	Yellow
`CLR_WHITE`	`0xF`	White

CLR_NONE (-1) is a special sentinel meaning “no color / skip draw”, accepted by shape and element functions.

XConnectionData Struct

GetXConnection fills this struct with the raw Xlib handles managed by LWXGL. Defined only when XlibSpecificationRelease is available (i.e., when <X11/Xlib.h> has been included before libLWXGL.h).

typedef struct {
    Pixmap       bb;        /* Back-buffer pixmap used for double-buffering */
    XFontStruct* font;      /* Currently active font (9x15 or 9x15bold)     */
    Display*     dpy;       /* Connection to the X server                   */
    Window       win;       /* The application window handle                */
    GC           gc;        /* The graphics context used for all drawing    */
    unsigned long clrs[16]; /* Allocated pixel values for CLR_* indices     */
    int          scrn;      /* Default screen number                        */
    Visual*      vis;       /* Default visual                               */
    int          depth;     /* Pixel depth of the screen                    */
    Colormap     cmap;      /* Colormap in use                              */
} XConnectionData;

The handles inside XConnectionData are owned by LWXGL. Do not free or destroy them directly — use TerminateWindow() for teardown.

Functions

CreateWindow

Opens a new X11 window, allocates the 16-color palette, loads the default font, and prepares the back-buffer pixmap. Must be called before any other LWXGL function.

int CreateWindow(int w, int h, const char* name, int bgcolor, int f);

int

required

Width of the window in pixels.

int

required

Height of the window in pixels.

name

const char*

required

Title string shown in the window’s title bar. Passed directly to XStoreName.

bgcolor

int

required

Background clear color used every frame. One of the CLR_* palette constants. This can be changed later with SetWindowColor.

int

required

Bitmask of FLAG_* constants. Pass FLAG_NONE (or 0) for default behaviour.

Return codes

Code	Meaning
`0`	Success.
`1`	`XOpenDisplay` failed — no X display available.
`2`	Font `9x15` could not be loaded.
`3`	A window is already open (only one window is supported).
`127 + N`	`XAllocColor` failed for palette index `N`. Any colors already allocated (indices `0` through `N-1`) are freed before returning.

TerminateWindow

Destroys all elements, frees all allocated TGAs, releases the modal state, unloads the font, frees the graphics context and back-buffer pixmap, releases all 16 palette colors from the colormap, destroys the X window, and closes the display connection.

void TerminateWindow(void);

Call TerminateWindow after MainWindowLoop returns to release all X resources cleanly before your process exits.

MainWindowLoop

Runs the blocking frame loop at the requested frame rate. On each frame, X events are processed, the back-buffer is cleared, elements are rendered, your callback is invoked, and queued tasks are dispatched. The loop exits when DeleteWindow (or the WM close button) signals a close.

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

target_fps

int

required

Target frame rate in frames per second. LWXGL uses a sleep/yield strategy to stay close to this rate without busy-waiting.

on_every

void (*)(int tick, float delta_time)

required

Callback invoked once per frame. tick is a monotonically increasing frame counter starting at 0. delta_time is the actual elapsed time since the previous frame, in seconds. May be NULL if you only need element rendering.

DeleteWindow

Signals the frame loop to exit. If an EventAttachDelete callback has been registered, it is called first; if it returns 0 the close is cancelled.

void DeleteWindow(void);

SetWindowTitle

Updates the window title bar text at runtime.

void SetWindowTitle(const char* title);

title

const char*

required

New title string. Passed to XStoreName; the caller retains ownership.

SetWindowColor

Changes the background clear color used at the start of every frame. The new color takes effect from the next frame.

void SetWindowColor(int color);

color

int

required

One of the CLR_* palette constants.

ChangeCursor

Sets the mouse cursor shown inside the window using an X cursor font glyph index.

void ChangeCursor(int cursor_font_glyph);

cursor_font_glyph

int

required

Glyph index from the X cursor font (see <X11/cursorfont.h>). Common values: 68 = standard left-pointer arrow (set automatically by CreateWindow). The special value 255 hides the cursor entirely by creating a 1×1 blank pixmap cursor.

SetGlobalBold

Switches the font used for all text rendering between the normal and bold variants. Affects all TextElement instances and immediate-mode text drawn in the current and future frames.

int SetGlobalBold(int bold);

bold

int

required

Pass 1 to load 9x15bold; pass 0 to revert to 9x15.

Returns 1 on success, or 0 if the requested font could not be loaded (the previous font remains active).

GetXConnection

Fills a caller-provided XConnectionData struct with the Xlib handles currently managed by LWXGL. Use this to interoperate with raw Xlib code or third-party libraries that need the display/window/GC directly.

void GetXConnection(XConnectionData* data);

data

XConnectionData*

required

Pointer to a caller-allocated XConnectionData struct. All fields are overwritten on return.

This function is only declared when XlibSpecificationRelease is defined — ensure you include <X11/Xlib.h> before libLWXGL.h.

Code Example

#include <X11/Xlib.h>
#include "libLWXGL.h"
#include <stdio.h>

static void on_frame(int tick, float dt) {
    /* Called every frame. tick=0 on first frame. */
    if (tick == 0) {
        printf("Window is running\n");
    }
}

int main(void) {
    /* Create a 800×600 window, dark-gray background, no special flags */
    int result = CreateWindow(800, 600, "My LWXGL App", CLR_GRAY, FLAG_NONE);
    if (result != 0) {
        fprintf(stderr, "CreateWindow failed: %d\n", result);
        return 1;
    }

    /* Run at 60 FPS until the window is closed */
    MainWindowLoop(60, on_frame);

    /* Release all X resources */
    TerminateWindow();
    return 0;
}

Window & Lifecycle

UI Elements

Graphics & Images

Events & Input

Utilities

LWXGL Window Management API — CreateWindow Reference

Constants

FLAG_* — Window Flags

CLR_* — Color Palette Indices

XConnectionData Struct

Functions

CreateWindow

TerminateWindow

MainWindowLoop

DeleteWindow

SetWindowTitle

SetWindowColor

ChangeCursor

SetGlobalBold

GetXConnection

Code Example

Build docs developers (and LLMs) love

Window & Lifecycle

UI Elements

Graphics & Images

Events & Input

Utilities

Documentation Index

​Constants

​FLAG_* — Window Flags

​CLR_* — Color Palette Indices

​XConnectionData Struct

​Functions

​CreateWindow

​TerminateWindow

​MainWindowLoop

​DeleteWindow

​SetWindowTitle

​SetWindowColor

​ChangeCursor

​SetGlobalBold

​GetXConnection

​Code Example

Build docs developers (and LLMs) love

Constants

FLAG_* — Window Flags

CLR_* — Color Palette Indices

XConnectionData Struct

Functions

CreateWindow

TerminateWindow

MainWindowLoop

DeleteWindow

SetWindowTitle

SetWindowColor

ChangeCursor

SetGlobalBold

GetXConnection

Code Example