@glassly/bluetooth-sdk 0.1.0-dev.98 → 0.2.8-dev.444

package/android/src/main/java/com/glassly/bluetoothsdk/sgcs/G2CfwTextureCache.kt

@@ -3,35 +3,64 @@ package com.glassly.bluetoothsdk.sgcs
 import java.io.ByteArrayOutputStream
 
 /**
- * Phone-side model of the Glassly CFW's lease-scoped 64 KiB texture cache
- * (g2flash texture_cache.c), plus the mode-12/13/14 wire encoders.
+ * Phone-side mirror of the Glassly CFW's asset store (GLASSLYCFW/38, g2flash
+ * scene.c): 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] 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.
  */
 internal class G2CfwTextureCache {
     companion object {
-        const val CACHE_SIZE = 64 * 1024
+        const val STORE_SIZE = 256 * 1024
+        const val GRANULE = 16
+        const val MAX_ASSETS = 256
         const val FONT_TABLE_CHARS = 96 // ASCII 32..127
+        const val FONT_TABLE_ENTRY_BYTES = 4
 
-        /** Keep mode-12 payloads comfortably inside one BLE image message. */
-        const val MAX_UPLOAD_PAYLOAD_BYTES = 3600
+        /** A PUT message is one transport message; keep them a few round trips long. */
+        const val MAX_UPLOAD_PAYLOAD_BYTES = 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.
          */
         const val OPAQUE_DRAW_OPTIONS = 0x0F
+        const val KIND_IMAGE = 0
+        const val KIND_FONT = 1
+        const val KIND_STRING = 2
+
+        /** Nonzero 31-bit FNV-1a of a key: asset ids and content versions. */
+        fun hash31(s: String): Int = hash31(s.toByteArray(Charsets.UTF_8))
+
+        fun hash31(bytes: ByteArray): Int {
+            var h = 0x811C9DC5.toInt()
+            for (b in bytes) {
+                h = h xor (b.toInt() and 0xFF)
+                h *= 0x01000193
+            }
+            h = h and 0x7FFFFFFF
+            return if (h == 0) 1 else h
+        }
+
+        private fun footprint(length: Int): Int = (length + GRANULE - 1) / GRANULE * GRANULE
 
         /**
          * RLE over a flat 8-bit grayscale pixel sequence (quantized to 4bpp),
@@ -39,232 +68,276 @@ internal class G2CfwTextureCache {
          * contract. Token forms match modes 3/6.
          */
         fun rleEncodePixels(gray: ByteArray): ByteArray {
-            val output = ByteArrayOutputStream()
+            val out = ByteArrayOutputStream()
             var index = 0
             while (index < gray.size) {
-                // Same rounded quantization as pack4Bpp: a cached draw must reproduce
-                // the composited frame's exact levels or the phone-side shadow
-                // diverges from the panel.
-                val color = G2CfwRenderer.grayNibble(gray[index].toInt())
+                val color = G2CfwRenderer.grayNibble(gray[index].toInt() and 0xFF)
                 var end = index + 1
-                while (end < gray.size && G2CfwRenderer.grayNibble(gray[end].toInt()) == color) end += 1
+                while (end < gray.size && G2CfwRenderer.grayNibble(gray[end].toInt() and 0xFF) == color) end++
                 var remaining = end - index
                 while (remaining > 0) {
                     val chunk = minOf(remaining, 0xFFFF)
                     when {
-                        chunk <= 15 -> output.write((chunk shl 4) or color)
-                        chunk <= 255 -> {
-                            output.write(color)
-                            output.write(chunk)
-                        }
-                        else -> {
-                            output.write(color)
-                            output.write(0)
-                            output.write(chunk and 0xFF)
-                            output.write((chunk ushr 8) and 0xFF)
-                        }
+                        chunk <= 15 -> out.write((chunk shl 4) or color)
+                        chunk <= 255 -> { out.write(color); out.write(chunk) }
+                        else -> { out.write(color); out.write(0); out.write(chunk and 0xFF); out.write((chunk ushr 8) and 0xFF) }
                     }
                     remaining -= chunk
                 }
                 index = end
             }
-            return output.toByteArray()
+            return out.toByteArray()
         }
 
-        /** Mode-13 cached-image draw: `[13][offset:u16][x:u16][y:u16][options]`. */
-        fun imageDrawPayload(offset: Int, x: Int, y: Int, options: Int): ByteArray? {
-            if (offset !in 0..0xFFFF || x !in 0..0xFFFF || y !in 0..0xFFFF) return null
-            val payload = ByteArrayOutputStream()
-            payload.write(13)
-            for (value in intArrayOf(offset, x, y)) {
-                payload.write(value and 0xFF)
-                payload.write((value ushr 8) and 0xFF)
+        fun ByteArrayOutputStream.writeU32(value: Int) {
+            write(value and 0xFF)
+            write((value ushr 8) and 0xFF)
+            write((value ushr 16) and 0xFF)
+            write((value ushr 24) and 0xFF)
+        }
+
+        fun ByteArrayOutputStream.writeI16(value: Int) {
+            val v = value.coerceIn(-32768, 32767)
+            write(v and 0xFF)
+            write((v ushr 8) and 0xFF)
+        }
+
+        /** PUT_ASSET entries for one asset: `[0][id][version][kind][total][offset][len][data]` per chunk. */
+        fun putAssetEntries(id: Int, version: Int, kind: Int, data: ByteArray): List<ByteArray> {
+            val out = mutableListOf<ByteArray>()
+            var offset = 0
+            val chunk = MAX_UPLOAD_PAYLOAD_BYTES - 32
+            do {
+                val len = minOf(chunk, data.size - offset)
+                val entry = ByteArrayOutputStream()
+                entry.write(0)
+                entry.writeU32(id)
+                entry.writeU32(version)
+                entry.write(kind)
+                entry.writeU32(data.size)
+                entry.writeU32(offset)
+                entry.write(len and 0xFF); entry.write((len ushr 8) and 0xFF)
+                entry.write(data, offset, len)
+                out.add(entry.toByteArray())
+                offset += len
+            } while (offset < data.size)
+            return out
+        }
+
+        /** Asset ids a [takeUploadPayloads] payload puts, in order. */
+        fun assetIdsInUploadPayload(payload: ByteArray): List<Int> {
+            if (payload.size <= 5 || payload[0].toInt() != 37) return emptyList()
+            val ids = mutableListOf<Int>()
+            var i = 5
+            while (i + 20 <= payload.size && payload[i].toInt() == 0) {
+                val id = (payload[i + 1].toInt() and 0xFF) or ((payload[i + 2].toInt() and 0xFF) shl 8) or
+                    ((payload[i + 3].toInt() and 0xFF) shl 16) or ((payload[i + 4].toInt() and 0xFF) shl 24)
+                if (ids.lastOrNull() != id) ids.add(id)
+                i += 20 + ((payload[i + 18].toInt() and 0xFF) or ((payload[i + 19].toInt() and 0xFF) shl 8))
             }
-            payload.write(options and 0xFF)
+            return ids
+        }
+
+        /** Mode-19 image draw: `[19][asset id:u32][x:i16][y:i16][options]`. */
+        fun imageDrawPayload(assetId: Int, x: Int, y: Int, options: Int): ByteArray? {
+            if (assetId == 0 || x !in -32768..32767 || y !in -32768..32767) return null
+            val payload = ByteArrayOutputStream()
+            payload.write(19)
+            payload.writeU32(assetId)
+            payload.writeI16(x)
+            payload.writeI16(y)
+            payload.write(options)
             return payload.toByteArray()
         }
 
         /**
-         * 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
+         * 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).
          */
-        fun stringRunPayload(
-            fontTableOffset: Int,
-            x: Int,
-            y: Int,
-            options: Int,
-            chars: ByteArray,
-        ): ByteArray? {
-            if (chars.isEmpty() || chars.size > 255) return null
-            if (fontTableOffset !in 0..(CACHE_SIZE - FONT_TABLE_CHARS * 2)) return null
-            if (x !in 0..0xFFFF || y !in 0..0xFFFF) return null
+        fun stringRunPayload(fontId: Int, x: Int, y: Int, options: Int, chars: ByteArray): ByteArray? {
+            if (chars.isEmpty() || chars.size > 255 || fontId == 0) return null
+            if (x !in -32768..32767 || y !in -32768..32767) return null
             if (chars.any { (it.toInt() and 0xFF) < 32 || (it.toInt() and 0xFF) > 126 }) return null
             val payload = ByteArrayOutputStream()
-            payload.write(14)
-            for (value in intArrayOf(fontTableOffset, x, y)) {
-                payload.write(value and 0xFF)
-                payload.write((value ushr 8) and 0xFF)
-            }
-            payload.write(options and 0xFF)
+            payload.write(20)
+            payload.writeU32(fontId)
+            payload.writeI16(x)
+            payload.writeI16(y)
+            payload.write(options)
             payload.write(chars.size)
             payload.write(chars)
             return payload.toByteArray()
         }
     }
 
-    class FontEntry(val tableOffset: Int, val cellWidth: Int, val lineHeight: Int) {
-        /** Cache offset per printable char (index = char - 32), null = not resident. */
-        val glyphOffsets = arrayOfNulls<Int>(FONT_TABLE_CHARS)
-    }
+    class FontEntry(val id: Int, val cellWidth: Int, val lineHeight: Int, val glyphs: Set<Int>)
+
+    private class Asset(val id: Int, val version: Int, val bytes: Int, var lastUse: Int)
 
     var generation = -1
         private set
 
-    private val fonts = mutableMapOf<Int, FontEntry>()
-    private val images = mutableMapOf<String, Int>()
+    /** Bytes the glasses could allocate for the store (the RESET reply says; 256 KiB when unknown). */
+    var storeCapacity = STORE_SIZE
 
-    /**
-     * 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 val fonts = mutableMapOf<String, FontEntry>()
+    private val assets = mutableMapOf<String, Asset>()
+    private val byId = mutableMapOf<Int, String>()
     private val seenImageHashes = ArrayDeque<String>()
+    private val pendingEntries = mutableListOf<ByteArray>()
+    private var useClock = 0
 
-    /** 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 val pendingUploads = mutableListOf<Pair<Int, ByteArray>>()
+    /** Predicted store occupancy of everything this mirror believes resident. */
+    var predictedBytes = 0
+        private set
 
-    /**
-     * 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.
-     */
+    /** The prediction overflowed and the mirror dropped its oldest assets; advisory. */
     var exhausted = false
         private set
 
-    /**
-     * Forget everything and adopt `generation` (the on-glass cache was freed
-     * or its state became unknown).
-     */
+    /** Forget everything and adopt `generation` (the on-glass cache was freed or reset). */
     fun reset(generation: Int) {
         this.generation = generation
         fonts.clear()
-        images.clear()
+        assets.clear()
+        byId.clear()
         seenImageHashes.clear()
-        nextOffset = 2
-        pendingUploads.clear()
+        pendingEntries.clear()
+        predictedBytes = 0
+        useClock = 0
         exhausted = false
     }
 
-    private fun allocate(length: Int): Int? {
-        if (length <= 0 || nextOffset + length > CACHE_SIZE) {
-            if (length > 0) exhausted = true
-            return null
+    /** The glasses reported these asset ids absent: upload them again on next use. */
+    fun forget(assetIds: Collection<Int>) {
+        for (id in assetIds) {
+            val key = byId.remove(id) ?: continue
+            val asset = assets.remove(key) ?: continue
+            predictedBytes -= asset.bytes
+            fonts.entries.removeAll { it.value.id == id }
         }
-        val offset = nextOffset
-        nextOffset += length
-        return offset
     }
 
-    /**
-     * 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.
-     */
-    fun font(fontSize: Int, cellWidth: Int, lineHeight: Int): FontEntry? {
-        fonts[fontSize]?.let { return it }
-        val tableOffset = allocate(FONT_TABLE_CHARS * 2) ?: return null
-        val entry = FontEntry(tableOffset, cellWidth, lineHeight)
-        fonts[fontSize] = entry
-        return entry
+    fun holds(assetId: Int): Boolean = byId.containsKey(assetId)
+
+    private fun ensureAsset(key: String, kind: Int, data: ByteArray): Int? {
+        useClock += 1
+        assets[key]?.let { it.lastUse = useClock; return it.id }
+        if (data.isEmpty() || data.size > storeCapacity) return null
+        val id = hash31(key)
+        val other = byId[id]
+        if (other != null && other != key) return null
+        val footprint = footprint(data.size)
+        makeRoom(footprint)
+        val asset = Asset(id, hash31(data), footprint, useClock)
+        assets[key] = asset
+        byId[id] = key
+        predictedBytes += footprint
+        pendingEntries.addAll(putAssetEntries(id, asset.version, kind, data))
+        return id
     }
 
-    /**
-     * 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.
-     */
-    fun ensureGlyph(font: FontEntry, char: Int, rasterize: () -> ByteArray?): Boolean {
-        if (char < 32 || char > 126) return false
-        val index = char - 32
-        if (font.glyphOffsets[index] != null) return true
-        val gray = rasterize() ?: return false
-        if (gray.size != font.cellWidth * font.lineHeight) return false
-        val image = ByteArrayOutputStream()
-        image.write(font.cellWidth)
-        image.write(font.lineHeight)
-        image.write(rleEncodePixels(gray))
-        val bytes = image.toByteArray()
-        val offset = allocate(bytes.size) ?: return false
-        font.glyphOffsets[index] = offset
-        pendingUploads.add(offset to bytes)
-        pendingUploads.add(
-            (font.tableOffset + index * 2) to
-                byteArrayOf((offset and 0xFF).toByte(), ((offset ushr 8) and 0xFF).toByte())
-        )
-        return true
+    private fun makeRoom(footprint: Int) {
+        while (predictedBytes + footprint > storeCapacity || assets.size >= MAX_ASSETS) {
+            val victim = assets.entries.minByOrNull { it.value.lastUse } ?: break
+            exhausted = true
+            assets.remove(victim.key)
+            byId.remove(victim.value.id)
+            fonts.entries.removeAll { it.value.id == victim.value.id }
+            predictedBytes -= victim.value.bytes
+        }
     }
 
     /**
-     * Record a sighting of an image content hash; true when it was already
-     * seen in an earlier frame (worth caching).
+     * 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.
      */
+    fun font(
+        fontSize: Int,
+        cellWidth: Int,
+        lineHeight: Int,
+        variant: String = "ascii",
+        codes: List<Int> = (32..126).toList(),
+        rasterize: (Int) -> ByteArray?,
+    ): FontEntry? {
+        val key = "font:$fontSize:${cellWidth}x$lineHeight:$variant"
+        fonts[key]?.let { existing ->
+            if (assets.containsKey(key)) {
+                useClock += 1
+                assets[key]?.lastUse = useClock
+                return existing
+            }
+        }
+        val table = ByteArray(FONT_TABLE_CHARS * FONT_TABLE_ENTRY_BYTES)
+        val body = ByteArrayOutputStream()
+        val glyphs = mutableSetOf<Int>()
+        for (code in codes) {
+            if (code < 32 || code > 127) continue
+            val gray = rasterize(code) ?: continue
+            if (gray.size != cellWidth * lineHeight) continue
+            val offset = table.size + body.size()
+            val index = (code - 32) * FONT_TABLE_ENTRY_BYTES
+            table[index] = (offset and 0xFF).toByte()
+            table[index + 1] = ((offset ushr 8) and 0xFF).toByte()
+            table[index + 2] = ((offset ushr 16) and 0xFF).toByte()
+            table[index + 3] = ((offset ushr 24) and 0xFF).toByte()
+            body.write(cellWidth); body.write(lineHeight)
+            body.write(rleEncodePixels(gray))
+            glyphs.add(code)
+        }
+        if (glyphs.isEmpty()) return null
+        val id = ensureAsset(key, KIND_FONT, table + body.toByteArray()) ?: return null
+        val entry = FontEntry(id, cellWidth, lineHeight, glyphs)
+        fonts[key] = entry
+        return entry
+    }
+
+    /** Record a sighting of an image content hash; true when it was already seen in an earlier frame. */
     fun noteImageSighting(hash: String): Boolean {
-        if (images.containsKey(hash)) return true
+        if (assets.containsKey(hash)) return true
         if (hash in seenImageHashes) return true
         seenImageHashes.addLast(hash)
         if (seenImageHashes.size > 32) seenImageHashes.removeFirst()
         return false
     }
 
-    /**
-     * The cache offset of an image, uploading it on first residency.
-     * `gray` is the width×height 8-bit grayscale raster.
-     */
+    /** The asset id of an image, uploading it on first residency. `gray` is the width×height 8-bit raster. */
     fun ensureImage(hash: String, gray: ByteArray, width: Int, height: Int): Int? {
-        images[hash]?.let { return it }
+        assets[hash]?.let { useClock += 1; it.lastUse = useClock; return it.id }
         if (width !in 1..255 || height !in 1..255 || gray.size != width * height) return null
         val image = ByteArrayOutputStream()
         image.write(width)
         image.write(height)
         image.write(rleEncodePixels(gray))
-        val bytes = image.toByteArray()
-        val offset = allocate(bytes.size) ?: return null
-        images[hash] = offset
-        pendingUploads.add(offset to bytes)
-        return offset
+        return ensureAsset(hash, KIND_IMAGE, image.toByteArray())
+    }
+
+    /** The asset id of a string (1..128 bytes of UTF-8, no NUL), uploading it on first use. */
+    fun ensureBytes(key: String, bytes: ByteArray): Int? {
+        if (bytes.isEmpty() || bytes.size > 128 || bytes.any { it.toInt() == 0 }) return null
+        return ensureAsset(key, KIND_STRING, bytes)
     }
 
     /**
-     * Drain the pending mode-12 entries into `[12][offset16][len16][data]...`
-     * payloads, each at most [MAX_UPLOAD_PAYLOAD_BYTES]. An entry larger than
-     * the budget gets a payload of its own (the BLE fragmenter splits it).
+     * Drain the pending PUT_ASSET entries into `[37][epoch 0][request 0][entries]`
+     * payloads, each at most [MAX_UPLOAD_PAYLOAD_BYTES]; the link stamps the epoch and request.
      */
     fun takeUploadPayloads(): List<ByteArray> {
-        if (pendingUploads.isEmpty()) return emptyList()
+        if (pendingEntries.isEmpty()) return emptyList()
         val payloads = mutableListOf<ByteArray>()
-        var current = ByteArrayOutputStream().apply { write(12) }
-        for ((offset, data) in pendingUploads) {
-            val record = ByteArrayOutputStream()
-            record.write(offset and 0xFF)
-            record.write((offset ushr 8) and 0xFF)
-            record.write(data.size and 0xFF)
-            record.write((data.size ushr 8) and 0xFF)
-            record.write(data)
-            if (current.size() > 1 && current.size() + record.size() > MAX_UPLOAD_PAYLOAD_BYTES) {
+        var current = ByteArrayOutputStream().apply { write(byteArrayOf(37, 0, 0, 0, 0)) }
+        for (entry in pendingEntries) {
+            if (current.size() > 5 && current.size() + entry.size > MAX_UPLOAD_PAYLOAD_BYTES) {
                 payloads.add(current.toByteArray())
-                current = ByteArrayOutputStream().apply { write(12) }
+                current = ByteArrayOutputStream().apply { write(byteArrayOf(37, 0, 0, 0, 0)) }
             }
-            record.writeTo(current)
+            current.write(entry)
         }
-        if (current.size() > 1) payloads.add(current.toByteArray())
-        pendingUploads.clear()
+        if (current.size() > 5) payloads.add(current.toByteArray())
+        pendingEntries.clear()
         return payloads
     }
 }