Surfaces: a program's own screen in its 3D scene

A Surface is a command of the 3D vector display's list (device 9) that shows a rectangle of the program's own screen as a flat panel in its 3D scene: a console in a cockpit, a sign on a wall, an instrument on a dashboard. What it shows is the program's 2D layers (the terminal, the page and the 2D vector display), drawn as usual; what it adds is where they appear. No other machine is involved and nothing can nest: a Surface never shows the 3D display itself.

The command

OpCommandOperands (bytes)Effect
0EhSurfacex, y, width, height (2 each, unsigned, screen units), panel width w (2, unsigned, sixteenths)Shows that rectangle of the screen as a panel

The command is 11 bytes with its opcode; the C builder is v3_surface(x, y, w, h, width). The rectangle, the **source**, is clamped so it lies on the screen, as the page's rectangle is: x to at most 640, y to at most 480, the width to at most 640 - x and the height to at most 480 - y.

The panel is w/16 units wide and as high as the source's shape makes it, h' = w * height / width (in sixteenths), centred on the transform's origin in its xy plane. With M the transform in force its corners are

    top left      M(-w/32, -h'/32, 0)
    top right     M( w/32, -h'/32, 0)
    bottom right  M( w/32,  h'/32, 0)
    bottom left   M(-w/32,  h'/32, 0)

so it lies as a Screen does: with the identity, like the glass, its front towards the viewer. The point a fraction u along its top edge and v down its left edge shows the point (x + u * width, y + v * height) of the screen. It does not change the current point, and it is seen from behind as a Screen is (an opaque dark plate).

Which Surfaces take effect

Any program with device 9 may use them. A Surface is in effect if its source, after clamping, has a width and a height, its w is not 0, and fewer than 4 Surfaces before it in the list are in effect. Any other Surface is decoded and does nothing: it draws nothing, hides nothing, is not counted and leaves the glass alone. A Surface in effect counts as one face toward the caps of the 3D display; if a cap stops it, it is not in effect either.

How the screen is drawn

A program whose list has no Surface in effect is drawn exactly as without them. One that has Surfaces in effect is drawn, from the bottom:

1. the glass: its 2D layers in their usual order and style, without its 3D lines, and black wherever a pixel lies in the source of a Surface in effect: what a Surface shows is not also on the glass; 2. its Surfaces, from the farthest to the nearest (by the distance from the eye to their centres; the earlier in the list first where two are as far), each covering what is below it; 3. its 3D lines, points and circles, each Surface hiding what is behind it exactly as a Face of its four corners does. Lines in front of a Surface are drawn over it.

So text outside the sources stays on the glass as a heads-up line, and the instrument panels move onto their consoles. In the phosphor style the 2D layers on a Surface glow as they would on the glass, their afterglow included; the afterglow belongs to the screen, so it moves with the panel, and a moving Surface leaves no trail. How the 3D lines are lit over the Surfaces is up to the host.

Wherever the program's screen is shown it is this complete picture: on its own, in a tile of the shell, or as a panel in the shell's gallery. The shell's own Surfaces, when its scene has panels, are drawn among them, far to near.

A host that cannot draw in perspective may draw each source flat, scaled into the rectangle around the panel's projection. The resolution a source is drawn at for a Surface and its filtering are the host's.

The pointer

A pointer position over the front of a Surface (the ray from the eye through it meets the panel in front of the near plane; of several, the nearest counts) is delivered to the program as an ordinary pointer event at the corresponding point of the source: at (x + floor(u * width), y + floor(v * height)). A position over no Surface, or over one seen from behind, is delivered as its position on the glass, as before. So text and anchors shown on a console can be pressed without the program doing any geometry; a page anchor pressed on a Surface sends its anchor event as on the glass.

The eye is the host's, and the program is not told where it is, nor whether a pointer event was mapped.

Charges, caps and state

Nothing more is charged: a Surface is 11 bytes of the list, which a submit charges 1 unit per 4 bytes. At most 4 take effect in a list, each one face of the 256. The state is the list as submitted: which Surfaces are in effect depends on the list alone.

Example

A console below the middle of the screen, tilted back, showing the terminal's rows 4 to 11, columns 1 to 28; the text there stays where the program writes it:

#define U V3_UNIT

v3_begin(list, sizeof list);
v3_push();
v3_translate(320 * U, 380 * U, 0);
v3_rotate(V3_AXIS_X, 59164);  /* -35 degrees */
v3_surface(8, 64, 224, 128, 220 * U);
v3_pop();
v3_end();
v3_submit_list(list);

A click on the console arrives as a pointer event between (8, 64) and (231, 191). The holo program's cockpit (scene 6) has three such consoles: instruments that change every frame, a log, and a list chosen with the pointer.