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.

An image element is a software-rendered canvas backed by a palette-indexed pixel buffer. Every pixel is stored as a single byte holding a palette index (0–15). Changes to the pixel buffer are not visible until you call UpdateImage, which diffs the current buffer against the previous frame and only pushes changed pixels to the X server — keeping frame cost proportional to the area that actually changed.

​
CreateImage

void CreateImage(int id, int x, int y, int w, int h);
Creates a new image element at position (x, y) with dimensions w × h. Registers it in the element slot id. If w or h is zero or negative, the dimension is expanded to fill the remaining back-buffer space relative to the given offset: 
if (w <= 0) w = bb.w - x + w;
if (h <= 0) h = bb.h - y + h;
This means passing w = 0 gives a canvas that reaches the right edge of the window, and passing w = -20 leaves a 20-pixel margin on the right. Internally, CreateImage allocates:
  • An XImage (ZPixmap, display depth) for the pixel data
  • A data buffer (w * h bytes, palette indices, zero-initialised)
  • A prev buffer (w * h bytes) for diff-based dirty detection
  • An imgdata buffer (h * ximage->bytes_per_line bytes) that backs the XImage pixel storage
  • An off-screen Pixmap of the same dimensions
​
id
int
required
Element slot index. Must be unique; an existing element at this index will be replaced.
​
x
int
required
Left edge of the image, in pixels, relative to the window origin.
​
y
int
required
Top edge of the image, in pixels, relative to the window origin.
​
w
int
required
Width in pixels. Pass 0 or a negative value to expand to the back-buffer width minus x (plus w as an offset).
​
h
int
required
Height in pixels. Pass 0 or a negative value to expand to the back-buffer height minus y (plus h as an offset).

​
GetImageData

unsigned char* GetImageData(int id);
Returns a pointer to the raw pixel buffer for the image at slot id. The buffer is w * h bytes, stored in row-major order (left-to-right, top-to-bottom). Each byte is a palette index in the range 0–15. Writing directly to this buffer and then calling UpdateImage is the primary way to draw into an image element.
​
id
int
required
Element slot index of the target image.
The returned pointer is valid until DeleteElement(id) is called. Do not free() it — the buffer is owned by the element.

​
UpdateImage

void UpdateImage(int id);
Flushes changes from the pixel buffer to the display. UpdateImage compares each byte in data against the corresponding byte in prev. For each changed pixel it calls put_pixel to write the new color into the XImage, then calls XPutImage once if any pixel changed. If nothing changed, no X calls are made. Call this once per frame after all drawing operations are complete. Calling it multiple times per frame is safe but wasteful.
​
id
int
required
Element slot index of the target image.
Batch all primitive and pixel writes for a given frame before calling UpdateImage — the single diff pass is far cheaper than calling UpdateImage after every draw call.

​
ClearImage

void ClearImage(int id, int c);
Fills the entire pixel buffer with palette index c using memset. Equivalent to calling PrimitiveRect covering the whole image, but faster.
​
id
int
required
Element slot index of the target image.
​
c
int
required
Palette index (0–15) to fill with. Use the CLR_* constants for readability.

​
RedrawAllImages

void RedrawAllImages(void);
Forces a full redraw of every image element in the element list. Marks each image’s prev buffer as invalid (fills with 255) then calls UpdateImage for each, ensuring all pixels are re-pushed to the X server regardless of whether data changed. This is called automatically by PaletteModify when redraw = 1 and by PaletteReset. You rarely need to call it manually.
Because palette index 255 is not a valid 4-bit index, filling prev with 255 guarantees every pixel is treated as changed on the next UpdateImage pass.

​
SetImageFont

void SetImageFont(int id, unsigned char* font, int h);
Attaches a custom bitmap font to the image element. The font buffer must contain 256 glyphs — one per ASCII code point — each h bytes tall and 8 pixels wide. Each byte is a row of 8 pixels, MSB first (bit 7 = leftmost pixel). The buffer is copied internally, so it is safe to free() or reuse font after this call.
​
id
int
required
Element slot index of the target image.
​
font
unsigned char*
required
Pointer to the font data. Must be exactly 256 * h bytes.
​
h
int
required
Height of each glyph in pixels (i.e., the number of bytes per character).

​
DrawString

void DrawString(int id, int x, int y, const char* txt, int color);
Renders a null-terminated string into the image at (x, y) using the custom font set by SetImageFont. Each character occupies a 9-pixel-wide cell (8 pixels of glyph + 1 pixel gap). Newline characters (\n, value 10) advance y by the font height and reset the horizontal cursor. Pixels outside the image bounds are silently clipped.
​
id
int
required
Element slot index of the target image.
​
x
int
required
Left edge of the first character, in image-local coordinates.
​
y
int
required
Top edge of the first character row, in image-local coordinates.
​
txt
const char*
required
Null-terminated string to draw. Supports \n for line breaks.
​
color
int
required
Palette index (0–15) for the drawn pixels. Background pixels are not affected — only the set bits in each glyph row are written.
DrawString requires a font to have been set with SetImageFont first. Calling it without a font will access a NULL pointer and crash.

​
ApplyPixelFunc

void ApplyPixelFunc(int id, int (*f)(int x, int y, int current_color));
Iterates every pixel of the image and replaces its color with the return value of f modulo 16. The callback receives the pixel’s x and y coordinates within the image and its current palette index. Use this for palette-rotation effects, noise, and per-pixel color transformations.
​
id
int
required
Element slot index of the target image.
​
f
int (*)(int x, int y, int current_color)
required
Mapping function called for every pixel. The return value (mod 16) becomes the new palette index.

​
Code Example

#include "libLWXGL.h"
#include <string.h>

// External 8×8 font: 256 chars × 8 bytes each
extern unsigned char my_font[2048];

void on_frame(int tick, float dt) {
    // 1. Clear the canvas to black every frame
    ClearImage(1, CLR_BLACK);

    // 2. Draw some primitives
    PrimitiveRect(1, 10, 10, 100, 60, CLR_WHITE, CLR_BLUE);
    PrimitiveCircle(1, 160, 40, 30, CLR_YELLOW, CLR_ORANGE);

    // 3. Render text using the custom font
    DrawString(1, 10, 80, "Hello, LWXGL!", CLR_WHITE);

    // 4. Flush changes to the display
    UpdateImage(1);
}

int main(void) {
    CreateWindow(320, 200, "Image Demo", CLR_BLACK, FLAG_NONE);

    // Create a full-window image element in slot 1
    CreateImage(1, 0, 0, 0, 0);

    // Attach the bitmap font (8px tall glyphs)
    SetImageFont(1, my_font, 8);

    MainWindowLoop(60, on_frame);
    TerminateWindow();
    return 0;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us