screen: the program that owns the display.

  screen.talc           the display server: the card, the keyboard and the
                        mouse on one side, programs with windows on the
                        other, talking (canvas protocol) over a local socket
  lib/screen/drm.talc   (screen drm)  a card under /dev/dri: open, version,
                        capabilities, mastery, events, and the ioctl pieces
  lib/screen/kms.talc   (screen kms)  what a card shows and on what:
                        connectors, encoders, crtcs, modes, dumb buffers,
                        framebuffers, page flips, the cursor, dirty rectangles
  lib/screen/input.talc (screen input)  the keyboard and the mouse as the
                        kernel hands them over: event devices, grabbing,
                        events, a US keymap as data
  lib/screen/windows.talc (screen windows)  what the screen knows about its
                        windows: clients, surfaces and their popups, buffers,
                        order, focus, the pointer -- no handle touched, so it
                        can be tested without a card
  lib/screen/serve.talc (screen serve)  the protocol's server side: listening,
                        requests and their answers, input delivered to the
                        surface it concerns, frames once a tick
  lib/screen/compose.talc (screen compose)  the picture: the backdrop, every
                        window's shadow, frame and content -- the frames
                        drawn by ../look's (look frame) as the theme says;
                        which part of which frame a point is on
  lib/screen/policy.talc (screen policy)  what keys and mouse buttons do --
                        move, resize, maximize, raise, cycle, close, launch
                        -- from a bindings file of forms, like rc.xml
  lib/screen/keys.talc  (screen keys)  chords ("super+q") and text to key codes
  (the programs with windows are elsewhere: the terminal,
                        super+return, is ../terminal, the launcher,
                        super+space, is ../toolkit's; the screen finds
                        them on PATH or beside itself, collects them
                        when they end, and takes in what they leave
                        behind: a program the launcher started sits
                        under the screen once the launcher has ended)
  probes/               not programs to use but the card checked a layer
                        at a time, from the milestones that built them,
                        kept for bringing up a card the screen has not
                        run on (scripts/vm-show.sh runs them):
    gradient.talc       pixels on a card through the kernel's own
                        interface: a gradient, flipped once a frame
    poster.talc         the canvas on a card: text and shapes drawn into
                        a buffer the card scans out
    pointer.talc        the mouse and the keyboard on a card: a hardware
                        cursor, clicks painted, typing shown
  config/default.config the built-in bindings written out, with what each
                        does: the file to copy for one's own
  scripts/build.sh      builds screen.talc and probes/ into bin/,
                        against lib/ here, ../canvas/lib and ../look/lib
  scripts/regress.sh    the screen without a card: composes in memory with
                        two terminals, the shell and the launcher in it,
                        drives them from examples/drive.talc and compares a
                        picture at each step with examples/*.ppm
  scripts/vm-show.sh    boots ../vm's machine with nothing in it but one
                        tool and the fonts, runs it on the machine's card,
                        and leaves a picture of the screen in
                        build/vm/screen.ppm; VM_SCREEN=1 shows it in a
                        window instead, VM_FIRMWARE=efi boots it under
                        UEFI (simpledrm), VM_CARD=std on the bochs card,
                        VM_DRIVE types and clicks through qemu's monitor,
                        VM_BIN puts more programs in the machine's /bin

Build:

  scripts/build.sh

which needs the installed toolchain (compiler on PATH).

  bin/gradient /dev/dri/card1            three seconds of gradient
  bin/gradient /dev/dri/card1 -look      everything but the screen
  bin/poster /dev/dri/card1 ../canvas/fonts/plain-8x16.font
  bin/poster /dev/dri/card1 ../canvas/fonts/plain-8x16.font -look out.ppm

  bin/screen /dev/dri/card1 ../canvas/fonts -run ../terminal/bin/terminal
  bin/screen none ../canvas/fonts -picture out.ppm -seconds 3 \
             -run ../terminal/bin/terminal -shell ../shell/shell
  bin/screen /dev/dri/card1 ../canvas/fonts -theme ../look/themes/plain.theme \
             -config config/default.config -run ../terminal/bin/terminal
  bin/screen /dev/dri/card1 ../canvas/fonts -themes ../look/examples \
             -run ../terminal/bin/terminal      (then `themes` in the launcher)

The -look forms and `screen none` work while a desktop holds the card; the
others need a text console, because only one program at a time may set
what a card shows. scripts/vm-show.sh is the full thing with no console to
switch to:

  scripts/vm-show.sh gradient -seconds 8
  scripts/vm-show.sh poster /share/fonts/plain-8x16.font
  VM_BIN="../terminal/bin/terminal ../toolkit/bin/launcher ../shell/shell" VM_DRIVE=keys.txt \
      scripts/vm-show.sh screen /share/fonts -cursor software -seconds 12 -run /bin/terminal
  VM_SCREEN=1 VM_BIN="../terminal/bin/terminal ../toolkit/bin/launcher ../shell/shell" \
      scripts/vm-show.sh screen /share/fonts -cursor software -run /bin/terminal
  VM_SCREEN=1 VM_BIN="../terminal/bin/terminal ../toolkit/bin/launcher ../shell/shell" \
      scripts/vm-show.sh screen /share/fonts -cursor software \
      -theme /share/themes/left.theme -run /bin/terminal
  VM_SCREEN=1 VM_BIN="../terminal/bin/terminal ../toolkit/bin/launcher ../desktop/bin/themes ../shell/shell" \
      scripts/vm-show.sh screen /share/fonts -cursor software \
      -themes /share/themes -icons /share/icons -run /bin/terminal
  VM_SCREEN=1 VM_DISPLAY=gtk,zoom-to-fit=off VM_WIDTH=1920 VM_HEIGHT=1080 \
      VM_BIN="../terminal/bin/terminal ../toolkit/bin/launcher ../desktop/bin/themes ../shell/shell" \
      scripts/vm-show.sh screen /share/fonts -cursor software -scale 2 \
      -themes /share/themes -icons /share/icons -run /bin/terminal

which needs ../vm built, qemu with its virtio card, and python3. The
second is the screen in a window to use: the machine's pointer is a
tablet, so the window's pointer is the screen's pointer with nothing to
grab, and -cursor software draws the arrow into the picture, since the
window shows the card's cursor plane only now and then. The third is
the same with the title bar down the left side: ../look's themes are at
/share/themes in the machine. The fourth has the theme chooser in it: `themes`
typed into the launcher lists /share/themes and a pick changes the look of
everything on the screen while it runs. The fifth is the 960 by 540
screen shown on a 1920 by 1080 card with every pixel doubled (-scale 2,
nothing smoothed), in a window at 1:1 so that qemu does no scaling of
its own -- qemu's window smooths whatever it scales, which is why it is
not asked to.

THE SCREEN. One program owns the card and the input devices; every other
program with something to show asks it for a window and draws into a
buffer the two of them share ((canvas buffers)), telling the screen what
changed; the screen composes the windows onto the card and tells each
program what concerns it -- keys, the pointer, when to draw -- as talc
forms over a local socket ((canvas protocol); the whole set is listed
there). Programs the screen starts find it through SCREEN, SCREEN_FONTS (the
fonts' directory), SCREEN_THEME (the theme file, when one was given),
SCREEN_THEMES (the directory of looks, when -themes was given) and
SCREEN_ICONS (the directory of icon packs, when -icons was given:
../look/icons, or /share/icons on the machine; the theme names the pack) in
their environment. A program may ask for another look -- the (theme
"path") request, which ../desktop's chooser sends -- and the screen
takes it for every frame, tells every program, and starts later
programs with it. Inside, one
isolate reads each input device, one accepts clients, one reads each
client and one writes to each, and one ticks once a frame; the main
program receives from all of them and is the only one that touches the
windows, the card and the picture, so there is no moment at which two
things change the same state -- and it never waits on a client, so one
stuck program cannot stop the rest.

THE FRAMES are the screen's, not the programs'. A window is content; the
title bar, its buttons, the border and the shadow around it are drawn
around it by ../look's (look frame) as the theme says, (screen compose)
saying where, and the pointer on them is the screen's business ((screen
policy)): no program links a toolkit to get a frame, and changing the
look is editing a theme and pressing super+r -- ../look/README, where
the title bar can be put on any side of the window. The theme and the
bindings are files of forms, the way Openbox has a themerc and an
rc.xml; the built-in ones are written out as ../look/themes/plain.theme
and config/default.config, each line with what it does, and those are
the files to copy. A popup -- the launcher's list (../toolkit/tools/launcher.talc) -- is a frameless
surface a window hangs under itself, that moves with it and goes when
the pointer presses elsewhere; a translucent window is one whose pixels
carry alpha, laid over what is under it.

`screen none` is the screen with no card: it composes into memory, which
is how scripts/regress.sh runs the whole thing -- screen, terminal, shell
-- under no console at all and compares the picture. It is 960 by 540
unless told otherwise, as the machine in ../vm is: half of 1920 by 1080,
the size the windows here are designed at, to be scaled up on other
machines later.

What is here is pixels on a card
through the kernel's own interface, the canvas drawing on them, input,
clients with windows, frames and window management, and the looks --
a proportional font, shadows, alpha, popups and a launcher; a
clipboard, one text held for every client ((clipboard-set "text"),
(clipboard-get) answered by (clipboard text)), for the terminal and
the toolkit's field. The GPU renderer behind (screen compose), outline
fonts at any size and the rest are not here yet.