@mentra/bluetooth-sdk 0.1.18 → 0.1.19

package/ios/Source/sgcs/SGCManager.swift

@@ -1,5 +1,49 @@
 import Foundation
 
+/// One element of a scene frame (display.render()). Geometry is raw pixels on
+/// the device's drawable canvas; `change` is the host differ's annotation
+/// against the previous frame sent to this device.
+struct SceneElement {
+    let id: String
+    let type: String // "text" | "rect" | "image"
+    let x: Int32
+    let y: Int32
+    let w: Int32
+    let h: Int32
+    let text: String?
+    let data: String? // base64 image pixels (SGC decodes → re-encodes to wire format)
+    let border: Int32
+    let radius: Int32
+    let change: String // "created" | "updated" | "moved" | "unchanged"
+    let contentHash: String
+
+    func with(change: String) -> SceneElement {
+        SceneElement(
+            id: id, type: type, x: x, y: y, w: w, h: h, text: text, data: data,
+            border: border, radius: radius, change: change, contentHash: contentHash
+        )
+    }
+}
+
+/// A whole scene from the host pipeline — the full frame plus per-element
+/// change annotations and host-computed removes. Full-frame consumers can
+/// serialize `elements` and ignore the annotations; per-element consumers walk
+/// them.
+struct SceneFrame {
+    let appId: String
+    let epoch: Int
+    let replay: Bool
+    let elements: [SceneElement]
+    let removed: [String]
+
+    func asReplay() -> SceneFrame {
+        SceneFrame(
+            appId: appId, epoch: epoch, replay: true,
+            elements: elements.map { $0.with(change: "created") }, removed: removed
+        )
+    }
+}
+
 @MainActor
 protocol SGCManager {
     // MARK: - hard coded device properties:
@@ -62,6 +106,29 @@ protocol SGCManager {
         _ text: String, x: Int32, y: Int32, width: Int32, height: Int32,
         borderWidth: Int32, borderRadius: Int32
     ) async
+
+    // MARK: - Scene display (display.render() pipeline)
+
+    /// Retained element verbs — identity is the element id. Defaults delegate
+    /// to the positioned/bitmap paths (see extension); SGCs with retained
+    /// components (G2 containers, Mentra Display canvas) override for
+    /// update-in-place / delete semantics.
+    func drawLayoutText(
+        _ text: String, x: Int32, y: Int32, width: Int32, height: Int32,
+        borderWidth: Int32, borderRadius: Int32, elementId: String, layoutId: String?
+    ) async
+    func drawLayoutBitmap(
+        base64ImageData: String, x: Int32, y: Int32, width: Int32, height: Int32,
+        elementId: String, layoutId: String?
+    ) async -> Bool
+    func removeLayoutElement(_ elementId: String, layoutId: String?) async
+    /// Apply a whole host-diffed scene frame (default: paint-then-sweep over the verbs above).
+    func applySceneFrame(_ frame: SceneFrame) async
+    /// A replay frame is about to repaint from scratch — reset retained bookkeeping.
+    func onSceneReplay(_ appId: String) async
+    /// Remove a set of scene elements (scene→legacy handoff sweep).
+    func clearSceneElements(_ elementIds: [String]) async
+
     func showDashboard()
     func setDashboardPosition(_ height: Int, _ depth: Int)
     /// Default implementation sends both via [setDashboardPosition]; Nex overrides to one protobuf.
@@ -156,6 +223,94 @@ extension SGCManager {
         borderWidth _: Int32, borderRadius _: Int32
     ) async {}
 
+    // MARK: - Scene display defaults
+
+    /// Default: ignore the ids and behave like the positioned-text path.
+    func drawLayoutText(
+        _ text: String, x: Int32, y: Int32, width: Int32, height: Int32,
+        borderWidth: Int32, borderRadius: Int32, elementId _: String, layoutId _: String?
+    ) async {
+        await sendPositionedText(
+            text, x: x, y: y, width: width, height: height,
+            borderWidth: borderWidth, borderRadius: borderRadius
+        )
+    }
+
+    /// Default: ignore the ids and behave like displayBitmap.
+    func drawLayoutBitmap(
+        base64ImageData: String, x: Int32, y: Int32, width: Int32, height: Int32,
+        elementId _: String, layoutId _: String?
+    ) async -> Bool {
+        await displayBitmap(base64ImageData: base64ImageData, x: x, y: y, width: width, height: height)
+    }
+
+    /// Default: no-op (SGC has no retained elements).
+    func removeLayoutElement(_: String, layoutId _: String?) async {}
+
+    /// Default: no retained bookkeeping to reset.
+    func onSceneReplay(_: String) async {}
+
+    /// Default sweep: remove each element individually.
+    func clearSceneElements(_ elementIds: [String]) async {
+        for id in elementIds {
+            await removeLayoutElement(id, layoutId: nil)
+        }
+    }
+
+    /// Apply a whole scene frame from the host pipeline (display.render()).
+    ///
+    /// The host has already diffed the scene, so each element arrives annotated
+    /// and `removed` lists what disappeared. PAINT-THEN-SWEEP: creates/updates/
+    /// moves land first, removes go LAST — a scene transition never shows a
+    /// blank interval. "unchanged" elements are skipped entirely (this is also
+    /// what prevents image re-uploads over BLE). Replay frames arrive
+    /// all-"created" and reset retained bookkeeping first, because firmware
+    /// silently drops updates to dead component ids. Rects compile to empty
+    /// bordered text boxes (no shape primitive on current targets) and always
+    /// get a visible border.
+    func applySceneFrame(_ frame: SceneFrame) async {
+        if frame.replay {
+            await onSceneReplay(frame.appId)
+        }
+        // An id in `removed` that ALSO appears in `elements` is a type change
+        // (the differ keys matches by type:id). Its removal must run BEFORE the
+        // paint — registries key by id, so a post-paint sweep would delete the
+        // just-painted replacement.
+        let paintedIds = Set(frame.elements.map { $0.id })
+        for id in frame.removed where paintedIds.contains(id) {
+            await removeLayoutElement(id, layoutId: frame.appId)
+        }
+        for el in frame.elements {
+            if !frame.replay, el.change == "unchanged" { continue }
+            switch el.type {
+            case "text":
+                await drawLayoutText(
+                    el.text ?? "", x: el.x, y: el.y, width: el.w, height: el.h,
+                    borderWidth: el.border, borderRadius: el.radius,
+                    elementId: el.id, layoutId: frame.appId
+                )
+            case "rect":
+                await drawLayoutText(
+                    "", x: el.x, y: el.y, width: el.w, height: el.h,
+                    borderWidth: max(1, el.border), borderRadius: el.radius,
+                    elementId: el.id, layoutId: frame.appId
+                )
+            case "image":
+                if let data = el.data {
+                    _ = await drawLayoutBitmap(
+                        base64ImageData: data, x: el.x, y: el.y, width: el.w, height: el.h,
+                        elementId: el.id, layoutId: frame.appId
+                    )
+                }
+            default:
+                Bridge.log("SGC: applySceneFrame: unknown element type \(el.type)")
+            }
+        }
+        for id in frame.removed where !paintedIds.contains(id) {
+            await removeLayoutElement(id, layoutId: frame.appId)
+        }
+    }
+
     // MARK: - Video recording (default: ignore custom settings, use saved defaults)
 
     func startVideoRecording(