uLisp

Graphics extensions

This page lists the graphics extensions available in the ARM, ESP, and RISC-V versions of uLisp.

Recommended boards

The current releases of uLisp include built-in support for the graphics extensions with the displays on the following boards:

Board	Resolution	Size	read-pixel	Touchscreen
Adafruit PyGamer and PyBadge	160 x 128	1.8"	Yes	No
Adafruit ESP32-S2 TFT Feather	240 x 135	1.14"	Yes	No
TTGO T-Display	240 x 135	1.14"	Yes	No
LILYGO T-Display RP2040	240 x 135	1.14"	Yes	No
Adafruit Clue	240 x 240	1.3"	No	No
Seeed Studio Wio Terminal	320 x 240	2.4"	Yes	No
Adafruit PyPortal	320 x 240	3.2"	Yes	Yes
Adafruit PyPortal Pynt	320 x 240	2.4"	Yes	Yes
Sipeed MAiX RISC-V boards	320 x 240	2.4"	No	No
M5Stack Tab5	1280 x 720	5"	Yes	Yes

You could also use the graphics extensions with an external colour TFT display attached to a board via SPI, but you would need to do some configuration of uLisp to specify the type of display.

These extensions are based on and compatible with Adafruit's GFX library ^[1].

For examples of using these routines see the Graphics examples.

Summary

Plotting pixels

draw-pixel

Plotting shapes

draw-line, draw-rect, fill-rect, draw-round-rect, fill-round-rect, draw-circle, fill-circle, draw-triangle, fill-triangle

Plotting characters

draw-char, with-gfx, set-cursor, set-text-color, set-text-size, set-text-wrap

Reading the display

read-pixel, touchscreen

Display control

fill-screen, set-rotation, invert-display, display, display-size

Colours

Most of the plotting functions take a colour parameter to specify the colour of plotting. This is a 16-bit number specifying the red, blue, and green components of the colour:

The following function rgb allows you to define a colour by specifying the red, green, and blue components as numbers between 0 and 255:

(defun rgb (r g b)
  (logior (ash (logand r #xf8) 8) (ash (logand g #xfc) 3) (ash b -3)))

For example, to define an orange colour you could write:

(defvar orange (rgb 255 127 0))

---

display function

Syntax: (display)

With monochrome OLED displays you need to call (display) to update the display from the memory cache after performing any drawing functions. Not needed with colour displays.

display-size function

Syntax: (display-size)

Returns the display dimensions as a list of:

(width height)

taking into account the orientation of the display set by set-rotation.

draw-char function

Syntax: (draw-char x y char [colour background size])

Draws the character char with its top left corner at (x, y). The character is drawn in a 5 x 7 pixel font in colour against background, which default to white and black respectively. The character can optionally be scaled by size.

Built-in character set

Text plotting uses a built-in character set which is based on the IBM PC Code Page 437 character set:

draw-circle function

Syntax: (draw-circle x y r [colour])

Draws an outline circle with its centre at (x, y) and with radius r. The outline is drawn in colour, or white if omitted.

draw-line function

Syntax: (draw-line x0 y0 x1 y1 [colour])

Draws a line from (x0 , y0) to (x1, y1) in colour, or white if omitted.

draw-pixel function

Syntax: (draw-pixel x y [colour])

Draws a pixel at coordinates (x , y) in colour, or white if omitted.

draw-rect function

Syntax: (draw-rect x y w h [colour])

Draws an outline rectangle with its top left corner at (x, y), with width w, and with height h. The outline is drawn in colour, or white if omitted.

draw-round-rect function

Syntax: (draw-round-rect x y w h radius [colour])

Draws an outline rounded rectangle with its top left corner at (x, y), with width w, height h, and corner radius radius. The outline is drawn in colour, or white if omitted.

draw-triangle function

Syntax: (draw-triangle x0 y0 x1 y1 x2 y2 [colour])

Draws an outline triangle between (x1, y1), (x2, y2), and (x3, y3). The outline is drawn in colour, or white if omitted.

fill-circle function

Syntax: (fill-circle x y r [colour])

Draws a filled circle with its centre at (x, y) and with radius r. The circle is drawn in colour, or white if omitted.

fill-rect function

Syntax: (fill-rect x y w h [colour])

Draws a filled rectangle with its top left corner at (x, y), with width w, and with height h. The rectangle is drawn in colour, or white if omitted.

fill-round-rect function

Syntax: (fill-round-rect x y w h radius [colour])

Draws a filled rounded rectangle with its top left corner at (x, y), with width w, height h, and corner radius radius. The frame is drawn in colour, or white if omitted.

fill-triangle function

Syntax: (fill-triangle x0 y0 x1 y1 x2 y2 [colour])

Draws a filled triangle between (x1, y1), (x2, y2), and (x3, y3). The triangle is drawn in colour, or white if omitted.

invert-display function

Syntax: (invert-display boolean)

Mirror-images the display. 

read-pixel function

Syntax: (read-pixel x y)

Returns the colour of the pixel at (x, y). For details of which boards support this function see Recommended boards above.

set-cursor function

Syntax: (set-cursor x y)

Sets the start point for text plotting to (x, y).

touchscreen function

Syntax: (touchscreen [raw])

Returns the touch position as a list (x y) in screen coordinates, or nil if there is no touch.

Setting raw to t returns the raw coordinates from the touchscreen, not scaled to the screen, in case you want to do your own scaling.

For details of which boards support this function see Recommended boards above.

with-gfx special form

Syntax: (with-gfx (stream) form*)

The with-gfx form evaluates the forms with stream bound to a gfx-stream.

You can then print text to the graphics display using the standard uLisp print commands. To control printing use set-cursor, set-text-color, set-text-size, and set-text-wrap.

For example, the following function pretty-prints the currently defined functions to the display:

(defun gprint ()
  (fill-screen)
  (set-rotation 2)
  (with-gfx (str)
    (set-cursor 0 0)
    (pprintall str)))

---

1. ^ Diagrams reproduced from Adafruit under the Attribution-ShareAlike Creative Commons licence.