summaryrefslogtreecommitdiff
path: root/docs/render-pipeline.md
blob: 64fa4e65dc03ae134f6c586ec375c124e458fc0f (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
# pardes render pipeline: the core's frame, then the frontend's own

What a frame is and who draws it, as it stands. The effects programme this
document planned (eleven panel transitions in two tracks, a Shadertoy post
chain with Crt, Bloom, Vignette and Grain, Lift and its soft shadows, the
glows, the terminal's chip shadow and thumb flash, the lapis ornament and
its parallax, the message fall and dissolve, the theme crossfade, five
Motion flavours with anticipation and squash, tiers and track groups) is
gone: the core keeps no motion and no clock but its deadlines, and each
frontend keeps the little it draws on its own.

## The core's frame

- `Pardes.pump` drives the host: `wait_input`, with the core's next
  deadline (`nextWake`: a message's linger, the look-hover preview, a
  question's hint, a paused Grep, work that resumes a frame at a time);
  `now`; `poll_frame`; `render` and `present` only when a frame is owed
  (`needs_frame`); and `post_present`, whose `Pardes.presented` lets a
  drag's moving end and a look-hover follow what is under the pointer now.
- `advance(now)` steps `.tick`s a `frame_ns` (16 ms) at a time, for the
  work that resumes a frame at a time; a wait is jumped in one step.
- `render` (draw.zig) paints one `Surface`: the canonical grid (`/screen`,
  the snapshot goldens, the tty), the regions (each part's rectangle,
  owner and focus; a body's first line and the text it shows,
  `Region.line` and `Region.doc`), the layers a pixel shell draws at the
  tagline's pitch and with compact context rows, the placements, the
  cursor and the palette (`Chrome`). Nothing on it moves.
- A placement (surface.zig's `Placement`) is a picture over the cells, a
  pane's at a time and lowest first: its pixels (`raster`: RGBA, straight
  alpha), the part shown (`src`), the cells it lies over and is clipped to
  (`dst`), where in them in pixels (`at`; none for an image pane, which
  the frontend fits there), a `key` that names those pixels (pane serial,
  page, revision) so a frontend keeps what it uploaded under it, a
  terminal program's kitty `z`, the rows that alone changed since an
  older key (`dirty`, a PDF's highlight), and how the pane wants it as
  glyph art (`art`: Petscii, Palette, Ascii). A PDF's body region carries
  its strip's scroll (`scroll_px`): its pictures lie at the whole pixel
  and a pixel frontend draws them the fraction higher. The core never
  draws a picture in the cells, so `/screen` (whose `images` lists the
  placements) is the same on every client.

## The frontends' own

Each draws these on its own clock, from the Surface alone, and draws their
frames itself while they move (the last frame again: the tty's
`poll_frame`, the window's loop), pacing its own waits:

| what | tty | window | from |
|---|---|---|---|
| a scroll's glide (glide.zig) | whole rows | the pixel | a body's line and doc between two frames, and the last frame's cells |
| the caret's ease | (the terminal's cursor) | its quad on critically damped springs (gui.zig's `Caret`) | the cursor and the focused body |
| the blink (`CursorBlink`) | (the terminal's) | the cursor's alpha | the window's last key or click |
| a jump's trail (`JumpTrail`, jump_trail.zig) | the ground behind the cursor, truecolor terminals | drawn over it, in the overlay | the cursor between two frames |
| `InactiveDim` | (kept, not drawn) | the unfocused panes' ink faded, never below its contrast floor | the regions' focus |
| `Pet` | (unsupported) | a sprite in the workspace tag's blank end (gui/pet.zig) | the grid's first row; SDL's ticks |
| a placement | a kitty image placed over its cells, or glyph art in them (Art.zig) without kitty graphics or when its pane asks | a texture by key, scissored to its cells, or glyph art when its pane asks | the frame's placements |

The settings these read are plain bytes in the core's settings, dumped
and replicated as any other; nothing a frontend keeps goes back to the
core.

## The window's composition

Four fixed draw groups, bottom to top: the page and the panes, the
notices, the guides and the debug box the core paints over them, and the
ink (bar cursors); then the overlay (the pet, a jump's trail, the caret's
quad). Decor is flat: rules, rails, grips, spines, notice rules and bar
cursors as hard-edged rectangles read from the regions.