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.

This guide walks you through building a minimal LWXGL application: a 400×300 window containing a text label and a button. When the button is clicked the label text updates in place — no rebuild required, just a live in-process element swap. By the end you will have a working binary that runs at 60 FPS using LWXGL’s built-in frame-capped loop.
1

Install LWXGL

Clone the repository and run the two Makefile targets to compile and install the shared library:
git clone https://github.com/Dressedalarm184/lwxgl.git
cd lwxgl
make build
sudo make install
make build compiles libLWXGL.so in the repository root. make install copies it to /usr/local/lib, copies src/libLWXGL.h to /usr/local/include, and runs ldconfig so the dynamic linker picks up the new library immediately. See Build and Install LWXGL from Source for full details.
2

Create your source file

Create a file called hello.c with the following contents:
#include <libLWXGL.h>

void on_click(void) {
    /* Replace the label text with a confirmation message.
       Color index 10 = Light Green in the default palette. */
    GCreateText(0, 20, 20, 10, "Button clicked!");
}

int main(void) {
    /* Open a 400x300 window. Background color index 0 = Black. */
    GCreateWindow(400, 300, "Hello LWXGL", 0);

    /* Create a text label at element ID 0.
       Position (20, 20), color index 15 = White. */
    GCreateText(0, 20, 20, 15, "Click the button!");

    /* Create a button at element ID 1.
       Position (150, 120), size 100x30.
       0x87 -> normal state: H=8 border (Dark Gray), L=7 fill (Light Gray)
       0x98 -> hover  state: H=9 border (Light Blue), L=8 fill (Dark Gray)
       0x97 -> pressed state: H=9 border (Light Blue), L=7 fill (Light Gray) */
    GCreateButton(1, 150, 120, 100, 30, 0x87, 0x98, 0x97, "Click me", on_click);

    /* Run the event/render loop at 60 FPS. Pass NULL for no per-frame callback. */
    GSimpleWindowLoop(60, NULL);

    /* Clean up all elements and close the X11 connection. */
    GTerminateWindow();
    return 0;
}
The program creates two elements — ID 0 (text) and ID 1 (button) — before entering the loop. on_click calls GCreateText again with the same ID 0, which replaces the existing label in-place.
3

Compile

Link against both libLWXGL and libX11:
gcc -o hello hello.c -lLWXGL -lX11
Because make install ran ldconfig, the linker can resolve -lLWXGL without any extra -L flags. If you skipped the install step you can point the linker at the repository directory directly:
gcc -o hello hello.c -L/path/to/lwxgl -lLWXGL -lX11 -Wl,-rpath,/path/to/lwxgl
4

Run

Launch the compiled binary:
./hello
A 400×300 window titled Hello LWXGL will appear. Click the Click me button and watch the label change from white “Click the button!” to green “Button clicked!”. Close the window normally — the WM close event is handled by LWXGL and exits the loop cleanly.
Tip: Press F12 while the window is open to toggle the built-in debug overlay, which displays live FPS and average per-frame work time.
Color parameters throughout the LWXGL API are palette indices in the range 0–15, not RGB values. The default 16-color palette is fixed at startup and maps to CGA-style colors (0 = Black, 7 = Light Gray, 10 = Light Green, 15 = White, and so on).For functions that take a packed color byte — such as the u, hvr, and p arguments of GCreateButton — each byte encodes two palette indices: the high nibble (bits 7–4, extracted with the H(byte) macro defined in main.cc) carries one color and the low nibble (bits 3–0, extracted with L(byte)) carries the other. For example, 0x87 means high nibble 8 (Dark Gray) and low nibble 7 (Light Gray).
GCreateButton is just one of six element types LWXGL provides. See UI Elements for a full reference covering text labels, single-line inputs, rectangles, image canvases, and checkboxes — including how to read input values with GGetInput and query checkbox state with GGetCheckbox.

Build docs developers (and LLMs) love

Get started for freeTalk to us