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 let you draw arbitrary graphics by writing directly to a palette-index pixel array and flushing it to the screen. Each canvas is backed by an XImage and a matching byte array — you write palette indices (0–15) into the array, then call GUpdateImage to push only the changed pixels to the display. LWXGL also provides a set of GPrimitive* drawing functions that operate on image canvases: GPrimitiveRect, GPrimitiveCircle, GPrimitiveLine, and GPrimitiveSprite. See their individual entries below.

​
GCreateImage

void GCreateImage(int id, int x, int y, int w, int h)
Allocates a new image canvas element. Internally this creates an XImage of size w × h, a w*h-byte pixel array (initialized to 0), and a second copy of that array used to track which pixels have changed since the last GUpdateImage call. Pixel at position (px, py) maps to array index py * w + px.
​
id
int
required
Element slot index. If the slot is already occupied the existing element (and its XImage) is destroyed first.
​
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.
Do not use GElemModifyBounds to resize an image canvas after creation — it updates the stored dimensions but does not reallocate the underlying XImage or pixel arrays. Call GCreateImage again with the new size instead.

​
GGetImageData

unsigned char* GGetImageData(int id)
Returns a pointer to the w * h byte array of palette indices for canvas id. Write values 0–15 to this array to set pixel colors. The changes will not appear on screen until GUpdateImage is called.
​
id
int
required
Element slot index of an existing image element.
Return value: unsigned char* — pointer to the internal pixel data array. Do not free this pointer. It remains valid until the element is deleted or recreated.

​
GUpdateImage

void GUpdateImage(int id)
Scans the entire pixel array for bytes that differ from the previous-frame snapshot and calls XPutPixel only for those positions. After updating, the snapshot is synchronized with the current data. This diff-based approach is efficient for canvases where only a small region changes per frame (e.g., a moving sprite on a static background). For canvases where every pixel changes, a full XPutImage would be faster — use GUpdateImage selectively in that case.
​
id
int
required
Element slot index of an existing image element.
GUpdateImage updates the XImage data structure but does not copy it to the window. The canvas is composited onto the back-buffer during the next GRenderWindow call via XPutImage.

​
GClearImage

void GClearImage(int id, int c)
Fills the entire pixel array for canvas id with palette index c using memset. Call GUpdateImage afterwards to push the clear to the screen.
​
id
int
required
Element slot index of an existing image element.
​
c
int
required
Palette index (0–15) to fill with. Palette index 0 is typically black.

​
GPrimitiveSprite

void GPrimitiveSprite(int id, int sx, int sy, int color, const char* sprite, int scale)
Draws an RLE-encoded sprite into image canvas id. The sprite is positioned with its top-left corner at (sx, sy), drawn using the specified palette color, and scaled so that each logical pixel becomes a scale × scale block. Pixels that would fall outside the canvas bounds are clipped silently.
​
id
int
required
Element slot index of the target image canvas.
​
sx
int
required
X position (canvas-relative) of the sprite’s top-left corner.
​
sy
int
required
Y position (canvas-relative) of the sprite’s top-left corner.
​
color
int
required
Palette index (0–15) used for filled (#) pixels.
​
sprite
const char*
required
Null-terminated RLE sprite string. See the format table below.
​
scale
int
required
Pixel scale factor. 1 = 1:1, 2 = each logical pixel becomes a 2×2 block, etc.

​
RLE sprite format

TokenMeaning
#Draw one filled pixel (palette color), advance x by scale.
.Draw one background pixel (palette index 0), advance x by scale.
$Newline — reset x to sx, advance y by scale.
>Skip — advance x by scale without drawing.
N<token>Repeat <token> N times. Example: 5# = 5 filled pixels.
N[pattern]Repeat pattern N times. Example: 3[#.] = #.#.#.
!End of sprite (optional — the null terminator also stops parsing).
Example sprite strings: 
"5[5#$]"          // 5×5 filled square (5 rows of 5 filled pixels)
"3#$#.#$3#"       // 3×3 C-shape:  ###
                  //               #
                  //               ###
"3[#>]"           // 3 filled pixels with gaps: # # #
GPrimitiveSprite writes directly into the pixel array. Call GUpdateImage after all drawing is complete for a given frame to flush changes to the screen.

​
Example

// Create a 128×128 canvas at position (50, 50)
GCreateImage(0, 50, 50, 128, 128);

// Fill the canvas black (palette index 0)
GClearImage(0, 0);

// Draw a white (index 15) square outline, transparent fill
GPrimitiveRect(0, 10, 10, 50, 50, 15, -1);

// Draw a 3×3 C-shape sprite in yellow (index 14) at scale 2
GPrimitiveSprite(0, 70, 10, 14, "3#$#.#$3#", 2);

// Flush all changes to the XImage
GUpdateImage(0);

// GRenderWindow() will composite the canvas onto the window next frame

Build docs developers (and LLMs) love

Get started for freeTalk to us