//! The view's glide (G6, anim 3, 9, 12): a frontend's own picture of a //! scroll, on its own clock, from the frames it draws alone. Whatever //! scrolls a text (a wheel's lines, Ctrl-d, a page, G, n, a Look) scrolls //! the core at once, so every key and click acts on where the text is; the //! frontend sees a body's first line move between two frames (Region.line) //! and its picture follows there, critically damped (text never passes its //! mark), every distance on the same law. The GUI draws it at the pixel; //! the tty at whole rows (tui.zig's glideRows). Nothing here reaches back //! into the core. const std = @import("std"); const pardes = @import("pardes.zig"); const config = @import("config.zig"); /// How far the rows moved is measured on the frame against the last drawn, /// a line wrapped over several rows or a terminal's output included, and /// the rows that left are kept to draw in the gap. A move past what the two /// frames share (a page and more, G) has no rows between them to show: the /// picture comes from the last frame's body as if it lay just past the new /// one, one body away, so a jump of any length reads as one body's slide. /// /// The picture's motion is one system with its own state, integrated in /// one place every frame (`Follow.advance`), and every scroll, whatever /// made it, is an input into it (`Follow.kick`): it moves the target by the /// rows the core moved and leaves the motion as it is. Inputs coming as a /// stream (each like the last, at a steady spacing: a held key, a spun /// wheel) feed it at the stream's own rate; an input into a resting view, /// or against the way it moves, starts the spring from the speed it has; a /// jump mid-glide adds its rows with the speed kept. pub const Glide = struct { /// The picture's lag behind the core's rows and its motion (rows). follow: Follow = .{}, now_ns: u64 = 0, pane: usize = 0, rect: pardes.Rect = .{ .x = 0, .y = 0, .w = 0, .h = 0 }, body_y: u16 = 0, body_h: u16 = 0, /// The way the last scroll went, and the body's rows before it. dir: i8 = 0, before: []pardes.Cell = &.{}, /// The rows past the body's top (`above`) and bottom (`below`), nearest /// first, `bw` cells each: what the gap shows while the picture lags. above: []pardes.Cell = &.{}, below: []pardes.Cell = &.{}, nabove: u16 = 0, nbelow: u16 = 0, /// The core's lines a scroll moved, not yet measured; and what the /// glide in flight has moved, in lines and in the picture's rows. A /// wrapped line is several rows, and the thumb counts lines. pending_lines: f32 = 0, lines_moved: f32 = 0, rows_moved: f32 = 0, /// The caret's row as the last frame drew it, and whether the move /// measured carried it with its line (a wheel's) or left it on its row /// (a page, a held key's): the tty draws a carried caret with the rows. caret_row: ?u16 = null, caret_rides: bool = false, /// Each body as the last frame showed it, by its pane: its serial, /// first line, text and place, so a view that moved since is found /// whatever moved it. seen: [pardes.MAX_PANES]struct { serial: u32 = 0, line: i32 = 0, doc: u64 = 0, rect: pardes.Rect = .{ .x = 0, .y = 0, .w = 0, .h = 0 } } = @splat(.{}), /// Each body's rows held at its top while it scrolls (a source's /// sticky context rows, TreeContext), its frontend's to say: they do /// not move, so a move is measured, and the rows that left are kept, /// below them. held: [pardes.MAX_PANES]u16 = @splat(0), /// The last frame's cells, which a move is measured against. last: []pardes.Cell = &.{}, last_cols: u16 = 0, last_rows: u16 = 0, /// The rows kept past each edge, in bodies, so a jump made while one /// glides carries on from where it is: as far as the picture may lag. pub const reach = Follow.reach; pub fn moving(glide: *const Glide) bool { return glide.follow.moving(); } pub fn stop(glide: *Glide) void { glide.follow = .{ .at_ns = glide.follow.at_ns }; glide.nabove = 0; glide.nbelow = 0; glide.pending_lines = 0; glide.lines_moved = 0; glide.rows_moved = 0; } /// The glide's lag in the core's lines: its rows, scaled by the lines /// they carried. pub fn lagLines(glide: *const Glide) f32 { if (glide.rows_moved == 0) return glide.follow.offset; return glide.follow.offset * glide.lines_moved / glide.rows_moved; } pub fn deinit(glide: *Glide, gpa: std.mem.Allocator) void { gpa.free(glide.before); gpa.free(glide.above); gpa.free(glide.below); gpa.free(glide.last); } pub fn bw(glide: *const Glide) u16 { return glide.rect.w -| config.GUTTER; } /// The rules at this body's size: a tenth of a pixel is 5e-3 rows. pub fn pace(glide: *const Glide) Follow.Pace { return Follow.pace(@floatFromInt(glide.body_h), 5e-3); } /// The frame about to be drawn, at `now_ns` on the frontend's clock: /// the glide moves on to now, and a body whose first line moved since /// the last frame (the same text in the same place) is measured against /// that frame and kicks it. A terminal's view glides only under the /// wheel (`wheeled`: its output scrolls it at every line, and that is no /// glide); not one the frontend moves by the pixel (`direct`). One glide /// at a time: the focused body's, else the one that moved most. pub fn frame(glide: *Glide, gpa: std.mem.Allocator, surface: *const pardes.Surface, now_ns: u64, wheeled: ?usize, direct: ?usize) void { glide.now_ns = now_ns; defer glide.remember(gpa, surface); if (glide.follow.moving()) { glide.follow.advance(now_ns, glide.pace()); if (glide.follow.offset == 0) { glide.nabove = 0; glide.nbelow = 0; glide.lines_moved = 0; glide.rows_moved = 0; } } var pick: ?pardes.Region = null; var delta: i64 = 0; var shown: [pardes.MAX_PANES]bool = @splat(false); for (surface.regionList()) |region| { if (region.kind != .body or region.owner >= glide.seen.len) continue; const id: usize = region.owner; shown[id] = true; const was = glide.seen[id]; glide.seen[id] = .{ .serial = region.serial, .line = region.line, .doc = region.doc, .rect = region.rect }; if (was.serial != region.serial or was.doc != region.doc or was.line == region.line) continue; // The last frame drew this body where it is now: a pane that // moved or was resized in the same step has no picture to glide // from. if (!std.meta.eql(was.rect, region.rect)) continue; if (region.doc == 0 and wheeled != id) continue; if (direct == id) continue; const moved = @as(i64, region.line) - was.line; if (pick) |best| if (best.active or (!region.active and @abs(moved) <= @abs(delta))) continue; pick = region; delta = moved; } for (&glide.seen, shown) |*seen, here| if (!here) { seen.* = .{}; }; const body = pick orelse return; const r = body.rect; const rect: pardes.Rect = .{ .x = r.x -| config.GUTTER, .y = r.y, .w = r.w + config.GUTTER, .h = r.h }; // A new pane or place: what was kept belongs to another picture. if (glide.pane != body.owner or !std.meta.eql(glide.rect, rect)) glide.stop(); glide.pane = body.owner; glide.rect = rect; glide.body_y = r.y; glide.body_h = r.h; const w = r.w; if (w == 0 or r.h == 0 or glide.last_cols != surface.cols or glide.last_rows != surface.rows or r.x + w > surface.cols or r.y + r.h > surface.rows) return glide.stop(); // The body as the last frame drew it, which the move is measured from. const n = @as(usize, w) * r.h; if (glide.before.len < n) glide.before = gpa.realloc(glide.before, n) catch &.{}; if (glide.before.len < n) return glide.stop(); for (0..r.h) |row| @memcpy(glide.before[row * w ..][0..w], glide.last[(@as(usize, r.y) + row) * glide.last_cols + r.x ..][0..w]); glide.dir = @intCast(std.math.sign(delta)); glide.pending_lines += @floatFromInt(@abs(delta)); glide.measure(gpa, surface); } /// This frame's cells and caret, for the next frame's measure. fn remember(glide: *Glide, gpa: std.mem.Allocator, surface: *const pardes.Surface) void { if (glide.last.len != surface.cells.len) { gpa.free(glide.last); glide.last = gpa.alloc(pardes.Cell, surface.cells.len) catch &.{}; } if (glide.last.len != surface.cells.len) { glide.last_cols = 0; return; } @memcpy(glide.last, surface.cells); glide.last_cols = surface.cols; glide.last_rows = surface.rows; glide.caret_row = if (surface.cursor) |c| c.y else null; } /// Finds how far the pane's body rows moved, `dir` rows at a time, by /// the rows of `surface` against `before`; keeps the rows that left. fn measure(glide: *Glide, gpa: std.mem.Allocator, surface: *const pardes.Surface) void { const w = glide.bw(); const x0 = glide.rect.x + config.GUTTER; if (w == 0 or glide.body_h == 0 or x0 + w > surface.cols or glide.body_y + glide.body_h > surface.rows or glide.before.len < @as(usize, w) * glide.body_h) return glide.stop(); // The rows under the held ones (`held`) are what scrolls: `before` // and the frame are compared, and kept, from there. const top = @min(glide.held[glide.pane], glide.body_h -| 1); const h = glide.body_h - top; const now = struct { fn row(s: *const pardes.Surface, x: u16, y: u16, n: u16) []const pardes.Cell { return s.cells[@as(usize, y) * s.cols + x ..][0..n]; } }; // The least shift under which the rows agree, but for a few: the // cursor's line and its number's weight move with the scroll. The // lines the core moved are tried first: unwrapped, they are the // rows, and one pass over the body settles it (the search over // every shift was 6 ms of the first frame of a page in Debug). const agrees = struct { fn at(gl: *const Glide, surf: *const pardes.Surface, x: u16, width: u16, height: u16, kk: u16) bool { if (kk == 0 or kk + 3 > height) return false; const allowed = @max(2, (height - kk) / 8); var misses: usize = 0; for (0..height - kk) |r| { const rr: u16 = @intCast(r); const held = @min(gl.held[gl.pane], gl.body_h -| 1); const old_row = gl.before[@as(usize, held + if (gl.dir > 0) rr + kk else rr) * width ..][0..width]; const new_row = now.row(surf, x, gl.body_y + held + if (gl.dir > 0) rr else rr + kk, width); if (!sameRow(old_row, new_row)) { misses += 1; if (misses > allowed) return false; } } return true; } }; const guess: u16 = @intFromFloat(@min(glide.pending_lines, @as(f32, @floatFromInt(h)))); // A body's lines or more: every row moved off, none in common. var shift: u16 = if (guess >= h) 0 else if (agrees.at(glide, surface, x0, w, h, guess)) guess else found: for (1..h) |k| { if (agrees.at(glide, surface, x0, w, h, @intCast(k))) break :found @intCast(k); } else 0; // Rows that disagree under every shift though the core moved a few // lines: their colours changed as they moved (a paint arriving as a // spin stops). Unwrapped, the rows moved are the lines: glide those // (it landed from wherever it was, a snap at a spin's end). if (shift == 0 and guess > 0 and guess < h) shift = guess; // None in common: a body's move from the last frame's body, if the // lines moved are that many (rows that merely changed, a small // scroll the rows cannot show, land at once). if (shift == 0 and glide.pending_lines + 3 < @as(f32, @floatFromInt(h))) return glide.stop(); const far = shift == 0; if (far) shift = h; glide.caret_rides = !far and if (glide.caret_row) |old| if (surface.cursor) |c| @as(i32, c.y) == @as(i32, old) - @as(i32, shift) * glide.dir else false else false; glide.rows_moved += @floatFromInt(shift); glide.lines_moved += glide.pending_lines; glide.pending_lines = 0; // The rows that left: past the top going down, the bottom going up. if (!glide.ensure(gpa)) return glide.stop(); const keep = if (glide.dir > 0) &glide.above else &glide.below; const count = if (glide.dir > 0) &glide.nabove else &glide.nbelow; const kept = @min(count.*, h * reach - shift); std.mem.copyBackwards(pardes.Cell, keep.*[@as(usize, shift) * w ..][0 .. @as(usize, kept) * w], keep.*[0 .. @as(usize, kept) * w]); for (0..shift) |i| { const src_row: usize = top + if (glide.dir > 0) shift - 1 - i else h - shift + i; @memcpy(keep.*[i * w ..][0..w], glide.before[src_row * w ..][0..w]); } count.* = kept + shift; // What came into view is no longer past the other edge. const other = if (glide.dir > 0) &glide.below else &glide.above; const other_n = if (glide.dir > 0) &glide.nbelow else &glide.nabove; // ...and after a jump, the rows past it are another place's. const dropped = if (far) other_n.* else @min(other_n.*, shift); std.mem.copyForwards(pardes.Cell, other.*[0 .. @as(usize, other_n.* - dropped) * w], other.*[@as(usize, dropped) * w ..][0 .. @as(usize, other_n.* - dropped) * w]); other_n.* -= dropped; // An input: the core's rows moved by as many (down positive). glide.follow.kick(@as(f32, @floatFromInt(shift)) * @as(f32, @floatFromInt(glide.dir)), glide.now_ns, glide.pace()); } pub fn ensure(glide: *Glide, gpa: std.mem.Allocator) bool { const n = @as(usize, glide.bw()) * glide.body_h * reach; inline for (.{ &glide.above, &glide.below }) |buffer| if (buffer.len < n) { const grown = gpa.realloc(buffer.*, n) catch return false; buffer.* = grown; }; return true; } }; pub fn sameRow(a: []const pardes.Cell, b: []const pardes.Cell) bool { for (a, b) |x, y| { if (x.default != y.default) return false; if (x.default) continue; if (!std.mem.eql(u8, x.grapheme(), y.grapheme()) or !std.meta.eql(x.style, y.style)) return false; } return true; } /// A frame's length at 60 Hz, what a tick of the follow is clamped to. const frame_ns: u64 = 16 * std.time.ns_per_ms; /// A view that follows its input (anim 9, 11): the picture's offset from /// the core's position now (rows of text; negative, the picture still /// shows what is above), its speed (rows a second), when it was last /// integrated, and what has been feeding it. pub const Follow = struct { offset: f32 = 0, speed: f32 = 0, at_ns: u64 = 0, /// The last inputs (down positive), their spacing, the last's time, and /// how many came as one stream. feed: struct { amount: f32 = 0, gap_ns: u64 = 0, last_ns: u64 = 0, count: u16 = 0 } = .{}, /// How far the picture may lag, in bodies (a flick past that jumps); /// how fast it may move, in bodies a second, so moving text stays /// readable. pub const reach = 2; pub const bodies_per_s: f32 = 15; /// Inputs this close, each the way the last went, are one stream. pub const stream_ns = 150 * std.time.ns_per_ms; /// The spring's natural frequency, rad/s: an arrival lands inside /// 220 ms. pub const omega: f32 = 51; /// What a view's size makes of the rules: the speed cap, the lag cap, /// and the offset under which it is at rest (a tenth of a pixel, in /// rows). pub const Pace = struct { cap: f32, limit: f32, rest: f32 }; pub fn pace(body: f32, rest: f32) Pace { return .{ .cap = body * bodies_per_s, .limit = body * reach, .rest = rest }; } pub fn moving(follow: *const Follow) bool { return follow.offset != 0 or follow.speed != 0; } /// An input: the core moved `amount` (down positive). The picture now /// lags by as much more, its speed as it was. pub fn kick(follow: *Follow, amount: f32, now_ns: u64, p: Pace) void { follow.advance(now_ns, p); follow.offset = std.math.clamp(follow.offset - amount, -p.limit, p.limit); const f = &follow.feed; const like = f.count > 0 and (amount > 0) == (f.amount > 0) and now_ns -| f.last_ns < stream_ns; if (like) { const gap = now_ns -| f.last_ns; f.gap_ns = if (f.count == 1) gap else (f.gap_ns + gap) / 2; f.amount = (f.amount + amount) / 2; f.count +|= 1; } else f.* = .{ .amount = amount, .count = 1 }; f.last_ns = now_ns; } /// The system moved on to `now_ns`. Fed by a stream, at the stream's /// rate (an input's amount over their spacing), held a lag `lead` /// behind so a late input never finds it stopped and the stream's end /// never runs it past its mark; else on the spring, critically damped, /// from the speed it has. Never faster than `p.cap`. pub fn advance(follow: *Follow, now_ns: u64, p: Pace) void { const dt: f32 = @floatCast(@as(f64, @floatFromInt(@min(now_ns -| follow.at_ns, 2 * frame_ns))) / std.time.ns_per_s); follow.at_ns = now_ns; if (follow.offset == 0 and follow.speed == 0) return; const toward: f32 = if (follow.offset < 0) 1 else -1; const f = follow.feed; if (f.count >= 2 and f.gap_ns > 0 and now_ns -| f.last_ns < f.gap_ns * 3 / 2) { const gap: f32 = @floatCast(@as(f64, @floatFromInt(f.gap_ns)) / std.time.ns_per_s); const rate = @abs(f.amount) / gap; const lead = @max(@abs(f.amount), rate / omega); // ponytail: a gentle pull to the lead (a tenth an input), so the // per-frame step varies by a tenth; a stream's own jitter beyond // that shows. An estimate of the input clock if it ever matters. // A slow stream's lag runs out before its next input: never // faster than the spring's own pace from there (omega a unit of // lag a second), so it eases onto the mark, not into it at speed. const v = std.math.clamp(rate + 0.1 / gap * (@abs(follow.offset) - lead), 0, @min(p.cap, omega * @abs(follow.offset))); const step = @min(v * dt, @abs(follow.offset)); follow.offset += toward * step; follow.speed = if (follow.offset == 0) 0 else toward * v; return; } const x = follow.offset; // Coming to rest from a stream: never faster than the spring's own // pace from here (omega a unit of lag a second), so it eases in and // does not pass its mark. if (follow.speed * x < 0 and @abs(follow.speed) > omega * @abs(x)) follow.speed = std.math.sign(follow.speed) * omega * @abs(x); const lead_v = follow.speed + omega * x; const decay = @exp(-omega * dt); var next = (x + lead_v * dt) * decay; var speed = (follow.speed - omega * dt * lead_v) * decay; if (@abs(next - x) > p.cap * dt) { next = x + std.math.sign(next - x) * p.cap * dt; speed = std.math.sign(next - x) * p.cap; } follow.offset = next; follow.speed = speed; if (@abs(next) < p.rest and @abs(speed) < 10 * p.rest) follow.* = .{ .at_ns = now_ns }; } }; test "a follow comes to rest without a snap: past its fastest frame each step is shorter, the last under a tenth of a pixel" { // A flick's spin (a stream of notches, then nothing), one page, and // notches slow enough that each lag runs out before the next (its // stream must ease onto each mark, never pass it). const p = Follow.pace(600, 0.1); for ([_]struct { n: u16, gap_ms: u64 }{ .{ .n = 12, .gap_ms = 16 }, .{ .n = 1, .gap_ms = 16 }, .{ .n = 6, .gap_ms = 144 } }) |run| { var f: Follow = .{}; var now: u64 = std.time.ns_per_s; for (0..run.n) |_| { f.kick(if (run.n == 1) 600 else 25, now, p); var waited: u64 = 0; while (waited < run.gap_ms) : (waited += 8) { now += 8 * std.time.ns_per_ms; const was = f.offset; f.advance(now, p); // Toward its mark only, and onto it from under a pixel. try std.testing.expect(f.offset <= 0 and f.offset >= was); if (f.offset == 0) try std.testing.expect(-was <= 3 * p.rest); } } var last: f32 = std.math.inf(f32); var before = f.offset; var frames: usize = 0; var fastest: f32 = 0; while (f.moving()) : (frames += 1) { now += frame_ns; f.advance(now, p); const step = @abs(f.offset - before); try std.testing.expect(@abs(f.offset) <= @abs(before)); if (f.offset == 0) try std.testing.expect(step <= 3 * p.rest); fastest = @max(fastest, step); if (step < fastest) try std.testing.expect(step <= last); last = step; before = f.offset; try std.testing.expect(frames < 120); } try std.testing.expect(last <= 0.1); } } test "a body scrolling under held rows (sticky context) is measured, and keeps the rows that left, below them" { const gpa = std.testing.allocator; // A body 10 rows high whose first 3 hold still (a source's context // rows) while the lines under them scroll one. var cells: [2][24 * 12]pardes.Cell = undefined; var frames: [2]pardes.Surface = undefined; for (&frames, &cells, [_]u16{ 10, 11 }) |*s, *c, first| { @memset(c, .{}); s.* = .{ .cols = 24, .rows = 12, .cells = c }; s.addRegion(.{ .kind = .body, .owner = 0, .serial = 1, .rect = .{ .x = config.GUTTER, .y = 1, .w = 24 - config.GUTTER, .h = 10 }, .active = true, .line = first, .doc = 7 }); for (0..3) |k| { var buf: [8]u8 = undefined; _ = s.print(config.GUTTER, @intCast(1 + k), 20, std.fmt.bufPrint(&buf, "ctx {d}", .{k}) catch unreachable, .{}); } for (3..10) |k| { var buf: [8]u8 = undefined; _ = s.print(config.GUTTER, @intCast(1 + k), 20, std.fmt.bufPrint(&buf, "L{d}", .{first + k - 3}) catch unreachable, .{}); } } var glide: Glide = .{}; defer glide.deinit(gpa); glide.held[0] = 3; glide.frame(gpa, &frames[0], std.time.ns_per_s, null, null); glide.frame(gpa, &frames[1], std.time.ns_per_s + 16 * std.time.ns_per_ms, null, null); // A row down, and the row that left is the first under the held ones, // L10, not a held row. try std.testing.expect(glide.follow.offset < -0.9); try std.testing.expectEqual(@as(u16, 1), glide.nabove); const w = glide.bw(); try std.testing.expect(sameRow(glide.above[0..w], frames[0].cells[@as(usize, 1 + 3) * 24 + config.GUTTER ..][0..w])); }