Figures on the page

A figure is a drawing between the paragraphs of a page document: a box of a given size, drawn from paths of straight lines and Bezier curves, filled and stroked. It is the Figure command (08h) of the page device, version 0 of device slot 7. Like the rest of the page it is drawn by the host, outside the machine's frames; three caps bound the work of each figure.

The box above is one filled path; the triangle is a path filled red and stroked in the text colour 2 units wide; the blue curve is a cubic segment, stroked only.

The Figure command

OffsetSizeField
01Opcode 08h
12Width in screen units, clamped to 1..1024
32Height, clamped to 1..1024
51Align: 0 start (left), 1 centre, 2 end (right); anything else 0
62n, the length of the path commands
8nThe path commands

If the n bytes run past the end of the document, the command is cut off and the document ends before it.

Path commands

Each command is an opcode byte and its operands. Coordinates are signed 16-bit numbers in sixteenths of a screen unit from the figure's top left corner (x right, y down); colours are r, g, b, a, one byte each, a the opacity.

OpCommandOperandsEffect
01hFillr, g, b, aEnds the path; later paths are filled in this colour, not filled if a is 0
02hStroker, g, b, a, width (2 bytes, unsigned, sixteenths)Ends the path; later paths are stroked so, not stroked if a or width is 0
03hMovex, yStarts a subpath at (x, y)
04hLinex, yStraight segment to (x, y)
05hQuadraticx1, y1, x, yQuadratic Bezier to (x, y), control point (x1, y1)
06hCubicx1, y1, x2, y2, x, yCubic Bezier to (x, y), control points (x1, y1), (x2, y2)
07hClosenoneStraight segment back to the subpath's start, ending the subpath; nothing if none is open

Operand sizes: Fill 4 bytes, Stroke 6, Move and Line 4, Quadratic 8, Cubic 12, Close 0. The commands end at the end of the n bytes, at an unknown opcode or at a command whose operands are cut off; the ones before are used.

At the start: no fill; stroke in the document's text colour at the Figure command, opaque, 16 sixteenths (one unit) wide; current point (0, 0); no subpath open.

Segments, subpaths and paths

Caps

Paths are drawn in order and counted against three caps per figure. The first path that would take a total above its cap is not drawn, and neither is any path after it. A path that draws nothing (no segment, or neither fill nor stroke) counts against none of them. The caps count the path commands alone: a figure drawn as outlines (below) counts its fills all the same.

CapLimit
Paths256
Area8 x width x height of the figure, and at most 4 x 640 x 480 = 1,228,800 square units
Length65,536

Worked example: a figure 100 x 50 units, so the area cap is 8 x 100 x 50 = 40,000. One path, filled and stroked 2 units (32 sixteenths) wide: Move (160, 160), then Lines to (1440, 160), (1440, 640), (160, 640) and (160, 160), the rectangle from (10, 10) to (90, 40) in units.

So seven such paths fit this figure's area cap (35,168); an eighth would take the total to 40,192 and would not be drawn, nor anything after it. The length cap alone would allow 70.

Outlines

When the vector display (device 3) is in the phosphor style or in fill mode 1, figures are drawn as outlines: nothing is filled, and a path that is filled but not stroked is stroked one unit wide in its fill colour. In the phosphor style they are light on the tube like the rest of the page. An image without the vector display has the clean style and fill mode 0, so its figures are filled.

Building a figure in C

While building a document (see The page (device 7)), the library's path builder writes these commands and doc_figure wraps them in a Figure command, whose head is DOC_FIGURE_HEAD (8) bytes. This is the red triangle above, in a box of 120 x 80 units:

static uint8_t path[64];
path_begin(path, sizeof path);
path_fill(224, 108, 117, 255);
path_stroke(229, 229, 229, 255, 32);
path_move(320, 1120);
path_line(960, 160);
path_line(1600, 1120);
path_close();
doc_figure(120, 80, DOC_CENTRE, path, path_length(path));

Figures in articles

The article format writes a figure as text: a fence whose opening line is three backquotes, path, the width W and the height H (1..1024 units each, 1 to 4 digits with no sign; a column of the recommended width, about 68 characters of body text, is 512 units), holding a path string up to a closing line of three backquotes. The path string is SVG path data:

CommandNumbersMeaning
M2Move; more pairs after it are lines
L2Line
H, V1Horizontal or vertical line
C6Cubic curve
S4Smooth cubic: first control point reflected
Q4Quadratic curve
T2Smooth quadratic: control point reflected
Z0Close the subpath

The reader turns each figure into a Figure command this way:

The source of the figure at the top of this article:

    ```path 240 80
    fill #20304a stroke none M0 0 H240 V80 H0 Z
    fill #e06c75 stroke fg 2 M20 70 L60 10 100 70 Z
    fill none stroke #61afef 3 M120 60 C150 0 190 0 220 60
    ```