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.

LWXGL’s primitive drawing functions write palette-indexed pixels directly into an image element’s data buffer. All coordinates are in image-local space (relative to the top-left corner of the image, not the window). None of these functions call UpdateImage — you must call it yourself after all drawing for a frame is complete. The special sentinel value CLR_NONE (-1) can be passed for fg or bg on any primitive that accepts both; the corresponding layer (border or fill) is then skipped entirely.

​
PrimitiveRect

void PrimitiveRect(int id, int x, int y, int w, int h, int fg, int bg);
Draws an axis-aligned rectangle with a 1-pixel border. Border pixels receive color fg; interior pixels receive color bg. If fg == -1 (i.e., CLR_NONE passed as sentinel for “same as fill”), the border color is set equal to bg, effectively producing a solid rectangle. Pixels outside the image bounds are silently clipped.
​
id
int
required
Element slot index of the target image element.
​
x
int
required
Left edge of the rectangle, in image-local coordinates.
​
y
int
required
Top edge of the rectangle, in image-local coordinates.
​
w
int
required
Width of the rectangle in pixels.
​
h
int
required
Height of the rectangle in pixels.
​
fg
int
required
Border color — palette index 0–15, or CLR_NONE (-1) to skip the border. If fg == -1, it is automatically set to bg before drawing (solid fill shortcut).
​
bg
int
required
Fill color — palette index 0–15, or CLR_NONE (-1) to leave the interior untouched (outline-only rectangle).

​
PrimitiveCircle

void PrimitiveCircle(int id, int cx, int cy, int r, int fg, int bg);
Draws a filled circle centered at (cx, cy) with radius r. The border ring (pixels where |dist² - r²| < r) is drawn in color fg; interior pixels (dist² ≤ r²) are drawn in color bg. Either may be CLR_NONE to skip that layer.
​
id
int
required
Element slot index of the target image element.
​
cx
int
required
X coordinate of the circle center, in image-local coordinates.
​
cy
int
required
Y coordinate of the circle center, in image-local coordinates.
​
r
int
required
Radius in pixels.
​
fg
int
required
Border color — palette index 0–15, or CLR_NONE to skip the outline.
​
bg
int
required
Fill color — palette index 0–15, or CLR_NONE to skip the interior.
The border thickness grows slightly with radius because the proximity test uses abs(dist² - r²) < r. For large circles the border will be approximately 1–2 pixels wide.

​
PrimitiveLine

void PrimitiveLine(int id, int x1, int y1, int x2, int y2, int color);
Draws a straight line from (x1, y1) to (x2, y2) using floating-point increments. The number of steps equals max(abs(dx), abs(dy)); at each step x and y are each advanced by dx/steps and dy/steps respectively, and the pixel position is rounded to the nearest integer with std::round. Pixels outside the image bounds are skipped.
​
id
int
required
Element slot index of the target image element.
​
x1
int
required
X coordinate of the line start, in image-local coordinates.
​
y1
int
required
Y coordinate of the line start, in image-local coordinates.
​
x2
int
required
X coordinate of the line end, in image-local coordinates.
​
y2
int
required
Y coordinate of the line end, in image-local coordinates.
​
color
int
required
Line color — palette index 0–15.

​
PrimitiveTriangle

void PrimitiveTriangle(int id,
                       int x1, int y1,
                       int x2, int y2,
                       int x3, int y3,
                       int fg, int bg);
Draws a triangle with vertices at (x1,y1), (x2,y2), and (x3,y3). The interior is filled with bg using a barycentric (edge-function) test; the three edges are drawn with fg via three PrimitiveLine calls. Either fg or bg may be CLR_NONE to skip outline or fill respectively. The fill bounding box is clamped to [0, w-1] × [0, h-1] before iteration, so overdraw outside the image is impossible.
​
id
int
required
Element slot index of the target image element.
​
x1
int
required
X coordinate of the first vertex.
​
y1
int
required
Y coordinate of the first vertex.
​
x2
int
required
X coordinate of the second vertex.
​
y2
int
required
Y coordinate of the second vertex.
​
x3
int
required
X coordinate of the third vertex.
​
y3
int
required
Y coordinate of the third vertex.
​
fg
int
required
Edge color — palette index 0–15, or CLR_NONE to skip the outline.
​
bg
int
required
Fill color — palette index 0–15, or CLR_NONE to skip the interior fill.

​
PrimitiveSprite

void PrimitiveSprite(int id, int sx, int sy, int color,
                     const char* sprite, int scale);
Renders an RLE-encoded sprite into the image starting at (sx, sy). Each logical pixel is drawn as a scale × scale block of actual pixels.

​
Sprite format tokens

TokenMeaning
#Draw one pixel in color
.Draw one pixel in CLR_BLACK (index 0)
$Newline — advance y by scale, reset x to sx
>Skip one pixel to the right (x += scale)
0–9Digit prefix — repeat count for the next single token or group
[...]Group — the contents are treated as a single repeated unit when prefixed with a digit
!Terminate parsing immediately
Digit prefixes stack for multi-digit counts (e.g. 12# draws 12 pixels). A digit prefix before [...] repeats the whole group. Pixels outside image bounds are silently clipped.
​
id
int
required
Element slot index of the target image element.
​
sx
int
required
X coordinate of the sprite origin (top-left), in image-local coordinates.
​
sy
int
required
Y coordinate of the sprite origin (top-left), in image-local coordinates.
​
color
int
required
Foreground color for # pixels — palette index 0–15.
​
sprite
const char*
required
Null-terminated RLE sprite string. Parsing stops at the first \0 or !.
​
scale
int
required
Pixel scale factor. Each logical pixel becomes a scale × scale block. Use 1 for 1:1 rendering.

​
Sprite format examples

"5#3.$"      → 5 colored pixels, 3 black pixels, newline
"3[2#>]"     → repeat [2 colored, 1 skip] three times
"##..##$##..##!"  → simple 2-row symmetrical pattern, stop

​
Code Example

#include "libLWXGL.h"

// A small arrow sprite: 5-wide, 3-tall
static const char* arrow_sprite =
    ">2#>$"      // row 0: skip, skip, fill, skip
    "5#$"        // row 1: five filled pixels
    ">2#>!";     // row 2: same as row 0

void on_frame(int tick, float dt) {
    // Background
    PrimitiveRect(1, 0, 0, 320, 200, CLR_NONE, CLR_BLACK);

    // Sky gradient approximation with rects
    PrimitiveRect(1, 0, 0, 320, 80, CLR_NONE, CLR_BLUE);

    // Ground
    PrimitiveRect(1, 0, 140, 320, 60, CLR_NONE, CLR_GREEN);

    // Player circle
    PrimitiveCircle(1, 160, 120, 18, CLR_WHITE, CLR_RED);

    // Horizon line
    PrimitiveLine(1, 0, 140, 319, 140, CLR_LGRAY);

    // Roof triangle
    PrimitiveTriangle(1, 80, 80, 160, 40, 240, 80, CLR_WHITE, CLR_GRAY);

    // Arrow indicator sprite at 2× scale
    PrimitiveSprite(1, 150, 10, CLR_YELLOW, arrow_sprite, 2);

    UpdateImage(1);
}

int main(void) {
    CreateWindow(320, 200, "Primitives Demo", CLR_BLACK, FLAG_NONE);
    CreateImage(1, 0, 0, 0, 0);
    MainWindowLoop(60, on_frame);
    TerminateWindow();
    return 0;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us