summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/render-pipeline.md18
-rw-r--r--docs/typ/reference.typ12
2 files changed, 26 insertions, 4 deletions
diff --git a/docs/render-pipeline.md b/docs/render-pipeline.md
index 49180ad3..64fa4e65 100644
--- a/docs/render-pipeline.md
+++ b/docs/render-pipeline.md
@@ -23,8 +23,21 @@ frontend keeps the little it draws on its own.
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 images, the cursor
- and the palette (`Chrome`). Nothing on it moves.
+ 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
@@ -40,6 +53,7 @@ frames itself while they move (the last frame again: the tty's
| 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
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index cb2df2a8..b515e1b2 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -572,7 +572,9 @@ drawn: glyph art (`on`) or pixels (`off`). With no graphics it is always
colours the glyph art uses, the C64's (`commodore`) or the terminal
theme's own 16 (#word("Palette") toggles it); `ascii` is whether the
printable ASCII bitmaps join the glyph set the matcher picks from
-(#word("Ascii") toggles it). #word("Palette") and ascii only change the glyph art.
+(#word("Ascii") toggles it). #word("Palette") and ascii only change the glyph art,
+which the frontend draws: a tui without graphics always, a window when
+#word("Petscii") is on.
#word("Petscii") and #word("Ascii") (`on|off`) and #word("Palette")
(`commodore|terminal`) take the value their tag word shows and set it, as
a PDF's #word("PdfFit") (`width|height`) and #word("PdfTint")
@@ -931,7 +933,13 @@ at 200, ending in `…`. Control characters become spaces.
row 5. Cells are #file("/screen")'s.
- #file("/screen"): JSON `cols`, `rows`, `cursor`, `styles`, and row-major
`cells` of `[grapheme, style_index]`; one frame per open. Compare a
- cell's style through `styles`, not the index.
+ cell's style through `styles`, not the index. A frame with pictures
+ (an image, a PDF's pages, a terminal program's kitty images) has
+ `images` too, a `{serial, rect, src, key, petscii}` each: the pane, the
+ cells it lies over (`[x, y, w, h]`), the part of its pixels shown, a
+ key naming those pixels, and whether its pane asks for glyph art. The
+ cells under a picture are the pane's ground: the glyph art a terminal
+ without graphics shows there is drawn by the frontend, not the core.
- #file("/commands"): `Word [arg] root|pane|both [values] -- sentence`, one
a line, generated from the builtin registry (`both`: #word("Edit"), at the active
pane from the root).