Libraries

$\text{[math]}$ `gfx`

Pixel drawing under the text of the screen: shapes, text, sprites and scrolling.

Transistor Mainframe and newer

The gfx library draws pixels on the computer's screen: points, lines, rectangles, circles, triangles, text in a small pixel font, sprites made of hex digits, and a scroll that slides the whole picture. It is how you build gauges, charts, maps of a rail network, control panels with real buttons, and games.

The drawing lies under the text of the screen. What you print stays readable on top of it, so a program can draw a picture and still use print, term.write and read as usual.

Functions

`gfx.size()`	The size of the drawing in pixels: the size of the text grid times 6 by 9.
`gfx.clear([color])`	Erases the drawing, or fills all of it with one colour.
`gfx.get_pixel(x, y)`	The colour of one pixel of the drawing, as a number, even when it was drawn with a name. It is `nil` where nothing is drawn, outside the screen, and everywhere before the first drawing.
`gfx.pixel(x, y, color [, size])`	Colours one pixel, or a square of `size` × `size` pixels centred on it.
`gfx.line(x1, y1, x2, y2, color [, thickness])`	A straight line from (x1, y1) to (x2, y2), both ends included.
`gfx.rect(x, y, w, h, color [, fill])`	A rectangle `w` pixels wide and `h` pixels tall, its top left corner at (x, y).
`gfx.circle(x, y, radius, color [, fill])`	A circle around (x, y), or a disc, or a ring.
`gfx.triangle(x1, y1, x2, y2, x3, y3, color [, fill])`	A triangle through three corners, given in any order.
`gfx.fill(x, y, color)`	The paint bucket: repaints the whole area of the same colour as the pixel at (x, y).
`gfx.text(x, y, text, color [, scale])`	Writes text with a tiny 3 × 5 pixel font, at any pixel and in any size. Returns the width it took.
`gfx.image(x, y, rows [, scale [, flip]])`	Draws a sprite: a small picture written as text, one character per pixel.
`gfx.scroll(dx, dy [, x, y, w, h])`	Slides the drawing by (dx, dy). What leaves the area is lost, and what comes in on the other side is empty.

The pixel layer

Every character cell of the screen is 6 pixels wide and 9 pixels tall, so the size of the drawing follows the size of the text grid:

Computer	Text	Pixels	Colours
Tube Computer	40 × 14	no `gfx`	paper teletype
Transistor Mainframe	51 × 19	306 × 171	green phosphor
Minicomputer	51 × 19	306 × 171	amber phosphor
Personal Computer	51 × 19	306 × 171	16 colours
Microcontroller	40 × 12	240 × 108	16 colours
Modern Computer	64 × 24	384 × 216	16 colours

The Tube Computer prints on paper and has no drawing: there, gfx is nil. A program meant to run everywhere can test if gfx then ... end.

Coordinates

Like term.set_cursor, coordinates start at (1, 1) in the top left corner. x grows to the right, y grows downwards. Decimal coordinates are rounded down, so you can pass the result of math.sin or a division directly.

Nothing is ever out of range: whatever falls outside the screen is simply cut off (clipped). A circle half off the edge draws its visible half, and a pixel at (-5, 400) draws nothing, without an error.

Colours

A colour is a name ("red"), or a number from 0 to 15 (term.colors.red, which is 14). The special name "none" (or the number -1) erases: the pixel becomes empty again and shows what is under the drawing. The 16 names and their numbers are in Colours. A number must be whole, from -1 to 15: anything else stops the program with bad argument #3 to 'pixel' (colour (0..15 or a name) expected, got number).

A name that does not exist stops the program, and the error lists the right ones:

Brass

gfx.rect(10, 10, 40, 20, "grey", true)

Screen

snippet:1: bad argument #5 to 'rect' (unknown colou
r 'grey': white, orange, magenta, light_blue, yello
w, lime, pink, gray, light_gray, cyan, purple, blue
, brown, green, red, black, none)

Layers: background, drawing, text

The screen is drawn in three layers, from bottom to top:

the background colour of each character cell (term.set_bg then term.clear, or write);
the drawing of gfx;
the characters of the text.

So text always shows over the drawing, but the background colour of a character cell is hidden wherever something is drawn. Empty pixels let the cell backgrounds show through.

The drawing stays on the screen after the program ends. term.clear only clears the text: to remove the drawing, call gfx.clear(). The shell command clear, stopping a program with Ctrl+T and a reboot clear both.

Cost

Drawing is not free. Every call that changes pixels charges the program one instruction per 64 pixels touched, on top of the call itself. A Personal Computer runs 1,200 instructions per tick at full speed, and filling its whole screen (306 × 171 = 52,326 pixels) costs 817 of them. Text costs one instruction per character, times the scale squared; a sprite one per row, plus its pixels.

Call	Instructions
`gfx.pixel`, `gfx.line`, `gfx.rect`, `gfx.circle`, `gfx.triangle`, `gfx.fill`, `gfx.scroll`, `gfx.clear(color)`	1 per 64 pixels
`gfx.text`	number of characters × scale²
`gfx.image`	1 per row + 1 per 64 pixels
`gfx.clear()`, `gfx.size`, `gfx.get_pixel`	nothing more than the call

The screen is sent to the players who look at it at most every 2 ticks (a server setting), and only the band of pixel rows that changed since the last update travels over the network: from the highest change to the lowest. A small animated gauge costs almost nothing; redrawing the whole screen every tick sends the whole picture every time. Draw only what changes (see the patterns at the end of this page).

Monochrome screens

The Transistor Mainframe (green) and the Minicomputer (amber) have a single phosphor colour. On them, every colour except black lights up in the phosphor colour, and black is the dark screen. A drawing meant for them uses black for "off" and any other colour for "on". (An LCD Monitor attached to them shows the real colours: see Screens and monitors.)

The same program on a Personal Computer:

`gfx.size()`

→ table

The size of the drawing in pixels: the size of the text grid times 6 by 9.

Returns

table: {w = width, h = height} in pixels

Use it instead of fixed numbers, and the same program fits every screen. This frame follows the edges of the screen whatever the computer:

The same code on a Microcontroller, whose screen is 240 × 108:

`gfx.clear([color])`

⚙ cost 1 per 64 px

Erases the drawing, or fills all of it with one colour.

Parameters

color string|number optional: a colour that fills the whole picture; left out (or "none"), the drawing is erased

Without a colour, every pixel becomes empty and the cell backgrounds of the text show again. This costs nothing. With a colour, the whole picture is painted, which costs one instruction per 64 pixels (817 on a Personal Computer).

gfx.clear does not touch the text, and term.clear does not touch the drawing. Here the cells are made gray with term.set_bg, the drawing covers them in blue, and a rectangle of "none" opens a window where the gray shows again:

A program that redraws its screen from scratch usually starts with both:

Brass

term.set_bg(term.colors.black)
term.clear()
gfx.clear()

`gfx.get_pixel(x, y)`

→ number|nil

The colour of one pixel of the drawing, as a number, even when it was drawn with a name. It is nil where nothing is drawn, outside the screen, and everywhere before the first drawing.

Parameters

x number: column of the pixel, from 1
y number: row of the pixel, from 1

Returns

number|nil: the colour number (0 to 15), or nil where nothing is drawn

Brass

gfx.rect(10, 10, 20, 20, "red", true)
print(gfx.get_pixel(15, 15))
print(gfx.get_pixel(15, 15) == term.colors.red)
print(gfx.get_pixel(100, 100))

Screen

14
true
nil

Watch out

Compare with a number: gfx.get_pixel(x, y) == "red" is always false. Use term.colors.red or 14.

It only reads the drawing, never the text. It is handy in small games, to know what a moving piece is about to hit: a wall drawn in gray, a coin drawn in yellow.

Points and lines

`gfx.pixel(x, y, color [, size])`

⚙ cost 1 per 64 px

Colours one pixel, or a square of size × size pixels centred on it.

Parameters

x number: column, from 1
y number: row, from 1
color string|number: a colour name or number, "none" to erase
size number optional: the side of a square centred on (x, y), 1 to 64 (1 when left out)

With an odd size, (x, y) is exactly in the middle. With an even size, the extra row and column go to the right and to the bottom. Sizes above 64 are taken as 64. The red dots below mark the point given:

Points are the right tool for plots: one reading, one dot. Here a day of a solar-like curve, one dot every 4 pixels:

`gfx.line(x1, y1, x2, y2, color [, thickness])`

⚙ cost 1 per 64 px

A straight line from (x1, y1) to (x2, y2), both ends included.

Parameters

x1 number: column of the start
y1 number: row of the start
x2 number: column of the end
y2 number: row of the end
color string|number: a colour name or number, "none" to erase
thickness number optional: 1 to 64 pixels (1 when left out)

A thin line is one pixel wide and has no gaps, even when it climbs steeply. A thick line stamps a square of thickness pixels at every point, so its ends are square, and it costs more: a 100-pixel line 8 pixels thick touches 6,400 pixels.

Lines between the readings of a sensor make a chart. Each segment joins one value to the next:

Shapes

The shapes take their size and colour, then an optional last argument that says how to draw them: left out, an outline one pixel wide; true, filled; for rectangles and circles, a number gives the thickness of the border.

`gfx.rect(x, y, w, h, color [, fill])`

⚙ cost 1 per 64 px

A rectangle w pixels wide and h pixels tall, its top left corner at (x, y).

Parameters

x number: column of the top left corner
y number: row of the top left corner
w number: width in pixels
h number: height in pixels
color string|number: a colour name or number, "none" to erase
fill boolean|number optional: true to fill it, or the thickness of the border (1 to 64); an outline 1 pixel wide when left out

The border is drawn inside the rectangle: gfx.rect(10, 10, 50, 20, "red", 3) stays within the same 50 × 20 pixels as the filled rectangle, with a hole in the middle. When the border is at least half of the smaller side, the rectangle is simply filled. A width or a height of zero or less draws nothing.

Filled rectangles are also the fastest way to erase part of the picture before drawing it again: paint it with the background colour, or with "none".

`gfx.circle(x, y, radius, color [, fill])`

⚙ cost 1 per 64 px

A circle around (x, y), or a disc, or a ring.

Parameters

x number: column of the centre
y number: row of the centre
radius number: in pixels; 0 draws a single pixel
color string|number: a colour name or number, "none" to erase
fill boolean|number optional: true for a disc, or the thickness of the ring (1 to 64); an outline 1 pixel wide when left out

The circle is 2 × radius + 1 pixels across. A border thickness grows inwards, like the border of a rectangle. A negative radius draws nothing.

With math.cos and math.sin, circles become lamps, dials and radar screens. A ring of 8 status lamps, lit by a bit pattern:

`gfx.triangle(x1, y1, x2, y2, x3, y3, color [, fill])`

⚙ cost 1 per 64 px

A triangle through three corners, given in any order.

Parameters

x1 number: column of the first corner
y1 number: row of the first corner
x2 number: column of the second corner
y2 number: row of the second corner
x3 number: column of the third corner
y3 number: row of the third corner
color string|number: a colour name or number, "none" to erase
fill boolean optional: true to fill it; an outline 1 pixel wide otherwise

Unlike rectangles and circles, a triangle has no border thickness: the last argument is true for a filled triangle, anything else draws the outline. For a thick outline, draw three lines with a thickness.

Triangles make roofs, mountains, and above all arrows:

`gfx.fill(x, y, color)`

⚙ cost 1 per 64 px

The paint bucket: repaints the whole area of the same colour as the pixel at (x, y).

Parameters

x number: column of the starting pixel
y number: row of the starting pixel
color string|number: the new colour, or "none" to erase the area

The area spreads from (x, y) to the neighbours above, below, left and right that have exactly the same colour as the starting pixel. It stops at any other colour. Outlines drawn by gfx.line, gfx.circle and gfx.triangle are closed for it, even where they go diagonally, so the inside of a shape fills without leaking.

Empty pixels count as a colour of their own: on a picture cleared with gfx.clear("black"), a hole erased with "none" is a wall for a fill that starts on black.

Nothing happens when the pixel already has the new colour, or when (x, y) is outside the screen. The fill stops after 1,048,576 pixels, far more than the largest screen (82,944 pixels on a Modern Computer), so in practice it always fills the whole area, at one instruction per 64 pixels.

A closed shape fills on the inside only. Open a gap of one pixel and the paint escapes:

The shapes example of the computer uses it for clicks: each click paints the area under the mouse (see shapes).

Text and sprites

`gfx.text(x, y, text, color [, scale])`

→ number⚙ cost characters × scale²

Writes text with a tiny 3 × 5 pixel font, at any pixel and in any size. Returns the width it took.

Parameters

x number: column of the left edge of the first letter
y number: row of the top of the letters
text string: the text (a number is turned into text)
color string|number: a colour name or number, "none" to erase
scale number optional: 1 to 64, the size of each dot of the font (1 when left out)

Returns

number: the width of the text drawn, in pixels

Each letter is 3 dots wide and 5 tall, with one empty column after it: 4 pixels per character, so a line of 76 characters fits a Personal Computer at scale 1. At scale 2, every dot becomes 2 × 2 pixels, and so on.

The font has capital letters only (lowercase is drawn in capitals), digits, and these signs: space . , : ; ! ? ' " - + = / ( ) < > % * _ # [ ]. Accents are removed (É is drawn E), and every other character becomes ?.

The width returned is (4 × characters - 1) × scale: the last empty column is not counted.

Brass

print(gfx.text(1, 1, "HELLO", "white"))
print(gfx.text(1, 10, "HELLO", "white", 2))
print(gfx.text(1, 30, "", "white"))

Screen

19
38
0

Since the width is known in advance, centring is a subtraction. Keep such a helper at the top of your programs:

The returned width also places the next piece of text, for a label followed by a value in another colour:

Note

Text drawn with gfx.text is part of the drawing: it lies under the characters of print, it can be erased with "none" and it moves with gfx.scroll. Each character costs instructions (scale² each), so a big title drawn once is cheap, but redrawing a whole page of scale-3 text every tick is not.

`gfx.image(x, y, rows [, scale [, flip]])`

⚙ cost rows + 1 per 64 px

Draws a sprite: a small picture written as text, one character per pixel.

Parameters

x number: column of the top left corner
y number: row of the top left corner
rows table: a list of strings, one per row of pixels, one hex digit per pixel
scale number optional: 1 to 64, each pixel of the sprite becomes a square of this size (1 when left out)
flip boolean optional: true mirrors the sprite left to right

Each row is a string. Each character is a hex digit, the number of a colour: 0 white, 1 orange... 9 cyan, a purple, b blue, c brown, d green, e red, f black (capitals work too). Any other character, such as . or a space, is transparent: the pixel keeps what was there before. The full table is in Colours.

scale makes each pixel a square, and flip mirrors the sprite, so a character walking left and right needs only one picture. Each row is mirrored on its own length: give every row the same length (pad with .), or a mirrored sprite falls apart.

A row that is not a string stops the program: bad argument #3 to 'image' (row 2 is not a string). There is no digit for "erase": to remove a sprite, draw a rectangle of the background colour (or of "none") over it.

Scrolling

`gfx.scroll(dx, dy [, x, y, w, h])`

⚙ cost 1 per 64 px of the area

Slides the drawing by (dx, dy). What leaves the area is lost, and what comes in on the other side is empty.

Parameters

dx number: pixels to the right (negative: to the left)
dy number: pixels down (negative: up); 0 when left out
x number optional: column of the top left corner of the area to move
y number optional: row of the top left corner of the area
w number optional: width of the area
h number optional: height of the area

With four more numbers, only that rectangle moves and the rest of the picture stays still: a status bar can stay on top while the landscape below scrolls. Give all four or none. The text of the screen does not move (that is term.scroll), and before any drawing it does nothing.

A scroll costs as much as filling its area once (one instruction per 64 pixels), whatever is drawn in it: a landscape made of hundreds of shapes moves for the price of one rectangle, and only the new strip at the edge needs drawing. This is how side-scrolling games and live charts work. Here the hills come in from the right, 2 pixels per tick, under a title bar that does not move:

Patterns

Complete small programs that combine the functions above. They use sample numbers so that they run anywhere: in your world, the values come from peripheral.wrap(), inventory.count(), kinetic.speed() and the other devices.

A bar chart

The stock of a warehouse, one bar per item, scaled so that the largest fills the chart:

A gauge

A speedometer for a Create shaft: a half circle of coloured dots, ticks every 32 RPM, and a needle. The angle goes from π (left, 0 RPM) to 2π (right, 256 RPM). The sine of these angles is negative and y grows downwards on the screen, so the arc rises above its centre.

When the speed changes, there is no need to redraw the dial: draw the old needle again in black, then the new one.

Animate without flicker

The screen reaches the players every 2 ticks. If a frame takes longer than one tick of instructions to draw (a full clear and a redraw easily do), the program pauses in the middle of it and the players may see a half-drawn picture: the screen flickers. Two habits avoid it:

Do not clear the whole screen for every frame. Erase only what moves (a rectangle of the background colour over its old place), then draw it at its new place.
**Slide what is already drawn with gfx.scroll**, then draw only the new part. The picture is never empty, and the frame costs a fraction of a redraw.

A live chart of the stress of a factory works like this: each tick, the chart moves 2 pixels left and a single new segment is drawn at the right edge.

A sprite animation

A small locomotive drives along its rails. It has two pictures whose wheels differ, shown in turn, and it is mirrored when it turns back. Each step erases the old place with a rectangle of the sky colour, so the rest of the picture is never redrawn.

Buttons drawn in pixels

Buttons of any size, anywhere, with a label in the pixel font. A click event carries e.px and e.py, the pixel under the mouse (or under the finger, on a monitor): the button hit is the one whose rectangle contains that point. See Screens and monitors for clicks on monitors.

The test itself is plain arithmetic, so you can check it without clicking:

Brass

local press = {x = 12, y = 40, w = 88, h = 40}
local function inside(b, px, py)
  return px >= b.x and px < b.x + b.w and py >= b.y and py < b.y + b.h
end
print(inside(press, 50, 60))
print(inside(press, 100, 60))

Screen

true
false

px < b.x + b.w, with a strict <, because a button 88 pixels wide starting at 12 ends at pixel 99.

#The pixel layer

#Coordinates

#Colours

#Layers: background, drawing, text

#Cost

#Monochrome screens

gfx.size()

gfx.clear([color])

gfx.get_pixel(x, y)

#Points and lines

gfx.pixel(x, y, color [, size])

gfx.line(x1, y1, x2, y2, color [, thickness])

#Shapes

gfx.rect(x, y, w, h, color [, fill])

gfx.circle(x, y, radius, color [, fill])

gfx.triangle(x1, y1, x2, y2, x3, y3, color [, fill])

gfx.fill(x, y, color)

#Text and sprites

gfx.text(x, y, text, color [, scale])

gfx.image(x, y, rows [, scale [, flip]])

#Scrolling

gfx.scroll(dx, dy [, x, y, w, h])

#Patterns

#A bar chart

#A gauge

#Animate without flicker

#A sprite animation

#Buttons drawn in pixels

The pixel layer

Coordinates

Colours

Layers: background, drawing, text

Cost

Monochrome screens

`gfx.size()`

`gfx.clear([color])`

`gfx.get_pixel(x, y)`

Points and lines

`gfx.pixel(x, y, color [, size])`

`gfx.line(x1, y1, x2, y2, color [, thickness])`

Shapes

`gfx.rect(x, y, w, h, color [, fill])`

`gfx.circle(x, y, radius, color [, fill])`

`gfx.triangle(x1, y1, x2, y2, x3, y3, color [, fill])`

`gfx.fill(x, y, color)`

Text and sprites

`gfx.text(x, y, text, color [, scale])`

`gfx.image(x, y, rows [, scale [, flip]])`

Scrolling

`gfx.scroll(dx, dy [, x, y, w, h])`

Patterns

A bar chart

A gauge

Animate without flicker

A sprite animation

Buttons drawn in pixels