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.

Primitive drawing functions operate directly on the pixel buffer of an image canvas element. All functions take an element id as their first argument and write palette indices into the canvas’s flat byte buffer. None of them call GUpdateImage automatically — call it after drawing to push changes to the screen. All primitives clip silently: pixels that fall outside the canvas bounds are skipped without error.

​
GPrimitiveRect

void GPrimitiveRect(int id, int x, int y, int w, int h, int fg, int bg);
Draws a rectangle on the image canvas. fg controls the 1-pixel border; bg controls the interior fill. Either can be omitted by passing -1. When fg is -1, it is set equal to bg before drawing, producing a solid filled rectangle with no distinct border. When bg is -1, interior pixels are left untouched (transparent).
​
id
int
required
ID of the target image canvas element.
​
x
int
required
Left edge of the rectangle within the canvas.
​
y
int
required
Top edge of the rectangle within the canvas.
​
w
int
required
Width in pixels.
​
h
int
required
Height in pixels.
​
fg
int
required
Border color as a palette index. Pass -1 to draw no border (the border color will instead match bg, producing a solid fill).
​
bg
int
required
Fill color as a palette index. Pass -1 to leave interior pixels unchanged.
Example 
GCreateImage(0, 0, 0, 200, 150);

// Bordered rectangle: color-7 outline, color-2 fill
GPrimitiveRect(0, 10, 10, 80, 40, 7, 2);

// Solid fill, no separate border
GPrimitiveRect(0, 100, 10, 40, 40, -1, 5);

// Outline only, transparent interior
GPrimitiveRect(0, 10, 60, 80, 40, 12, -1);

GUpdateImage(0);

​
GPrimitiveCircle

void GPrimitiveCircle(int id, int cx, int cy, int r, int fg, int bg);
Draws a circle on the image canvas. The border is 1 pixel thick and is determined by a distance-squared check: a pixel (x, y) is on the border when (r-1)² ≤ dx² + dy² ≤ r². Interior pixels satisfy dx² + dy² ≤ r² and are painted with bg when it is not -1. Border pixels take priority over fill pixels when both conditions are satisfied.
​
id
int
required
ID of the target image canvas element.
​
cx
int
required
X coordinate of the circle center within the canvas.
​
cy
int
required
Y coordinate of the circle center within the canvas.
​
r
int
required
Radius in pixels.
​
fg
int
required
Border color as a palette index. Pass -1 to draw no border.
​
bg
int
required
Fill color as a palette index. Pass -1 to leave interior pixels unchanged.
Example 
GCreateImage(1, 50, 50, 200, 200);

// Filled circle, white border, red fill
GPrimitiveCircle(1, 100, 100, 40, 15, 4);

// Ring only (no fill)
GPrimitiveCircle(1, 100, 100, 60, 7, -1);

GUpdateImage(1);

​
GPrimitiveLine

void GPrimitiveLine(int id, int x1, int y1, int x2, int y2, int color);
Draws a straight line between two points using step-count interpolation. The number of steps is max(|dx|, |dy|) where dx = x2 - x1 and dy = y2 - y1. At each step, x and y are incremented by dx/steps and dy/steps respectively, and the nearest integer pixel is painted. This produces results equivalent to Bresenham’s line algorithm. Pixels outside the canvas bounds are skipped.
​
id
int
required
ID of the target image canvas element.
​
x1
int
required
X coordinate of the start point within the canvas.
​
y1
int
required
Y coordinate of the start point within the canvas.
​
x2
int
required
X coordinate of the end point within the canvas.
​
y2
int
required
Y coordinate of the end point within the canvas.
​
color
int
required
Palette index (0–15) for the line pixels.
Example 
GCreateImage(2, 0, 0, 320, 240);

// Diagonal cross in color 14 (yellow)
GPrimitiveLine(2, 0,   0,   320, 240, 14);
GPrimitiveLine(2, 320, 0,   0,   240, 14);

GUpdateImage(2);

​
GPrimitiveSprite

void GPrimitiveSprite(int id, int sx, int sy, int color,
                      const char* sprite, int scale);
Renders an RLE-encoded sprite onto the image canvas. The sprite string describes a 2-D pixel pattern using a compact run-length encoding. The color argument sets the foreground palette index used for # pixels. The scale factor magnifies each logical pixel into a scale × scale block of canvas pixels. Out-of-bounds pixels are clipped.
​
id
int
required
ID of the target image canvas element.
​
sx
int
required
Left edge of the sprite within the canvas. This X origin is restored at each $ (row advance).
​
sy
int
required
Top edge of the sprite within the canvas.
​
color
int
required
Palette index (0–15) used to draw # pixels.
​
sprite
const char*
required
Null-terminated RLE sprite string (see format table below).
​
scale
int
required
Pixel scale factor. 1 = 1:1, 2 = each logical pixel becomes a 2×2 block, etc.

​
Sprite RLE Format

CharacterMeaning
#Draw one pixel in color and advance X by scale.
.Draw one pixel in color 0 (black) and advance X by scale.
$Move to the start of the next row: reset X to sx, advance Y by scale. Multiple $ tokens advance multiple rows.
>Advance X by scale without drawing (transparent skip).
[...]Repeat the enclosed pattern. Combine with a leading digit to repeat N times: 3[#.] = #.#.#.. Groups can be nested.
N (digit)Repeat the immediately following character or [...] group N times. Multi-digit counts are supported (12# = 12 filled pixels).
The draw cursor starts at (sx, sy). Each $ resets X to sx and advances Y by one row (scale pixels). The > and blank regions leave underlying canvas pixels unchanged. Examples 
// 3×3 filled square (scale 1)
const char* sq = "3#$3#$3#";
GPrimitiveSprite(0, 10, 10, 7, sq, 1);

// 5×5 X shape
const char* x_shape = "#3>.#$2#.2#$5.$2#.2#$#3>.#";
GPrimitiveSprite(0, 20, 20, 12, x_shape, 1);

// 3-pixel block repeated 4 times in a row using group syntax
const char* row = "4[3#>]";
GPrimitiveSprite(0, 0, 40, 10, row, 1);

// 9×9 yellow (color 14) filled square drawn at 3× scale
const char* big_sq = "3#$3#$3#";
GPrimitiveSprite(0, 50, 50, 14, big_sq, 3);

GUpdateImage(0);

Build docs developers (and LLMs) love

Get started for freeTalk to us