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.

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 are not limited by the fill cap.

The fill cap

When filled shapes are filled (the clean style with fill mode 0), the area they cover in one list is limited. Each disc, rectangle and triangle, in list order, counts the area of its bounding box:

with coordinates resolved as above (origin added). The box is clipped to the screen (0 to 10240 by 0 to 7680), and its area in square screen units is its width times its height in sixteenths, divided by 256 and rounded up.

The running total starts at 0 for each list. A filled shape whose area would take the total above 4 x 640 x 480 = 1,228,800 is not drawn, and neither is any filled shape after it in the list. Lines and circle outlines are still drawn. A shape that is not drawn does not count.

Worked numbers: a rectangle covering the whole screen counts 10240 x 7680 / 256 = 307,200, so four of them fill the cap exactly and a fifth filled shape, however small, is not drawn. A disc of radius 160 (10 units) centred at (0, 0) has the box (-160, -160) to (160, 160), clipped to 0..160 by 0..160: 25,600 / 256 = 100. A rectangle 17 by 17 sixteenths counts 289 / 256, rounded up to 2.

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 and the exact colour of blended pixels 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.

The phosphor style

In the phosphor style the whole screen imitates a vector monitor or oscilloscope tube:

The exact brightness, core width, glow, fast decay, tone curve and where an outline sits on a shape's edge are up to the host. The afterglow is presentation, not machine state, and the program cannot observe it; a host should let the user turn it off. In the clean style the persistence has no effect.

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 fill 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 image lists 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.