The 2D vector display (device 3)
The 2D vector display draws lines, circles and simple filled shapes from a display list: a short sequence of drawing commands that the program builds in RAM and hands to the device. The device keeps its own copy, and the host draws it every frame until the program submits another list or clears it. The device does no geometry for the program: it does not rotate, scale or clip against anything but the screen, and nothing it draws can be read back. The exact rules are in SPEC.md, the core machine (§vector).
Getting the device
The display is slot 3, version 0. An image gets it by listing (3, 0) in its header, which terse pack ... --device 3:0 does. In an image that does not list it, every call from 300h to 3FFh returns FFFF_FFFFh and does nothing else, and nothing is drawn; so does a call number in that range other than the five below. An image that lists only the 3D display (device 9) still has the style and persistence settings, through device 9's own calls, but device 3's calls stay absent.
Coordinates
Coordinates are signed 16-bit numbers, little-endian, in sixteenths of a screen unit. The screen is 640 by 480 units, so its top left is (0, 0) and its bottom right is (10240, 7680) (VEC_SCREEN_W, VEC_SCREEN_H; VEC_UNIT is 16). Anything outside the screen is not shown. Units are square and the screen is shown at a 4:3 shape, so a circle is round.
Calls
a7 | Call | Arguments | Result |
|---|---|---|---|
300h | submit | a0 list address, a1 length | 0 done, 1 rejected |
301h | clear | none | 0 |
302h | style | a0 style | 0 done, 1 rejected |
303h | persistence | a0 persistence | 0 done, 1 rejected |
304h | fill | a0 fill mode | 0 done, 1 rejected |
submitcopiesa1bytes from addressa0into the device, replacing the previous list, and returns 0. It is rejected, returning 1 and keeping the previous list, if the length is 0 or more than 16,384 (VEC_MAX_LIST) or any part of the range is outside RAM. A list in ROM is rejected this way too:submitnever returnsFFFF_FFFEh.clearempties the list, so nothing is drawn.stylesets the display style: 0 clean (VEC_STYLE_CLEAN), 1 phosphor (VEC_STYLE_PHOSPHOR).persistencesets the persistence, 0 to 255: how long the program would like the phosphor afterglow to last, a hint a host may ignore.fillsets the fill mode: 0 filled shapes are filled (VEC_FILL_ON), 1 they are drawn as outlines (VEC_FILL_OFF).
style, persistence and fill return 1 and change nothing for a value out of range, else 0. The style and the persistence are one setting shared with the 3D display: whichever device sets them, both displays and the whole screen are shown that way.
After reset the list is empty, the style is clean, the persistence is 160 and the fill mode is 0. The list the device holds at the end of a frame is the one the host shows for that frame.
The display list
A list is a sequence of commands, each one opcode byte followed by its operands. A coordinate pair x, y is two signed 16-bit values (4 bytes); a radius is 2 bytes, unsigned. Drawing state at the start of a list: colour opaque white (255, 255, 255, 255), width 16 (one screen unit), origin (0, 0), current point (0, 0).
| Op | Command | Operands | Effect |
|---|---|---|---|
00h | End | none | Ends the list |
01h | Colour | r, g, b, a (1 byte each) | Sets the colour; a is opacity, 255 opaque |
02h | Width | w (1 byte) | Line width in sixteenths; 0 counts as 1 |
03h | Origin | x, y | Sets the origin (below) |
04h | Move | x, y | Sets the current point |
05h | Line | x, y | Line from the current point to (x, y), the new current point |
06h | Circle | radius | Circle outline about the current point |
07h | Disc | radius | Filled circle about the current point |
08h | Rectangle | x, y | Fills the rectangle with corners at the current point and (x, y) |
09h | Triangle | x1, y1, x2, y2 | Fills the triangle of the current point and the two points |
The C builders in terse.h, in the same order: vec_end, vec_colour, vec_width, vec_origin, vec_move, vec_line, vec_circle, vec_disc, vec_rect, vec_tri. They append to the buffer given to vec_begin; vec_length is the bytes written so far.
Rules:
- The origin is added to every later coordinate, but not to a later Origin. The sum wraps to 16 bits. The current point is stored after the origin has been added, so a later Origin does not move it.
- Lines and circle outlines use the current width and have round ends, so a line to the current point draws a dot. A circle outline is centred on its radius: half the width falls inside and half outside.
- Circle, Disc, Rectangle and Triangle leave the current point unchanged.
- Shapes are drawn in list order, each over the earlier ones, blended by opacity.
- The list ends at an End command, at the end of the submitted bytes, at an unknown opcode (
0Ahand up), or at a command whose operands are cut off by the end of the list. Commands before that point are drawn; nothing after it is.
Outlines
In the phosphor style, and with fill mode 1, nothing is filled: a disc is drawn as a circle outline of the same radius, a rectangle as the four lines between its corners, and a triangle as the three lines between its points, each with the width in effect at that command. A rectangle's lines go from the current point (x0, y0) to (x1, y0), (x1, y1), (x0, y1) and back; a triangle's from the current point to the first point, the second, and back. The page's figures are outlined too. Outlines count against the ink cap like lines.
The ink cap
How much one list makes a host draw is limited, so that no list can make a frame slow. Each shape drawn counts its ink, in square screen units, in list order, with coordinates resolved as above (origin added) and w the width in sixteenths:
- a filled shape drawn filled (clean style, fill mode 0): half its bounding box. The box is a disc's square from (x - r, y - r) to (x + r, y + r) (computed without wrapping), a rectangle itself, or a triangle's smallest axis-aligned box, clipped to the screen (0 to 10240 by 0 to 7680); the ink is its width times its height in sixteenths, divided by 512, rounded up;
- a line or circle outline, and each outline a filled shape becomes: the smaller of its stroke, (L + w) x (w + 48), and its box grown by (w + 48) / 2 (rounded down) on every side and clipped to the screen, in sixteenths, divided by 256, rounded up. L is |x1 - x0| + |y1 - y0| for a line, 8 x r for a circle; the box is a line's two ends, or a circle's square.
The total starts at 0 for each list. A shape whose ink would take it above 3/4 x 640 x 480 = 230,400 is not drawn, and neither is anything after it in the list. What is drawn depends only on the list, the style and the fill mode.
Worked numbers: a rectangle over the whole screen counts 10240 x 7680 / 512 = 153,600; one over the top half 76,800, so the two make the cap exactly. A line across the screen one unit wide counts (10240 + 16) x 64 / 256 = 2,564. A disc of radius 160 at (0, 0) has the box 0..160 by 0..160 on the screen: 25,600 / 512 = 50. The 3 units added to a stroke's width are the edge a host smooths, which costs as much as the stroke itself on a thin line; a list at the cap takes the reference host about a third of a frame to draw on one thread.
Layers
In the clean style the host combines the displays in a fixed order, from the bottom:
- 1. the terminal's cell backgrounds;
- 2. the page: its background, then its text;
- 3. the vector displays: device 3's shapes, then device 9's;
- 4. the terminal's characters and cursor.
So terminal text is always drawn over vector shapes, and a cell's background colour is always behind them. Shapes are drawn over the page, and terminal characters over both (a program that shows the page usually leaves the terminal cells under its rectangle blank). To make a panel of text hide the shapes behind it, draw a filled rectangle at the end of the list; the text still appears above it. Smoothing of edges, the exact colour of blended pixels and the last pixel of each shape are up to the host and cannot be observed. In a system of several machines each machine's screen is combined in this order on its own, with its own style.
What a host must draw
In either style a host must draw each command the list draws, and nothing after its end, where the list puts it (coordinates with the origin added, the width in effect, round ends), in its colour and opacity; filled shapes filled in the clean style with fill mode 0, and as outlines otherwise, within the ink cap; nothing outside the screen. In the clean style shapes are drawn in list order, each over the earlier ones, and the layers in the order above. In the phosphor style it must also do what the next section requires. The rest of how the display looks is the host's.
The phosphor style
The phosphor style asks for the look of a vector monitor or oscilloscope tube: light on a black screen. Part of it changes what is visible, and every host must do it:
- The screen is black: cell background colours and the page's background are not drawn. A program in this style may leave any background colours in its cells.
- Nothing is filled: shapes and the page's figures are outlines, which count against the ink cap.
- The terminal's characters and cursor are drawn in their foreground colour, and the page's text and figures in their colours, on the black screen with the shapes.
- Nothing added for the look may hide or blur what is shown: text stays as legible as in the clean style.
Where light overlaps, a host may add it up, as a tube does (opacity then acts as brightness), or blend it in the clean style's order. The rest is the host's choice: whether light adds up, brightness, tone curve and tint, the beam's profile across its width, glow and halo, afterglow and trails and how the persistence shapes them, dots of light where lines end, flicker, curvature, vignette, and where an outline sits on a shape's edge. A host that draws plain lines in the given colours on black, with no glow and no afterglow, conforms. The persistence is a hint a host may ignore; it is still kept in the machine's state. None of the look is machine state, and the program cannot observe it. A host that draws an afterglow should let the user turn it off.
Not a requirement, the reference host's look: terse-host draws a thin, sharp beam (never thinner than about a pixel) on a faint, wide glow that leaves the gaps between close lines dark, and adds overlapping light, so drawing a line twice brightens it there. Text keeps its own colours and smoothing, as sharp as in the clean style, and adds only a little to the glow. Light lingers: an afterglow of what was shown before fades quickly at first, then with a dim tail multiplied by persistence / 256 each frame (none with persistence 0), and a shape that only moves leaves a continuous smear. A program may be written with this look in mind, but its picture should not depend on it.
Charges
| What | Charge |
|---|---|
| Any call, also a rejected one | 4 |
An accepted submit | 1 per 4 bytes of the list, rounded up |
A rejected submit copies nothing and costs only the 4. Drawing, decoding and the ink cap are the host's work and are not charged. A full 16,384-byte list costs 4 + 4,096 units. See charges.
State
The device sends no events and takes no input from the host. Its state is the style, the persistence, the fill mode and the copy of the list, held in this order: a present flag (1 byte: the machine has device 3 or device 9; if 00h nothing follows), the style (00h clean, 01h phosphor), the persistence, the fill mode (00h fill, 01h outlines), the list's length m (4 bytes, 0 to 16,384) and the m bytes of the last accepted submit. For an image with device 9 and not device 3 the fill mode is 00h and m is 0. The afterglow is not included.
Example
#include "terse.h"
static uint8_t list[256];
int main(void)
{
for (int16_t x = 0;; x = (x + 16) % VEC_SCREEN_W) {
vec_begin(list);
vec_colour(255, 200, 0, 255);
vec_width(32); /* two units */
vec_move(x, 120 * VEC_UNIT);
vec_line(x + 80 * VEC_UNIT, 360 * VEC_UNIT);
vec_disc(10 * VEC_UNIT); /* at the line end */
vec_origin(320 * VEC_UNIT, 240 * VEC_UNIT);
vec_move(0, 0); /* screen centre */
vec_colour(0, 160, 255, 128);
vec_rect(40 * VEC_UNIT, 40 * VEC_UNIT);
vec_end();
vec_submit_list(list); /* VEC_DONE */
terse_wait_frame();
}
}
The list is 41 bytes, so each submit costs 4 + 11 units. The list stays on the screen until the next submit; a program whose picture does not change need not submit again. The next article, the 3D vector display, shares this display's style and layers.