diff options
Diffstat (limited to 'docs/effects.md')
| -rw-r--r-- | docs/effects.md | 285 |
1 files changed, 285 insertions, 0 deletions
diff --git a/docs/effects.md b/docs/effects.md new file mode 100644 index 00000000..894bd75d --- /dev/null +++ b/docs/effects.md @@ -0,0 +1,285 @@ +# Effects: feel reviews + +**The rule above all the others:** no effect may alter or cover a focus +indicator (the focused pane's tag colour, its grip, the cursor, the +selection) or reduce its contrast. The effects are sugar; the indicators are +how a person knows where they are. Every G stage is reviewed against this. +Lift, for one, falls only on pane bodies and rails, never on a tag, a grip or +a header, and its strength is capped so text and the selection keep min(their +contrast, 4.5) (tests in src/gui/gui.zig). The rule binds effects, not a +theme's structure: the rules between panes (2px, `rule_px`) are the theme's +borders, and the one over a tag band stays in the band's slack, never over +its text. A dim touches only the unfocused +panes, with the same floor, and the focused pane's text is never at less +contrast than theirs (tests in src/draw.zig). + +**Density.** A pixel shell draws every size given in pixels in logical +pixels, `dp()` in gui.zig (SDL's window display scale, rounded, at least +one; `PARDES_TEST_SCALE` forces one in a harness, and a test window is 1x +otherwise): the rules (`rule_px`), the tag rule, the grip's ring and its +dirty gap and mode bars, the rail's gap to the text and its minimum, the +thumb's inset, the rim, a bar cursor's minimum width, underline and +strikethrough thickness, the rule-grab margin, and the Crt's scanline and +mask periods (`pardesScale`). Left as they are: what is measured in cells +or the tagline (the rail's width, `rail_px` scaled with the tagline; Lift's +blur and offsets; every motion, in cells), Shadertoy's iResolution, +fragCoord and iMouse (the display's pixels, as ghostty's), and the pet and +touch debug overlays. + +Each effect of docs/render-pipeline.md §9 lands behind its own switch, off, +and is kept only after a feel review (§8.4): a frame series on the virtual +clock, a recording, and a verdict — keep, polish or drop — with one line of +why. The verdict is the user's. + +| effect | switch | state | review material | verdict | +|---|---|---|---|---| +| Crt (bundled post pass) | `Crt 0..3` | kept, rewritten (no barrel) | fx-compare stills, live window | kept at the user's live look | +| Ripple, Glitch | — | removed | live window | dropped by the user after a live look | +| G1 lift | `Lift shadow\|rim\|auto` (off), `InactiveDim <percent>` | opt-in until the focus-lift default is decided | lift-shots-2 (off, shadow, rim, auto on acme, dusk, forge); frame series + mp4 per Motion flavour | shadow on acme: keep as is. Round 1 dropped glow and surface (surface lowered the focused text's contrast) and made rim a hairline just above the focused tag (light on a dark page, shade on a light one). auto on a dark page recedes the others (InactiveDim 30) | +| G3 cursor | follows `Motion`; `CursorBlink on\|off` (on) | glide on by default through the default flavour (smooth); blink on (decision 6) | .scratch/render/cursor/cursor-flavours-grid.mp4 (and quarter speed), raw/<flavour>/<motion>/ | pending | +| G4 bloom, vignette, grain | `Bloom`, `Vignette`, `Grain` `0..3` (off) | bundled post passes; none touches a tag, grip, notice or the cursor (pardesSpare); each capped per theme (pardesCap) | .scratch/render/{bloom,vignette,grain}/ (levels 0-3 on forge, dusk, acme; crops; mp4 stepping through the levels) | pending | +| G5 lapis | `Theme lapis` (its `decor`) | a native theme with ornament: tag plaques with hard shadows inside their bands (the focused one striped), dots, rail checker, title shadow | .scratch/render/lapis/ (whole window at 1x and 2x, crops, a slide mp4) | pending | +| G6 smooth scroll | follows `Motion` (on through the default smooth; `Motion off` lands at once) | a mouse wheel's notch glides, a touchpad follows the finger | .scratch/render/scroll/ (glide-<flavour>.mp4, quarter speed, strips) | pending | +| G7 panel transitions | `PanelSlide`, `PanelZoom`, `PanelVertical`, `PanelDissolve` (off) with `Motion` | a moving pane casts a shadow; a retargeted move keeps its speed; the GUI's dissolve is a crossfade | .scratch/render/transitions/ (slide smooth, bouncy, retargeted; dissolve) | pending | +| G8 notice chips | follows `Motion` and `Lift` | a notice floats in tier 4 on a lift (shadow) while Lift is on, drops in easing out and dissolves easing in, quicker than it came (150 ms against 180) | .scratch/render/notices/ (acme, forge) | pending | +| G9 selection glow | `SelectionGlow on\|off` (off) | a soft halo of the selection's colour round each block of it in a body, fading in over 100 ms | .scratch/render/selection/ (forge, acme, lapis; lapis-glow-zoom.png) | pending | +| G10 theme crossfade | always (a theme change) | the chrome's colours fade through OKLab, easing in and out (out when retargeted) | .scratch/render/crossfade/ (forge, lapis, acme cut short by dusk) | pending | +| G11 look-hover glow | `HoverGlow on\|off` (off) | a soft underline of the theme's accent under the word a look-hover would open, fading in over 80 ms | .scratch/render/hover/ (forge, acme, lapis; zooms) | pending | +| G12 ambient occlusion | `Occlusion on\|off` (off) | pane bodies darken toward their edges, at most 2% (§9.1: 1 to 2%) | .scratch/render/occlusion/ (on/off on forge, acme, lapis; acme-diff-x40.png) | pending | +| G13 parallax | `Parallax on\|off` (off) | a theme's page pattern under the bodies (lapis's dots) moves with the text at a quarter of its speed, glides included | .scratch/render/parallax/ (lapis, notches down and up) | pending | +| G14 afterglow | — | removed | live lapis showcase | dropped by the user: "one of the animations is like a flashing on the whole pane or something, that is really bad, just remove it" (a pane whose whole text changed, a file opened, a +Search refilled, a terminal's output, lit up at once) | + +## Motion flavours + +`Motion off|crisp|smooth|bouncy|playful` (default smooth, tuned so arrivals +land inside §8.1's 220 ms; bouncy and playful run longer, opt-in) is one parameter set +(animation.Motion) every fx animation reads, so a flavour is data, not a +branch in each effect. Input is never blocked, and a new target always +retargets from the current position and velocity. + +| flavour | timing (ω, length) | follow-through (ζ) | anticipation | squash/stretch | exaggeration (gain) | secondary lag | arcs | +|---|---|---|---|---|---|---|---| +| off | instant | — | — | — | — | — | — | +| crisp | 60, 0.6× (leaves at full speed) | 1 (none) | — | — | 1 | in step | — | +| smooth | 34, 1.1× (slow in, slow out; ≤220 ms) | 1 (none) | — | — | 1 | 0.85 | 0.04 | +| bouncy | 24, 1.4× | 0.35 (overshoots ~30%, settles twice) | — | 0.15 | 1.25 | 0.8 | 0.08 | +| playful | 18, 1.7× | 0.28 (overshoots ~40%) | 0.15 of the move | 0.35 | 1.4 | 0.55 | 0.15 | + +The flavours are distinct by design, not tuning: crisp leaves at full speed +and never passes its mark; smooth takes twice as long and eases in and out; bouncy clearly passes its mark and settles back once or twice; +playful winds up the other way first, flies well past, and stretches along +its path and squashes as it lands, its text with it (the user's choice); a +pointer inverts the same stretched box, and landed, a pane is exactly its +target. A motion only a few pixels big (Lift) is +exaggerated by the flavour's gain so its character shows. The flavours drive +the Lift spring (time-based), the notice drop and the pane moves (PanelSlide, +PanelZoom, PanelVertical opening or moving, whose length scales with the +flavour); a closing pane keeps its effect's own exit. Chart and side-by-side +video: .scratch/render/motion/compare/. + +Which principles each motion uses: + +- **Lift** (G1): timing, slow in / slow out (the spring), follow-through + (bouncy and playful lift past full and settle back), anticipation (playful + dips before it rises; below zero nothing is drawn, so it reads as a beat + before the lift), staging (only the focused pane lifts; nothing else moves + with a focus change), exaggeration (the flavour's gain). Squash, stretch, + arcs and secondary lag have nothing to act on in a lift. +- **Notice drop and pane moves**: timing and follow-through from the flavour's + spring over the move's length; anticipation (playful). A pane past its mark + never takes a neighbour's click, a rising one stays in its box, and a notice + past its row stays in its pane's body. +- **Cursor** (G3): timing (the flavour's spring, 2.4x its pace: it follows + input), follow-through (bouncy and playful pass the target), squash and + stretch and secondary action (the trailing corners lag by the flavour's + follow, so a jump smears and collapses), arcs (a jump over 8 cells bows by + the flavour's arc), anticipation (playful's wind-up). A step of a cell or + less, or any move in insert mode, lands at once, so typing never trails; + a scroll carries the cursor with the text. Only the focused cursor moves. + A pane that moves carries it too: the springs keep its place in the pane + and the quad is drawn through the pane's presented box, so through a + slide, a zoom or a drag it rides with the text, and a layout change with + no transition lands it with the text. A focus change (to another pane, or + into a column's or the workspace's tag) glides from where the cursor is + drawn to the new one, free of the old pane's edges while it crosses + (.scratch/render/cursor/move/: ride-*, cross-*). + + +Notes on G1: the lift and the dim run on one focus spring per pane, at the +Motion flavour's pace, sampled at each frame's own time; while it moves the +GUI draws at the display's rate, and a grid snaps. A notice floats on a lift +of 1 while a shadow or rim is on. InactiveDim under `Lift auto` defaults to +30. The fade is in linear light, so on a dark page it is gentle: at 30 +forge's text goes from 15.5:1 to 11.2:1 and dusk's from 6.4:1 to 4.8:1, +plainly quieter and still easy reading; at 10 forge barely moves (14.1:1). +On a light page the same percent bites far harder (acme: 7.0:1 at 10, the +4.5 floor at 30), which is why `auto` shades there instead of dimming. + +Notes on G4: the three are post passes, so each is a frame of cost only +when it is in the chain. None moves (grain is still, by choice: moving +grain would redraw every frame for a texture), so none asks for frames. +The focus rule is kept by construction: the shell hands every pass the +rectangles of the tags (with their grips), the column and workspace tags, +the notices and the cursor, and a bundled pass leaves them as they are; its +strength is capped per theme so the text on the page and the selection's +text keep min(their contrast, 4.5) (Post.capsOf, tested over the native +themes). Bloom takes only what is brighter than the page, so a light page +does not bloom at all; its glow is a dual Kawase blur in float textures at +half size and down (3 to 5 steps by level), within §8.2's 5%. The vignette +is round, starts halfway to a corner and reaches 10, 18 and 28%. Grain is +1.5, 3 and 5 of 255 on page-coloured pixels only, a logical pixel big. +Found on the way: SDL GPU binds at most 4 KiB of a uniform block, so every +Shadertoy colour after the palette (iBackgroundColor and on) read zero; the +block is now cut in three with ghostty's names and order kept. + +Notes on G5: lapis (src/themes/lapis.zig) is 0x4200.cafe's lapis.css in +pardes's chrome, drawn inside it (decision 1). The tags are the site's +trail and title bars: every tag a plaque in its own band, framed in gold +(2 px, the trail's border) with the trail's hard vermilion shadow (5 px) +down and right, the frame and the shadow both inside the band's rows and +columns, so no shadow reaches a body, a grip or the next pane; down, the +shadow gets what the band's slack under the text leaves (a pixel or three +at a tagline under the body's size, more at a larger one), to the right +its full offset. The focused pane's plaque is the code window's title bar, +gold and lapis stripes of 2 px, its words on plates of the focused ground +(the words' cells stay opaque, the blanks between let the stripes show), +so the focus indicator is plainer to see than any theme's tint, never +less; the unfocused ones are plain. Column and workspace tags take the +quieter object-label language: a 1 px frame and a 2 px shadow of vermilion +toward the page. The plaques are decor drawn under their cells (a group's +under range) with the cells blended premultiplied over them; blank tag +cells on the tag's ground are see-through there. They need an opaque +window: under WindowOpacity 100 the tags are plain. Also from the site: +the colours (lapis-deep page, vellum text, gold names and rules, +vermilion rubrics and tag rule, gold selection in lapis ink), the page's +gold dot grid (22 px, #e8c46a22) on page-coloured cells only, fixed to the +window; the dither frame's checker in the scroll track, anchored to its +rail (the thumb solid gold); the titles' vermilion offset shadow under a +file name's letters. Left out: Crimson Pro and Departure Mono, the +ornaments, a decor crossfade (it snaps while the colours fade). The tty +shows the colours alone: a tag row abuts its body and its neighbour, so +there is no cell for a shadow row or column. + +Notes on G6: a mouse wheel's notch (SDL's whole-number step) scrolls the +core by its lines at once, so keys and clicks act where the text is, and +the picture follows on the Motion flavour's spring at half again its pace, +critically damped whatever the flavour (text never passes its mark; §8.1), +from its current speed, so notches in a row carry on without a stall. How +far the rows moved is measured on the next frame against the last (a +wrapped line's rows, a terminal's output), within a couple of rows' slack +for the cursor's line and its number moving with the scroll; the rows that +left are kept and drawn in the gap the lag opens, and a lag is never more +than the body's height (a flick past that jumps). A touchpad's fractions +keep moving the picture under the finger, as before; there is no momentum +(SDL reports no finger lift on a wheel). The glide runs on the core's +continuous path (Pardes.shell_continuous), so the shell draws every loop +while it moves and a virtual clock moves with it; idle, it costs nothing. +A PDF page scrolls as before. The test feed takes wheel events +(ESC]777;mouse;wheel;<amount>;<x>;<y>BEL). + +Notes on G7: the geometry already followed the Motion flavour's spring +(sxrrwplk); a move retargeted mid-way now carries its speed on +(Track.launch, from the old move's speed along the new one's longest +side), so a second Newcol during a slide bends the motion instead of +stopping it dead. A pane that slides, zooms or rises stands off the page +while it moves: a soft shadow as Lift's, at sin(pi x progress) of its +strength (none as it sets out or lands), on the other panes' bodies and +rails alone and under the same contrast ceiling, moving with the pane. The +GUI's PanelDissolve is a crossfade: a changed cell's new form drawn whole, +its old one over it at 1 - progress; the blend is in sRGB, not linear +light (a two-colour mix in linear light needs both in one shader; open +point 3). The tty keeps its per-cell swap. GUI golden 18-mid-transition +changes (the slide's shadow at frame 6). + +Notes on G8: most of it was there: the drop eases out on the Motion +flavour's spring (sxrrwplk), the dissolve eases in, and a notice floats in +tier 4 with Lift's shadow at its fade while Lift is on, on the bodies +alone. What G8 changed: leaving was slower than arriving (a 300 ms +dissolve against a 180 ms fall); §8.1 wants leaving the quicker, in 100 to +160 ms, so MessageDissolve now defaults to 150 (a test holds both bands). + +Notes on G9: the halo is Lift's soft kind in the selection's own colour, +cast by each block of selected rows in a pane body (the rows that touch), +with the block as its caster, so the selection itself is never touched; +a cursor beside a block joins the caster, so it is never glowed over +either. It stays on bodies (never a tag or a grip), is at most 22% (§8.2: +coloured glows at most 25%) and less where the text round it would drop +below min(its contrast, 4.5); it comes up over 100 ms with an ease-out +(micro-feedback), on the core's continuous path, and is not drawn while +panes move. The blocks are read from the cells painted in the theme's +selection colour, a pixel shell's inference (§1.5, smell 4) until +selections are regions. + +Notes on G10: a theme change already faded the chrome (tags, rules, grips, +rails) over 10 frames (160 ms, in §8.1's 150 to 250 for a state change), +mixing sRGB bytes linearly in time. Now each colour goes through OKLab, so +a fade between two hues keeps its lightness instead of dipping dark and +muddy, on a smooth ease-in-out; a change made mid-fade sets off from where +it shows and eases out, so it moves at once instead of stalling. The page, +its text and the syntax colours still change at once with the theme, as +before: fading them would re-resolve every cell each frame. + +Notes on G11: the word a look-hover would open is already lit (the +affordance's tint); HoverGlow adds a strip three logical pixels tall along +its foot in the theme's accent, its edges blurred by one, at most 22% and +under the text's contrast floor, fading in over 80 ms (micro-feedback). It +stays on bodies and is split round a cursor, so it never touches one. The +word is found by the tint's colour, as G9 finds the selection. +Found while reviewing: with the machine loaded, test/gui_golden.py's +two-captures-agree settle can take a scene's frame before the scene's +change lands, and every later hash moves up a scene; a rerun on a quiet +machine matches. + +Notes on G12: four soft strips cast from just outside each body inward, +clipped to it and round a cursor, black in linear light, 2% at most and +under the lift's contrast ceiling, in the pane's own group so it moves +with it. At §9.1's strength it is all but invisible on a dark page (a +level of 255 on forge) and faint on a light one (acme's page steps one +level toward the edges); acme-diff-x40.png shows where it falls. + +Notes on G13: a body region now carries its first line (Region.line: a +file's scroll, a terminal's grid offset; on the wire, a u32 more a +region). Under Parallax the dots under each body are offset by a quarter +of its line times the row height, plus G6's glide offset while one runs, +so they drift with the text as it glides and settle with it (measured: 4 +lines at 35 px move the 22 px grid 13 px, 35 mod 22). The cell shader +reads the offset from the instance's serial slot, free since G7 took the +dissolve's per-cell noise out. Without a pattern, nothing happens. + +Notes on G14: removed with its builtin, setting and code after the user +saw it in the lapis showcase: "one of the animations is like a flashing on +the whole pane or something, that is really bad, just remove it". Every +changed cell glowing meant a pane whose whole text changed flashed whole. + +## Terminal track (§9.2) + +Audit, after decision 2 (keep every whimsical effect and polish it, never +remove it): the six core-composed character transitions (ascii, edges, +fall, wave, scramble, typewriter) and curtain stay as they are, each +bounded to its pane's final rectangle and each cell's last sample its +canonical one; slide and vertical are the tty compositor's and follow the +Motion flavour (sxrrwplk); zoom stays (nearest-cell scaling, its look is +the effect); dissolve swaps each changed cell once at its threshold; +message fades and the theme's chrome fade are the core's (the latter in +OKLab since G10), and InactiveDim (T5's unfocused dim) works in a grid as +it does in a pixel shell. + +| # | effect | switch | state | review material | verdict | +|---|---|---|---|---|---| +| T2 | cursor jump trail | `JumpTrail on\|off` (off) | a jump of three cells or more leaves 3 to 5 cells of trail behind the cursor, their ground drawn toward the text's colour in OKLab, most beside it, fading in 120 ms; truecolor terminals (vaxis's answer or COLORTERM); never the cursor's cell, a selection or outside the focused body; off under Motion off; a few cells a frame | .scratch/render/tty/trail/ (pyte replay of a real tty session at 60 fps: trail-forge.mp4, zooms) | pending | +| T1 chip shadow | `ChipShadow on\|off` (off) | a notice chip casts a shadow a cell right and down in its body: half blocks (▌ ▀ ▘) in a darker ground on blank cells, the ground 35% darker (OKLab) under text; never the cursor, a selection, a tag or another chip; truecolor only | .scratch/render/tty/shadow/ (forge, acme; zooms) | pending | +| T4 ordered swap | `PanelDissolve` (off) | the terminal's dissolve swaps each changed cell once at its place in a 4x4 Bayer matrix (shifted per pane), an even patterned screen instead of noise; hit-testing follows the same order | .scratch/render/tty/dissolve/ (ordered-swap-sim: the matrix applied to two real frames; see note) | pending | +| T7 thumb flash | `ThumbFlash on\|off` (off) | a pane whose view moves has its scroll thumb drawn toward the text's colour, 60% at once and back over 250 ms (quadratic); the thumb only, never a focus indicator; truecolor only; a few cells a frame while it fades | .scratch/render/tty/thumb-flash.mp4, thumb-flash-strip.png (pyte replay, forge) | pending | +| T3 wipe | `PanelCurtain` (off) | the curtain becomes a wipe, left to right: new grid behind the head, old ahead, and a soft edge of two columns whose ink and ground sit 2/3 and 1/3 of the way to the old ground (OKLab; a palette colour steps at the half); only the head's columns change a frame; the head's cells are not hit-testable until settled | .scratch/render/tty/wipe/ (curtain-gui.mp4, curtain-edge-zoom.png) | pending | + +Note on T4's material: a pane opening in a tty session recorded through +pyte did not animate (PanelSlide did not either there), so the review +material applies the same matrix to two real frames of that session; the +unit test holds the order (a 4x4 block reveals exactly t x 16 cells). + +Not built: T5 (unfocused dim) is InactiveDim, which already works in a +grid. T6 (a truecolor ramp on the active tag band) would change the +focused tag's colour, a focus indicator no effect may alter, so it stays +out. The §9.2 byte budget (deferring a sample after an oversized frame, +DECRQM for sync 2026) is not built either: the terminal effects here change +a few cells a frame, and only PanelSlide rewrites a whole pane per sample. |
