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.

Image canvases are pixel-addressable bitmap elements. Each pixel stores a palette index (0–15); LWXGL maps those indices to actual RGB colors when flushing to the display. After writing pixels or drawing primitives, call GUpdateImage to push the changes to screen. The update is diffed against the previous state — only modified pixels incur an XPutPixel call, keeping redraws efficient.

​
GCreateImage

void GCreateImage(int id, int x, int y, int w, int h);
Creates an image canvas element. Internally this allocates an XImage, a flat pixel data buffer of w * h bytes (one byte per pixel, holding a palette index), and a matching dirty-tracking “prev” buffer initialized to zero.
​
id
int
required
Element ID. If an element already exists at this ID it is deleted and replaced.
​
x
int
required
Left edge of the canvas in window pixels.
​
y
int
required
Top edge of the canvas in window pixels.
​
w
int
required
Canvas width in pixels.
​
h
int
required
Canvas height in pixels.
Example 
GCreateImage(0, 0, 0, 320, 200);

​
GGetImageData

unsigned char* GGetImageData(int id);
Returns a pointer to the flat pixel buffer of the image canvas. The buffer has w * h bytes. The pixel at canvas coordinate (x, y) is at index y * w + x and contains a palette index in the range 0–15. Writes to this buffer are staged in memory. Call GUpdateImage to flush staged changes to the screen.
​
id
int
required
ID of an existing image canvas element.
Returns: unsigned char* — pointer to the element’s internal pixel buffer. Do not free this pointer. Example 
unsigned char* pixels = GGetImageData(0);
int w = 320;

// Paint a single pixel at (10, 20) with palette color 4
pixels[20 * w + 10] = 4;

GUpdateImage(0);

​
GUpdateImage

void GUpdateImage(int id);
Diffs the current pixel buffer against the previous state and calls XPutPixel only for pixels that have changed. After processing, the prev buffer is synchronized with the current buffer. This makes repeated calls cheap when few pixels change between frames. Call this function after any modification to the pixel buffer (via direct writes, GClearImage, or the drawing primitives in the Primitives API).
​
id
int
required
ID of an existing image canvas element.
Example 
GClearImage(0, 0);
GPrimitiveRect(0, 10, 10, 50, 50, 7, 2);
GUpdateImage(0);

​
GClearImage

void GClearImage(int id, int c);
Fills the entire pixel buffer with palette index c using memset. This is a fast bulk-fill — memset works correctly here because each pixel is exactly one byte. This function does not call GUpdateImage. Call it explicitly afterwards to push the cleared canvas to the screen.
​
id
int
required
ID of an existing image canvas element.
​
c
int
required
Palette index (0–15) to fill every pixel with.
Example 
GClearImage(0, 0);  // fill with color 0 (black)
GUpdateImage(0);

​
GRedrawAllImages

void GRedrawAllImages(void);
Marks all image canvas elements as fully dirty — by setting every byte in their prev buffers to 255 — and then calls GUpdateImage for each. Because 255 is not a valid palette index, every pixel is treated as changed, forcing a complete repaint. Use this after GPaletteModify or GPaletteReset to re-render all images with updated palette colors. (Note: GPaletteModify accepts a redraw flag that does this automatically when set to 1.) Example 
// Shift the entire palette and repaint all canvases
GPaletteModify(3, 255, 128, 0, 0);
GRedrawAllImages();

​
GImageSetFont

void GImageSetFont(int id, unsigned char* font, int h);
Attaches a raw bitmap font to an image canvas element for use with GDrawString. The font buffer is copied internally, so the caller’s buffer may be freed after this call. Font buffer format: 256 * h bytes total — 256 character slots × h bytes per character. Each byte encodes one horizontal row of the glyph as an 8-bit bitmask, MSB first (bit 7 = leftmost pixel). If a font was previously attached to this element, its buffer is freed before the new one is copied.
​
id
int
required
ID of an existing image canvas element.
​
font
unsigned char*
required
Pointer to a 256 * h byte bitmap font buffer.
​
h
int
required
Glyph height in pixels (rows per character).
Example 
// font_data is a 256 * 8 = 2048 byte buffer
GImageSetFont(0, font_data, 8);

​
GDrawString

void GDrawString(int id, int x, int y, const char* txt, int color);
Renders a null-terminated string into the image canvas at (x, y) using the bitmap font attached with GImageSetFont. Only set bits in each glyph row bitmap are painted — unset bits leave the canvas pixel unchanged, giving natural transparency.
  • Character width: 9 px (8 px glyph + 1 px spacing).
  • Newlines (ASCII code 10, \n) advance the Y position by the font height and reset X to the original x argument.
  • Pixels that fall outside the canvas bounds are silently clipped.
  • Requires GImageSetFont to have been called on the same element beforehand.
​
id
int
required
ID of an existing image canvas element with a font attached.
​
x
int
required
Left edge of the first character within the canvas.
​
y
int
required
Top edge of the first character within the canvas.
​
txt
const char*
required
Null-terminated string to render.
​
color
int
required
Palette index (0–15) used for all set glyph pixels.
Example 
// Assume font_data is a 256 * 8 byte bitmap font buffer
GCreateImage(0, 0, 0, 320, 200);
GImageSetFont(0, font_data, 8);

GClearImage(0, 0);
GDrawString(0, 10, 10, "Hello, LWXGL!", 15);
GDrawString(0, 10, 25, "Second line.", 12);
GUpdateImage(0);

Build docs developers (and LLMs) love

Get started for freeTalk to us