Metal: rebuild a row when its appearance changes, not only its contents

Addresses the review on #636.

A line's `generation` moves when its contents change and at no other
time, but a row is also drawn differently when it is selected, when a
link on it is highlighted, when the modifier for link activation goes
down, and when the blink phase turns over. Those arrive through the
dirty range, which this branch stopped taking at face value — so the
blinking row kept its geometry and stopped blinking, and a selection
could be left unpainted.

Each cached row now also carries the presentation it was built under:
the selected columns on that row, the highlighted link range, whether
the modifier is down, and the blink phase. The blink phase is compared
only for rows that have something blinking on them — otherwise a single
blinking cell would rebuild the whole screen twice a second, which is
the cost this cache exists to avoid. Whether a line blinks is decided
once per rebuild and kept, since only a change of contents can change
it, and that moves the generation.

Appearance that belongs to the view rather than to a row goes into
`CacheSignature` instead: a colour revision bumped in `colorsChanged`,
the anti-aliasing setting for custom glyphs, and the link highlight
mode. A new palette rebuilds everything, which is what it should do.

Three tests cover the three paths, and each fails without its fix:
selecting a row rebuilds that row and only that row, toggling the blink
phase rebuilds exactly the blinking row, and replacing a colour rebuilds
every visible row.

The row counters also leave `#if DEBUG` and lose their `debug` prefix —
they are what the tests assert on, and a test that only compiles against
a debug build is not a test of what ships. That is what kept the suite
from running in release. It runs there now:

    release, upstream: 3.391 ms per frame, 48.0 rows rebuilt per frame
    release, this:     0.222 ms per frame,  2.0 rows rebuilt per frame

Author: IKatsuba

Sources/SwiftTerm/Apple/AppleTerminalView.swift

@@ -568,6 +568,7 @@ extension TerminalView {
         urlAttributes = [:]
         attributes = [:]
         clearCGColorCache()
+        colorRevision &+= 1
 
 #if os(macOS)
         if !isUsingMetalRenderer {

Sources/SwiftTerm/Apple/Metal/MetalTerminalRenderer.swift

@@ -128,10 +128,34 @@ struct RowDrawBuffers {
     var otherImageBuffers: [ImageDrawBuffer]
 }
 
+/// What a row looks like beyond what its line holds.
+///
+/// A line's `generation` moves when its contents change, and nothing else moves
+/// it — but a row is also drawn differently when it is selected, when a link on
+/// it is highlighted, and when the blink phase turns over. Those arrive through
+/// the dirty range, which the cache no longer takes at face value, so they are
+/// compared here instead.
+struct RowPresentation: Equatable {
+    let selection: Range<Int>?
+    let linkHighlight: Range<Int>?
+    let commandActive: Bool
+
+    /// The blink phase, and only for a row that has something blinking on it:
+    /// otherwise one blinking cell anywhere would rebuild the whole screen
+    /// twice a second, which is the cost this cache exists to avoid.
+    let blinkVisible: Bool?
+}
+
 struct RowCacheEntry {
     var lineRef: BufferLine
     var generation: UInt64
     var bidiParagraphRevision: Int
+    var presentation: RowPresentation
+
+    /// Whether the line has any blinking cell. Kept from the build rather than
+    /// asked again: the answer only changes when the contents do, and that
+    /// moves the generation above.
+    var hasBlink: Bool
     var data: RowDrawData?
     var buffers: RowDrawBuffers?
 }
@@ -198,6 +222,19 @@ struct KittyCacheStamp: Hashable {
     let nextPlacementId: UInt32
 }
 
+extension LinkHighlightMode {
+    /// A value a cache signature can hold. Not `Hashable` on the type itself:
+    /// that is public API, and this is an implementation detail.
+    var cacheStamp: Int {
+        switch self {
+        case .hover: return 0
+        case .hoverWithModifier: return 1
+        case .always: return 2
+        case .alwaysWithModifier: return 3
+        }
+    }
+}
+
 struct CacheSignature: Hashable {
     let scale: Double
     let cellWidth: Double
@@ -209,6 +246,14 @@ struct CacheSignature: Hashable {
     let fontName: String
     let fontSize: Double
     let isAltBuffer: Bool
+
+    /// Appearance that belongs to the view rather than to any line: the
+    /// palette, whether custom glyphs are anti-aliased, and which links are
+    /// underlined. None of these move a line's generation, and all of them
+    /// change how every row is drawn.
+    let colorRevision: Int
+    let antiAliasCustomBlockGlyphs: Bool
+    let linkHighlightMode: Int
     let kittyStamp: KittyCacheStamp
     let bidiHostPolicy: BidiHostPolicy
 }
@@ -257,13 +302,14 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
     private let frameSemaphore = DispatchSemaphore(value: 1)
     private var pendingRedraw = false
     private let redrawLock = NSLock()
+    /// How the last frame split between rebuilt and reused rows. Not behind
+    /// `DEBUG`: this is what the row-cache tests assert on, and a test that can
+    /// only run against a debug build is not a test of what ships.
+    internal var rowsRebuiltLastFrame = 0
+    internal var rowsReusedLastFrame = 0
 #if DEBUG
     private var debugFrameCount = 0
     private var debugLastLogTime = CFAbsoluteTimeGetCurrent()
-    /// How the last frame split between rebuilt and reused rows. Internal so a
-    /// test can measure the row cache without a window to draw into.
-    internal var debugRowsRebuilt = 0
-    internal var debugRowsCached = 0
 #endif
 #if DEBUG
     private var imageTextureFailures: Set<ObjectIdentifier> = []
@@ -436,9 +482,9 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
         let now = CFAbsoluteTimeGetCurrent()
         let elapsed = now - debugLastLogTime
         if elapsed >= 1.0 {
-            let totalRows = debugRowsRebuilt + debugRowsCached
+            let totalRows = rowsRebuiltLastFrame + rowsReusedLastFrame
             let fps = Double(debugFrameCount) / elapsed
-            print(String(format: "Metal FPS: %.1f (rows rebuilt: %d/%d)", fps, debugRowsRebuilt, totalRows))
+            print(String(format: "Metal FPS: %.1f (rows rebuilt: %d/%d)", fps, rowsRebuiltLastFrame, totalRows))
             debugFrameCount = 0
             debugLastLogTime = now
         }
@@ -656,10 +702,8 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
 
     private func buildDrawDataPass(scale: CGFloat) -> DrawData {
         guard let terminalView = terminalView else {
-#if DEBUG
-            debugRowsRebuilt = 0
-            debugRowsCached = 0
-#endif
+            rowsRebuiltLastFrame = 0
+            rowsReusedLastFrame = 0
             return DrawData(rows: [],
                             frame: nil,
                             cursorColorVertices: [],
@@ -677,10 +721,8 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
 
         let rowInfo = visibleRowRange(buffer: buffer, cellHeight: cellHeight, terminalView: terminalView)
         guard let (firstRow, lastRow, visibleDisp) = rowInfo else {
-#if DEBUG
-            debugRowsRebuilt = 0
-            debugRowsCached = 0
-#endif
+            rowsRebuiltLastFrame = 0
+            rowsReusedLastFrame = 0
             return DrawData(rows: [],
                             frame: nil,
                             cursorColorVertices: [],
@@ -712,6 +754,9 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
                                        fontName: terminalView.fontSet.normal.fontName,
                                        fontSize: Double(terminalView.fontSet.normal.pointSize),
                                        isAltBuffer: terminalView.terminal.isCurrentBufferAlternate,
+                                       colorRevision: terminalView.colorRevision,
+                                       antiAliasCustomBlockGlyphs: terminalView.antiAliasCustomBlockGlyphs,
+                                       linkHighlightMode: terminalView.linkHighlightMode.cacheStamp,
                                        kittyStamp: kittyStamp,
                                        bidiHostPolicy: terminalView.bidiHostPolicy)
         let signatureChanged = signature != cacheSignature
@@ -770,9 +815,16 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
             // Cache is valid only when the absolute row still maps to the same
             // BufferLine instance (scrolls rotate refs in the CircularList) and
             // that line has not been mutated since we cached its draw data.
+            // Blink is asked of the cached answer where there is one: the
+            // contents decide it, and unchanged contents cannot have changed
+            // it. Without an entry the row is being built anyway.
+            let hasBlink = entry.map { $0.hasBlink } ?? hasBlinkingCell(line: line, cols: buffer.cols)
+            let rowPresentation = presentation(row: row, line: line, cols: buffer.cols,
+                                               terminalView: terminalView, hasBlink: hasBlink)
             let cacheValid = entry?.lineRef === line
                 && entry?.generation == lineGeneration
                 && entry?.bidiParagraphRevision == bidiParagraphRevision
+                && entry?.presentation == rowPresentation
             // The dirty range is deliberately not consulted for rows that are
             // already cached and unchanged. A scroll marks every screen row
             // dirty — from the screen's point of view each one holds different
@@ -796,8 +848,14 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
                                            scale: scale,
                                            virtualPlacementsByImageId: virtualPlacementsByImageId)
                 let buffers = bufferingMode == .perRowPersistent ? makeRowBuffers(from: rowData) : nil
+                let blinking = hasBlinkingCell(line: line, cols: buffer.cols)
                 entry = RowCacheEntry(lineRef: line, generation: lineGeneration,
                                       bidiParagraphRevision: bidiParagraphRevision,
+                                      presentation: presentation(row: row, line: line,
+                                                                 cols: buffer.cols,
+                                                                 terminalView: terminalView,
+                                                                 hasBlink: blinking),
+                                      hasBlink: blinking,
                                       data: rowData, buffers: buffers)
                 rowCache[lineKey] = entry
                 rowBuffers = buffers
@@ -814,6 +872,8 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
                 if cached.data == nil {
                     entry = RowCacheEntry(lineRef: line, generation: lineGeneration,
                                           bidiParagraphRevision: bidiParagraphRevision,
+                                          presentation: rowPresentation,
+                                          hasBlink: cached.hasBlink,
                                           data: rowData, buffers: cached.buffers)
                     rowCache[lineKey] = entry
                 }
@@ -840,8 +900,14 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
                                            scale: scale,
                                            virtualPlacementsByImageId: virtualPlacementsByImageId)
                 let buffers = bufferingMode == .perRowPersistent ? makeRowBuffers(from: rowData) : nil
+                let blinking = hasBlinkingCell(line: line, cols: buffer.cols)
                 entry = RowCacheEntry(lineRef: line, generation: lineGeneration,
                                       bidiParagraphRevision: bidiParagraphRevision,
+                                      presentation: presentation(row: row, line: line,
+                                                                 cols: buffer.cols,
+                                                                 terminalView: terminalView,
+                                                                 hasBlink: blinking),
+                                      hasBlink: blinking,
                                       data: rowData, buffers: buffers)
                 rowCache[lineKey] = entry
                 rowBuffers = buffers
@@ -877,10 +943,8 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
                 }
             }
         }
-#if DEBUG
-        debugRowsRebuilt = rebuiltRows
-        debugRowsCached = cachedRows
-#endif
+        rowsRebuiltLastFrame = rebuiltRows
+        rowsReusedLastFrame = cachedRows
 
         let cursorData = buildCursorDrawData(scale: scale,
                                              cellWidth: cellWidth,
@@ -941,6 +1005,30 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
         #endif
     }
 
+    /// What the row's appearance depends on right now, beyond its contents.
+    private func presentation(row: Int, line: BufferLine, cols: Int,
+                              terminalView: TerminalView, hasBlink: Bool) -> RowPresentation {
+        var linkHighlight: Range<Int>?
+        if let highlights = terminalView.linkHighlightRange {
+            linkHighlight = highlights.first(where: { $0.row == row })?.range
+        }
+
+        return RowPresentation(
+            selection: terminalView.selectedColumnsRange(row: row, cols: cols),
+            linkHighlight: linkHighlight,
+            commandActive: terminalView.commandActive,
+            blinkVisible: hasBlink ? terminalView.textBlinkVisible : nil)
+    }
+
+    /// Whether anything on the line blinks. Walked once per rebuild, never per
+    /// frame — see [RowCacheEntry.hasBlink].
+    private func hasBlinkingCell(line: BufferLine, cols: Int) -> Bool {
+        for column in 0..<min(cols, line.count) where line[column].attribute.style.contains(.blink) {
+            return true
+        }
+        return false
+    }
+
     /// Builds one row's geometry in the row's own coordinates — its baseline
     /// sits at zero rather than at a screen position.
     ///

Sources/SwiftTerm/Mac/MacTerminalView.swift

@@ -208,6 +208,11 @@ open class TerminalView: NSView, NSTextInputClient, NSUserInterfaceValidations,
     var debug: TerminalDebugView?
     var pendingDisplay: Bool = false
     var textBlinkVisible = true
+
+    /// Bumped whenever the colours are replaced, so a cache keyed on
+    /// appearance can tell that the same line now draws differently. See
+    /// `colorsChanged` and `CacheSignature`.
+    var colorRevision = 0
     var textBlinkTimer: Timer?
     var textBlinkObservers: [(NotificationCenter, NSObjectProtocol)] = []
     var textBlinkApplicationActive = true

Sources/SwiftTerm/iOS/iOSTerminalView.swift

@@ -201,6 +201,11 @@ open class TerminalView: UIScrollView, UITextInputTraits, UIKeyInput, UIScrollVi
     var debug: UIView?
     var pendingDisplay: Bool = false
     var textBlinkVisible = true
+
+    /// Bumped whenever the colours are replaced, so a cache keyed on
+    /// appearance can tell that the same line now draws differently. See
+    /// `colorsChanged` and `CacheSignature`.
+    var colorRevision = 0
     var textBlinkTimer: Timer?
     var textBlinkObservers: [(NotificationCenter, NSObjectProtocol)] = []
     var textBlinkApplicationActive = true

Tests/SwiftTermTests/MetalRowCacheTests.swift

@@ -51,10 +51,10 @@ final class MetalRowCacheTests: XCTestCase {
         _ = renderer.buildDrawData(scale: 2)
 
         XCTAssertLessThanOrEqual(
-            renderer.debugRowsRebuilt, 3,
-            "a one-line scroll rebuilt \(renderer.debugRowsRebuilt) rows of "
-            + "\(renderer.debugRowsRebuilt + renderer.debugRowsCached)")
-        XCTAssertGreaterThan(renderer.debugRowsCached, 20)
+            renderer.rowsRebuiltLastFrame, 3,
+            "a one-line scroll rebuilt \(renderer.rowsRebuiltLastFrame) rows of "
+            + "\(renderer.rowsRebuiltLastFrame + renderer.rowsReusedLastFrame)")
+        XCTAssertGreaterThan(renderer.rowsReusedLastFrame, 20)
     }
 
     /// A frame in which nothing happened must rebuild nothing at all.
@@ -64,7 +64,7 @@ final class MetalRowCacheTests: XCTestCase {
         _ = renderer.buildDrawData(scale: 2)
 
         _ = renderer.buildDrawData(scale: 2)
-        XCTAssertEqual(renderer.debugRowsRebuilt, 0)
+        XCTAssertEqual(renderer.rowsRebuiltLastFrame, 0)
     }
 
     /// The row that changed is the row that is rebuilt — the cache must not
@@ -78,8 +78,64 @@ final class MetalRowCacheTests: XCTestCase {
         view.feed(text: "\roverwritten")
         _ = renderer.buildDrawData(scale: 2)
 
-        XCTAssertGreaterThanOrEqual(renderer.debugRowsRebuilt, 1)
-        XCTAssertLessThanOrEqual(renderer.debugRowsRebuilt, 3)
+        XCTAssertGreaterThanOrEqual(renderer.rowsRebuiltLastFrame, 1)
+        XCTAssertLessThanOrEqual(renderer.rowsRebuiltLastFrame, 3)
+    }
+
+    /// A row is drawn differently when it is selected, and selecting it does
+    /// not touch the line's contents — so the generation the cache checks does
+    /// not move. Before the presentation revision, the selected row kept its
+    /// unselected geometry.
+    func testSelectingARowRebuildsIt() throws {
+        let (view, renderer) = try makeRenderer(rows: 24, cols: 80)
+        feed(view, lines: 40)
+        _ = renderer.buildDrawData(scale: 2)
+        _ = renderer.buildDrawData(scale: 2)
+        XCTAssertEqual(renderer.rowsRebuiltLastFrame, 0, "the second frame should have rebuilt nothing")
+
+        view.selection.setSelection(start: Position(col: 0, row: 20),
+                                    end: Position(col: 10, row: 20))
+        _ = renderer.buildDrawData(scale: 2)
+
+        XCTAssertGreaterThanOrEqual(renderer.rowsRebuiltLastFrame, 1,
+                                    "the selected row has to be built again")
+        XCTAssertLessThanOrEqual(renderer.rowsRebuiltLastFrame, 2,
+                                 "and only that row: \(renderer.rowsRebuiltLastFrame) were")
+    }
+
+    /// The blink phase turns over twice a second and changes nothing about the
+    /// line's contents. A row with something blinking on it must follow; a row
+    /// without must not be dragged along with it.
+    func testBlinkRebuildsOnlyTheBlinkingRow() throws {
+        let (view, renderer) = try makeRenderer(rows: 24, cols: 80)
+        feed(view, lines: 20)
+        view.feed(text: "\u{1b}[5mblinking\u{1b}[0m\r\n")
+        feed(view, lines: 2)
+        _ = renderer.buildDrawData(scale: 2)
+        _ = renderer.buildDrawData(scale: 2)
+        XCTAssertEqual(renderer.rowsRebuiltLastFrame, 0)
+
+        view.textBlinkVisible.toggle()
+        _ = renderer.buildDrawData(scale: 2)
+
+        XCTAssertEqual(renderer.rowsRebuiltLastFrame, 1,
+                       "exactly the blinking row, not the whole screen")
+    }
+
+    /// Replacing the palette changes how every row draws, and moves no line's
+    /// generation either.
+    func testChangingTheColoursRebuildsEverything() throws {
+        let (view, renderer) = try makeRenderer(rows: 24, cols: 80)
+        feed(view, lines: 40)
+        _ = renderer.buildDrawData(scale: 2)
+        _ = renderer.buildDrawData(scale: 2)
+        XCTAssertEqual(renderer.rowsRebuiltLastFrame, 0)
+
+        view.nativeForegroundColor = TTColor.make(red: 0.9, green: 0.2, blue: 0.2, alpha: 1)
+        _ = renderer.buildDrawData(scale: 2)
+
+        XCTAssertGreaterThan(renderer.rowsRebuiltLastFrame, 20,
+                             "a new palette means every visible row")
     }
 
     /// What the change is for, in wall-clock terms.
@@ -96,7 +152,7 @@ final class MetalRowCacheTests: XCTestCase {
             view.feed(text: "\u{1b}[1;32mscrolled line \(i)\u{1b}[0m — "
                       + "\u{1b}[38;5;244mthe quick brown fox jumps over the lazy dog\u{1b}[0m\r\n")
             _ = renderer.buildDrawData(scale: 2)
-            rebuilt += renderer.debugRowsRebuilt
+            rebuilt += renderer.rowsRebuiltLastFrame
         }
         let each = Date().timeIntervalSince(started) / 200 * 1000
         print(String(format: "buildDrawData while scrolling: %.3f ms per frame, %.1f rows rebuilt per frame",