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

a7CallArgumentsResult
300hsubmita0 list address, a1 length0 done, 1 rejected
301hclearnone0
302hstylea0 style0 done, 1 rejected
303hpersistencea0 persistence0 done, 1 rejected
304hfilla0 fill mode0 done, 1 rejected

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).

OpCommandOperandsEffect
00hEndnoneEnds the list
01hColourr, g, b, a (1 byte each)Sets the colour; a is opacity, 255 opaque
02hWidthw (1 byte)Line width in sixteenths; 0 counts as 1
03hOriginx, ySets the origin (below)
04hMovex, ySets the current point
05hLinex, yLine from the current point to (x, y), the new current point
06hCircleradiusCircle outline about the current point
07hDiscradiusFilled circle about the current point
08hRectanglex, yFills the rectangle with corners at the current point and (x, y)
09hTrianglex1, y1, x2, y2Fills 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:

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:

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:

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:

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

WhatCharge
Any call, also a rejected one4
An accepted submit1 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.