feat: E-Ink "Dynamic Partial" (#3193)

Use a mixture of full refresh, partial refresh, and skipped updates, balancing urgency and display health.

Co-authored-by: Ben Meadors <benmmeadors@gmail.com>

src/graphics/EInkDisplay2.h

@@ -54,4 +54,68 @@ class EInkDisplay : public OLEDDisplay
 
     // Connect to the display
     virtual bool connect() override;
+
+#if defined(USE_EINK_DYNAMIC_PARTIAL)
+    // Full, partial, or skip: balance urgency with display health
+
+    // Use partial refresh if EITHER:
+    // * highPriority() was set
+    // * a highPriority() update was previously skipped, for rate-limiting - (EINK_HIGHPRIORITY_LIMIT_SECONDS)
+
+    // Use full refresh if EITHER:
+    // * lowPriority() was set
+    // * too many partial updates in a row: protect display - (EINK_PARTIAL_REPEAT_LIMIT)
+    // * no recent updates, and last update was partial: redraw for image quality (EINK_LOWPRIORITY_LIMIT_SECONDS)
+
+    // Rate limit if:
+    // * lowPriority() - (EINK_LOWPRIORITY_LIMIT_SECONDS)
+    // * highPriority(), if multiple partials have run back-to-back - (EINK_HIGHPRIORITY_LIMIT_SECONDS)
+
+    // Skip update entirely if ALL criteria met:
+    // * new image matches old image
+    // * lowPriority()
+    // * not redrawing for image quality
+    // * not refreshing for display health
+
+    // ------------------------------------
+
+    // To implement for your E-Ink display:
+    // * edit configForPartialRefresh()
+    // * edit configForFullRefresh()
+    // * add macros to variant.h, and adjust to taste:
+
+    /*
+        #define USE_EINK_DYNAMIC_PARTIAL
+        #define EINK_LOWPRIORITY_LIMIT_SECONDS 30
+        #define EINK_HIGHPRIORITY_LIMIT_SECONDS 1
+        #define EINK_PARTIAL_REPEAT_LIMIT 5
+    */
+
+  public:
+    void highPriority(); // Suggest partial refresh
+    void lowPriority();  // Suggest full refresh
+
+  protected:
+    void configForPartialRefresh(); // Display specific code to select partial refresh mode
+    void configForFullRefresh();    // Display specific code to return to full refresh mode
+    bool newImageMatchesOld();      // Is the new update actually different to the last image?
+    bool determineRefreshMode();    // Called immediately before data written to display - choose refresh mode, or abort update
+
+    bool isHighPriority = true;            // Does the method calling update believe that this is urgent?
+    bool needsFull = false;                // Is a full refresh forced? (display health)
+    bool missedHighPriorityUpdate = false; // Was a high priority update skipped for rate-limiting?
+    uint16_t partialRefreshCount = 0;      // How many partials have occurred since last full refresh?
+    uint32_t lastUpdateMsec = 0;           // When did the last update occur?
+    uint32_t prevImageHash = 0;            // Used to check if update will change screen image (skippable or not)
+
+    // Set in variant.h
+    const uint32_t lowPriorityLimitMsec = (uint32_t)1000 * EINK_LOWPRIORITY_LIMIT_SECONDS;   // Max rate for partial refreshes
+    const uint32_t highPriorityLimitMsec = (uint32_t)1000 * EINK_HIGHPRIORITY_LIMIT_SECONDS; // Max rate for full refreshes
+    const uint32_t partialRefreshLimit = EINK_PARTIAL_REPEAT_LIMIT; // Max consecutive partials, before full is triggered
+
+#else // !USE_EINK_DYNAMIC_PARTIAL
+    // Tolerate calls to these methods anywhere, just to be safe
+    void highPriority() {}
+    void lowPriority() {}
+#endif
 };