@glassly/bluetooth-sdk 0.1.0-dev.99 → 0.2.8-dev.445

package/ios/Source/sgcs/G2CfwTextureCache.swift

@@ -1,59 +1,83 @@
 import Foundation
 
-/// Phone-side model of the Glassly CFW's lease-scoped 64 KiB texture cache,
-/// plus the mode-12/13/14 wire encoders.
+/// Phone-side mirror of the Glassly CFW's asset store (GLASSLYCFW/38): the
+/// images, cached fonts and strings that scene objects reference by 32-bit id.
 ///
-/// The firmware allocates and zeroes the cache on the first mode-12 write and
-/// frees it when the fbguard lease ends, so this model is only valid for one
-/// lease/generation: the owner bumps a generation counter whenever the lease
-/// cycles (or a send fails and residency becomes unknown) and the model
-/// re-learns from scratch — uploads are cheap (a full mono font is a few KiB).
+/// The glasses hold assets in a 256 KiB store behind their own allocator and
+/// evict the least recently used unreferenced ones when room is needed, so the
+/// wire never carries a storage offset: every asset has an id (a hash of what
+/// it is) and a version (a hash of its bytes), and a PUT_ASSET entry uploads
+/// it. This mirror remembers which ids it has queued for upload and predicts
+/// the store's occupancy; when the prediction overflows it forgets what the
+/// glasses are most likely to have evicted. A wrong prediction is harmless:
+/// the firmware answers a SHOW that references an absent asset with MISSING,
+/// and `forget(assetIds:)` makes the next frame re-upload exactly those.
+///
+/// The model is valid for one cache generation: the owner bumps a generation
+/// counter whenever the on-glass cache is lost (lease end, reset, failed send)
+/// and the model re-learns from scratch.
 ///
 /// Cached image format: `[width:u8][height:u8][4bpp RLE]` where the RLE covers
 /// exactly width*height pixels with NO row-pad nibbles (unlike modes 3/6).
-/// Mode-14 fonts are a 96-entry little-endian u16 image-offset table for
-/// characters 32..127; a zero entry points at cache offset 0, so the first
-/// two bytes of the cache are left zero (width 0 ⇒ invalid image) and real
-/// allocations start past them.
+/// A font asset is a 96-entry little-endian u32 table of glyph image offsets
+/// (characters 32..127, relative to the asset; 0 = absent) followed by the
+/// glyph images, uploaded whole.
 final class G2CfwTextureCache {
-    static let cacheSize = 64 * 1024
+    static let storeSize = 256 * 1024
+    static let granule = 16
+    static let maxAssets = 256
     static let fontTableChars = 96 // ASCII 32..127
-    /// Keep mode-12 payloads comfortably inside one BLE image message.
-    static let maxUploadPayloadBytes = 3600
+    static let fontTableEntryBytes = 4
+    /// A PUT message is one transport message; keep them a few round trips
+    /// long rather than one 64 KiB stream that acks late.
+    static let maxUploadPayloadBytes = 8192
     /// 0x0F: identity ramp (top color 15), opaque — a full-cell glyph or a
     /// full-box image drawn opaque self-erases whatever was under it.
     static let opaqueDrawOptions: UInt8 = 0x0F
+    static let kindImage: UInt8 = 0
+    static let kindFont: UInt8 = 1
+    static let kindString: UInt8 = 2
 
     final class FontEntry {
-        let tableOffset: Int
+        let id: UInt32
         let cellWidth: Int
         let lineHeight: Int
-        /// Cache offset per printable char (index = char - 32), nil = not resident.
-        var glyphOffsets = [Int?](repeating: nil, count: G2CfwTextureCache.fontTableChars)
+        /// Wire codes (32..127) whose glyphs the uploaded font carries.
+        let glyphs: Set<UInt8>
 
-        init(tableOffset: Int, cellWidth: Int, lineHeight: Int) {
-            self.tableOffset = tableOffset
+        init(id: UInt32, cellWidth: Int, lineHeight: Int, glyphs: Set<UInt8>) {
+            self.id = id
             self.cellWidth = cellWidth
             self.lineHeight = lineHeight
+            self.glyphs = glyphs
         }
     }
 
+    private struct Asset {
+        let id: UInt32
+        let version: UInt32
+        let bytes: Int // granule-rounded store footprint
+        var lastUse: Int
+    }
+
     private(set) var generation = -1
-    private var fonts: [Int32: FontEntry] = [:]
-    private var images: [String: Int] = [:]
+    /// Bytes the glasses could allocate for the store (the RESET reply says; 256 KiB when unknown).
+    var storeCapacity = G2CfwTextureCache.storeSize
+    private var fonts: [String: FontEntry] = [:]
+    /// Asset key → the resident (or queued) asset.
+    private var assets: [String: Asset] = [:]
+    private var byId: [UInt32: String] = [:]
     /// Content hashes seen in earlier frames. Streaming content (a minimap
     /// re-rendered every frame) never repeats a hash, so it never enters the
     /// cache; static icons promote on their second sighting.
     private var seenImageHashes: [String] = []
-    /// Bump allocator. Bytes 0..1 stay zero as the invalid-image guard.
-    private var nextOffset = 2
-    /// Mode-12 entries not yet flushed into payloads.
-    private var pendingUploads: [(offset: Int, data: Data)] = []
-    /// The bump allocator filled up. The reference client recycles a full
-    /// cache (`TextureCacheState.reset` "or we ran out of space"); without
-    /// recovery every later ensure fails and the texture path silently dies
-    /// for the rest of the lease. The renderer checks this before each frame
-    /// and starts a fresh generation.
+    /// PUT_ASSET entries not yet flushed into payloads.
+    private var pendingEntries: [Data] = []
+    private var useClock = 0
+    /// Predicted store occupancy of everything this mirror believes resident.
+    private(set) var predictedBytes = 0
+    /// The prediction overflowed the store and the mirror dropped its oldest
+    /// assets; advisory for the renderer.
     private(set) var exhausted = false
 
     /// Forget everything and adopt `generation` (the on-glass cache was freed
@@ -61,105 +85,202 @@ final class G2CfwTextureCache {
     func reset(generation: Int) {
         self.generation = generation
         fonts.removeAll()
-        images.removeAll()
+        assets.removeAll()
+        byId.removeAll()
         seenImageHashes.removeAll()
-        nextOffset = 2
-        pendingUploads.removeAll()
+        pendingEntries.removeAll()
+        predictedBytes = 0
+        useClock = 0
         exhausted = false
     }
 
-    private func allocate(_ length: Int) -> Int? {
-        guard length > 0, nextOffset + length <= Self.cacheSize else {
-            if length > 0 { exhausted = true }
+    /// The glasses reported these asset ids absent: upload them again on next use.
+    func forget(assetIds: [UInt32]) {
+        for id in assetIds {
+            guard let key = byId.removeValue(forKey: id), let asset = assets.removeValue(forKey: key) else { continue }
+            predictedBytes -= asset.bytes
+            fonts = fonts.filter { $0.value.id != id }
+        }
+    }
+
+    /// True when `id` names an asset this mirror believes resident.
+    func holds(assetId id: UInt32) -> Bool { byId[id] != nil }
+
+    /// Nonzero 31-bit FNV-1a of a key: asset ids and content versions.
+    static func hash31(_ s: String) -> UInt32 {
+        hash31(Data(s.utf8))
+    }
+
+    static func hash31(_ bytes: Data) -> UInt32 {
+        var h: UInt32 = 0x811C_9DC5
+        for byte in bytes {
+            h ^= UInt32(byte)
+            h = h &* 0x0100_0193
+        }
+        h &= 0x7FFF_FFFF
+        return h == 0 ? 1 : h
+    }
+
+    private static func footprint(_ length: Int) -> Int {
+        (length + granule - 1) / granule * granule
+    }
+
+    /// Register `data` under `key` as an asset of `kind`, queueing its upload.
+    /// Nil when it can never fit the store or its id is taken by another key.
+    private func ensureAsset(key: String, kind: UInt8, data: Data) -> UInt32? {
+        useClock += 1
+        if var asset = assets[key] {
+            asset.lastUse = useClock
+            assets[key] = asset
+            return asset.id
+        }
+        guard !data.isEmpty, data.count <= storeCapacity else { return nil }
+        let id = Self.hash31(key)
+        if let other = byId[id], other != key {
             return nil
         }
-        defer { nextOffset += length }
-        return nextOffset
+        let footprint = Self.footprint(data.count)
+        makeRoom(for: footprint)
+        let asset = Asset(id: id, version: Self.hash31(data), bytes: footprint, lastUse: useClock)
+        assets[key] = asset
+        byId[id] = key
+        predictedBytes += footprint
+        pendingEntries.append(contentsOf: Self.putAssetEntries(id: id, version: asset.version, kind: kind, data: data))
+        return id
     }
 
-    /// The font table for `fontSize`, allocating (and zero-filling on-glass by
-    /// virtue of the fresh cache) the 192-byte offset table on first use.
-    func font(fontSize: Int32, cellWidth: Int, lineHeight: Int) -> FontEntry? {
-        if let existing = fonts[fontSize] { return existing }
-        guard let tableOffset = allocate(Self.fontTableChars * 2) else { return nil }
-        let entry = FontEntry(tableOffset: tableOffset, cellWidth: cellWidth, lineHeight: lineHeight)
-        fonts[fontSize] = entry
-        return entry
+    /// Drop the mirror's least recently used assets until `footprint` fits the
+    /// predicted store: the glasses evict the same way, so believing an asset
+    /// gone is safer than believing it resident.
+    private func makeRoom(for footprint: Int) {
+        while predictedBytes + footprint > storeCapacity || assets.count >= Self.maxAssets {
+            guard let victim = assets.min(by: { $0.value.lastUse < $1.value.lastUse }) else { break }
+            exhausted = true
+            assets.removeValue(forKey: victim.key)
+            byId.removeValue(forKey: victim.value.id)
+            fonts = fonts.filter { $0.value.id != victim.value.id }
+            predictedBytes -= victim.value.bytes
+        }
     }
 
-    /// Make `char` (ASCII 32..126) resident for `font`, uploading its RLE
-    /// raster and patching the font table. `rasterize` supplies the full-cell
-    /// 8-bit grayscale raster (cellWidth × lineHeight) on first upload.
-    /// Returns false when the cache is full or the raster is unavailable.
-    func ensureGlyph(font: FontEntry, char: UInt8, rasterize: () -> Data?) -> Bool {
-        guard char >= 32, char <= 126 else { return false }
-        let index = Int(char) - 32
-        if font.glyphOffsets[index] != nil { return true }
-        guard let gray = rasterize(), gray.count == font.cellWidth * font.lineHeight else { return false }
-        var image = Data([UInt8(font.cellWidth), UInt8(font.lineHeight)])
-        image.append(Self.rleEncodePixels(gray))
-        guard let offset = allocate(image.count) else { return false }
-        font.glyphOffsets[index] = offset
-        pendingUploads.append((offset: offset, data: image))
-        pendingUploads.append((
-            offset: font.tableOffset + index * 2,
-            data: Data([UInt8(offset & 0xFF), UInt8((offset >> 8) & 0xFF)])
-        ))
-        return true
+    /// The font asset for `fontSize`, rasterizing every glyph the variant needs
+    /// and uploading the whole font on first use. `rasterize` supplies the
+    /// full-cell 8-bit grayscale raster (cellWidth × lineHeight) for a wire
+    /// code; a code it cannot raster is left absent from the font.
+    func font(
+        fontSize: Int32, cellWidth: Int, lineHeight: Int, variant: String = "ascii",
+        codes: [UInt8] = Array(32 ... 126), rasterize: (UInt8) -> Data?
+    ) -> FontEntry? {
+        let key = "font:\(fontSize):\(cellWidth)x\(lineHeight):\(variant)"
+        if let existing = fonts[key], assets[key] != nil {
+            useClock += 1
+            assets[key]?.lastUse = useClock
+            return existing
+        }
+        var table = Data(count: Self.fontTableChars * Self.fontTableEntryBytes)
+        var body = Data()
+        var glyphs = Set<UInt8>()
+        for code in codes where code >= 32 && code <= 127 {
+            guard let gray = rasterize(code), gray.count == cellWidth * lineHeight else { continue }
+            let offset = table.count + body.count
+            let index = (Int(code) - 32) * Self.fontTableEntryBytes
+            table[index] = UInt8(offset & 0xFF)
+            table[index + 1] = UInt8((offset >> 8) & 0xFF)
+            table[index + 2] = UInt8((offset >> 16) & 0xFF)
+            table[index + 3] = UInt8((offset >> 24) & 0xFF)
+            body.append(UInt8(cellWidth)); body.append(UInt8(lineHeight))
+            body.append(Self.rleEncodePixels(gray))
+            glyphs.insert(code)
+        }
+        guard !glyphs.isEmpty, let id = ensureAsset(key: key, kind: Self.kindFont, data: table + body) else { return nil }
+        let entry = FontEntry(id: id, cellWidth: cellWidth, lineHeight: lineHeight, glyphs: glyphs)
+        fonts[key] = entry
+        return entry
     }
 
     /// Record a sighting of an image content hash; true when it was already
     /// seen in an earlier frame (worth caching).
     func noteImageSighting(_ hash: String) -> Bool {
-        if images[hash] != nil { return true }
+        if assets[hash] != nil { return true }
         if seenImageHashes.contains(hash) { return true }
         seenImageHashes.append(hash)
         if seenImageHashes.count > 32 { seenImageHashes.removeFirst() }
         return false
     }
 
-    /// The cache offset of an image, uploading it on first residency.
+    /// The asset id of an image, uploading it on first residency.
     /// `gray` is the width×height 8-bit grayscale raster.
-    func ensureImage(hash: String, gray: Data, width: Int, height: Int) -> Int? {
-        if let offset = images[hash] { return offset }
-        guard width > 0, width <= 255, height > 0, height <= 255,
-              gray.count == width * height
-        else { return nil }
+    func ensureImage(hash: String, gray: Data, width: Int, height: Int) -> UInt32? {
+        if let asset = assets[hash] { useClock += 1; assets[hash]?.lastUse = useClock; return asset.id }
+        guard width > 0, width <= 255, height > 0, height <= 255, gray.count == width * height else { return nil }
         var image = Data([UInt8(width), UInt8(height)])
         image.append(Self.rleEncodePixels(gray))
-        guard let offset = allocate(image.count) else { return nil }
-        images[hash] = offset
-        pendingUploads.append((offset: offset, data: image))
-        return offset
+        return ensureAsset(key: hash, kind: Self.kindImage, data: image)
     }
 
-    /// Drain the pending mode-12 entries into `[12][offset16][len16][data]...`
-    /// payloads, each at most `maxUploadPayloadBytes`. An entry larger than
-    /// the budget gets a payload of its own (the BLE fragmenter splits it).
+    /// The asset id of a string (1..128 bytes of UTF-8, no NUL), uploading it on first use.
+    func ensureBytes(key: String, bytes: [UInt8]) -> UInt32? {
+        guard !bytes.isEmpty, bytes.count <= 128, !bytes.contains(0) else { return nil }
+        return ensureAsset(key: key, kind: Self.kindString, data: Data(bytes))
+    }
+
+    /// Drain the pending PUT_ASSET entries into `[37][epoch 0][request 0][entries]`
+    /// payloads, each at most `maxUploadPayloadBytes` (the link stamps the epoch
+    /// and request). An asset larger than the budget is split into chunks.
     func takeUploadPayloads() -> [Data] {
-        guard !pendingUploads.isEmpty else { return [] }
+        guard !pendingEntries.isEmpty else { return [] }
         var payloads: [Data] = []
-        var current = Data([12])
-        for entry in pendingUploads {
-            var record = Data()
-            record.append(UInt8(entry.offset & 0xFF))
-            record.append(UInt8((entry.offset >> 8) & 0xFF))
-            record.append(UInt8(entry.data.count & 0xFF))
-            record.append(UInt8((entry.data.count >> 8) & 0xFF))
-            record.append(entry.data)
-            if current.count > 1, current.count + record.count > Self.maxUploadPayloadBytes {
+        var current = Data([37, 0, 0, 0, 0])
+        for entry in pendingEntries {
+            if current.count > 5, current.count + entry.count > Self.maxUploadPayloadBytes {
                 payloads.append(current)
-                current = Data([12])
+                current = Data([37, 0, 0, 0, 0])
             }
-            current.append(record)
+            current.append(entry)
         }
-        if current.count > 1 { payloads.append(current) }
-        pendingUploads.removeAll()
+        if current.count > 5 { payloads.append(current) }
+        pendingEntries.removeAll()
         return payloads
     }
 
+    /// Asset ids a `takeUploadPayloads` payload puts, in order.
+    static func assetIds(inUploadPayload payload: Data) -> [UInt32] {
+        let b = [UInt8](payload)
+        guard b.count > 5, b[0] == 37 else { return [] }
+        var ids: [UInt32] = []
+        var i = 5
+        while i + 20 <= b.count, b[i] == 0 {
+            let id = UInt32(b[i + 1]) | UInt32(b[i + 2]) << 8 | UInt32(b[i + 3]) << 16 | UInt32(b[i + 4]) << 24
+            if ids.last != id { ids.append(id) }
+            i += 20 + (Int(b[i + 18]) | Int(b[i + 19]) << 8)
+        }
+        return ids
+    }
+
     // MARK: - Wire encoders
 
+    /// PUT_ASSET entries for one asset: `[0][id:u32][version:u32][kind][total:u32][offset:u32][len:u16][data]`
+    /// per chunk, chunks in order.
+    static func putAssetEntries(id: UInt32, version: UInt32, kind: UInt8, data: Data) -> [Data] {
+        var out: [Data] = []
+        var offset = 0
+        let chunk = maxUploadPayloadBytes - 32
+        repeat {
+            let len = min(chunk, data.count - offset)
+            var entry = Data([0])
+            appendU32(Int(id), to: &entry)
+            appendU32(Int(version), to: &entry)
+            entry.append(kind)
+            appendU32(data.count, to: &entry)
+            appendU32(offset, to: &entry)
+            entry.append(UInt8(len & 0xFF)); entry.append(UInt8(len >> 8))
+            entry.append(data.subdata(in: (data.startIndex + offset) ..< (data.startIndex + offset + len)))
+            out.append(entry)
+            offset += len
+        } while offset < data.count
+        return out
+    }
+
     /// RLE over a flat 8-bit grayscale pixel sequence (quantized to 4bpp),
     /// covering exactly the pixel count — no row padding, per the cached-image
     /// contract. Token forms match modes 3/6.
@@ -195,36 +316,42 @@ final class G2CfwTextureCache {
         return output
     }
 
-    /// Mode-13 cached-image draw: `[13][offset:u16][x:u16][y:u16][options]`.
-    static func imageDrawPayload(offset: Int, x: Int, y: Int, options: UInt8) -> Data? {
-        guard offset >= 0, offset <= 0xFFFF, x >= 0, x <= 0xFFFF, y >= 0, y <= 0xFFFF
-        else { return nil }
-        var payload = Data([13])
-        for value in [offset, x, y] {
-            payload.append(UInt8(value & 0xFF))
-            payload.append(UInt8((value >> 8) & 0xFF))
-        }
+    static func appendU32(_ value: Int, to payload: inout Data) {
+        payload.append(UInt8(value & 0xFF))
+        payload.append(UInt8((value >> 8) & 0xFF))
+        payload.append(UInt8((value >> 16) & 0xFF))
+        payload.append(UInt8((value >> 24) & 0xFF))
+    }
+
+    static func appendI16(_ value: Int, to payload: inout Data) {
+        let bits = UInt16(bitPattern: Int16(clamping: value))
+        payload.append(UInt8(bits & 0xFF))
+        payload.append(UInt8(bits >> 8))
+    }
+
+    /// Mode-19 image draw: `[19][asset id:u32][x:i16][y:i16][options]`.
+    static func imageDrawPayload(assetId: UInt32, x: Int, y: Int, options: UInt8) -> Data? {
+        guard assetId != 0, x >= -32768, x <= 32767, y >= -32768, y <= 32767 else { return nil }
+        var payload = Data([19])
+        appendU32(Int(assetId), to: &payload)
+        appendI16(x, to: &payload)
+        appendI16(y, to: &payload)
         payload.append(options)
         return payload
     }
 
-    /// Mode-14 cached-glyph run:
-    /// `[14][font-offset:u16][x:u16][y:u16][options][strlen:u8][chars]`.
-    /// Every char must be 32..126 and resident (the firmware validates each
-    /// referenced glyph and rejects the whole draw otherwise).
-    static func stringRunPayload(
-        fontTableOffset: Int, x: Int, y: Int, options: UInt8, chars: [UInt8]
-    ) -> Data? {
-        guard !chars.isEmpty, chars.count <= 255,
-              fontTableOffset >= 0, fontTableOffset <= cacheSize - fontTableChars * 2,
-              x >= 0, x <= 0xFFFF, y >= 0, y <= 0xFFFF,
+    /// Mode-20 glyph run: `[20][font asset id:u32][x:i16][y:i16][options][strlen:u8][chars]`.
+    /// Every char must be 32..126 and present in the font (the firmware
+    /// validates each referenced glyph and rejects the whole draw otherwise).
+    static func stringRunPayload(fontId: UInt32, x: Int, y: Int, options: UInt8, chars: [UInt8]) -> Data? {
+        guard !chars.isEmpty, chars.count <= 255, fontId != 0,
+              x >= -32768, x <= 32767, y >= -32768, y <= 32767,
               chars.allSatisfy({ $0 >= 32 && $0 <= 126 })
         else { return nil }
-        var payload = Data([14])
-        for value in [fontTableOffset, x, y] {
-            payload.append(UInt8(value & 0xFF))
-            payload.append(UInt8((value >> 8) & 0xFF))
-        }
+        var payload = Data([20])
+        appendU32(Int(fontId), to: &payload)
+        appendI16(x, to: &payload)
+        appendI16(y, to: &payload)
         payload.append(options)
         payload.append(UInt8(chars.count))
         payload.append(contentsOf: chars)