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
| Op | Command | Operands (bytes) | Effect |
|---|---|---|---|
0Eh | Surface | x, 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.