PaperS3: Fix ghosting and speed up partial updates

[Shadowtrance]

Summary

• Add generic DisplayApi::clear() and DisplayApi::refresh() hooks so the LVGL bridge can ask any capable display to wipe or quality-refresh itself, independent of draw_bitmap().
• Implement both on papers3_display, plus fix three pre-existing bugs found along the way.
• Wire an idle-repaint timer into lvgl_devices_attach() that forces a real LVGL redraw and quality pass after a period of no input, clearing e-paper ghosting from normal use without disrupting active interaction.
• Export display_has_capability, display_clear, and display_refresh as kernel symbols so side-loaded ELF apps (e.g. GraphicsDemo, MystifyDemo) can check DISPLAY_CAPABILITY_SLOW_REFRESH and call the new hooks.

papers3_display.cpp

• Fix: epd_fullclear() (the boot-priming panel wipe) lived in the DisplayApi::init() callback, but nothing in the boot path ever calls the public display_init() wrapper — it never ran. Moved into start() directly.
• Fix: draw_bitmap() used to dither into a scratch buffer, then call epd_draw_rotated_image(), which unpacks, rotates, and repacks every pixel again. Now dithers straight into the native framebuffer via epd_draw_pixel() in one pass. Removed the now-unused scratch buffer (~130KB SPIRAM freed). Measurable LVGL rendering speedup, verified across all four panel rotations.
• New: papers3_display_clear() — white-fill + one GC16 redraw, used to wipe content an app drew directly via draw_bitmap() (bypassing LVGL's screen model).
• New: papers3_display_refresh() — a GC16 pass over current content with no white-fill, for clearing ghosting without changing what's on screen. Bitwise-inverts back_fb first, since epdiy's own diffing otherwise silently skips any pixel that already matches between front_fb/back_fb regardless of draw mode — the same "guarantee a mismatch" trick epd_fullclear() uses via a white-fill, just without touching real content.
• Removed the old idle_exceeded check from should_use_quality_mode(). It only affected the next draw_bitmap() call after a gap, which could force an unwanted quality-mode promotion mid-interaction (e.g. right as a user resumes scrolling). Replaced by the LVGL-side timer below, which checks real input inactivity instead.
• Fix: quality_hold_until_tick was re-armed on every successful quality-mode draw, not just ones that were themselves bridging an existing hold gap. Since a GC16 draw takes 400ms+ (far longer than the 50ms hold), this let quality mode self-perpetuate indefinitely once triggered once. should_use_quality_mode()/commit_quality_mode_decision() now track whether the hold was already active so only draws genuinely bridging a gap extend it.

lvgl-module/source/devices/devices.cpp

• lvgl_devices_attach() now calls display_clear() for any bound DISPLAY_CAPABILITY_SLOW_REFRESH display. Runs on both boot and every app close, so it also cleans up after apps that draw outside LVGL's model.
• New idle_repaint_timer: once 5s pass with no real input activity (lv_display_get_inactive_time()), invalidates the active screen, forces a synchronous redraw (lv_refr_now()), then calls display_refresh() for the quality pass a tiled PARTIAL-mode redraw can't trigger on its own.

TactilityKernel

• DisplayApi::clear() / display_clear() and DisplayApi::refresh() / display_refresh() — new optional display hooks, both ERROR_NOT_SUPPORTED when null.
• Exported display_has_capability, display_clear, display_refresh as kernel symbols, so side-loaded ELF apps can call them too.

Summary by CodeRabbit

• New Features

  • Added support for clearing e-paper displays and forcing full-quality refreshes.
  • Displays can automatically repaint after remaining idle, helping ensure content is fully rendered.

• Improvements

  • Improved refresh handling for Papers3 displays, including bounded quality-refresh sessions.
  • Refreshes now better adapt to screen activity and update patterns.
  • Failed display refreshes can retry without unnecessarily repeating the repaint.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 05edc138-2043-4bd2-a532-5fb06e853e9d

📥 Commits

Reviewing files that changed from the base of the PR and between 896c09a and 8ae2490.

📒 Files selected for processing (2)

• Devices/m5stack-papers3/source/drivers/papers3_display.cpp
• Modules/lvgl-module/source/devices/devices.cpp

🚧 Files skipped from review as they are similar to previous changes (2)

• Modules/lvgl-module/source/devices/devices.cpp
• Devices/m5stack-papers3/source/drivers/papers3_display.cpp

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The display API now supports optional clear and refresh callbacks with kernel wrappers and exported symbols. The Papers3 driver bounds quality-refresh hold sessions and resets partial-refresh state after successful clear and refresh operations. The LVGL device layer maintains per-display idle-repaint contexts and retries refresh operations for slow-refresh displays.

Priority: ➖ Normal

Merge Risk: ⚪ Minimal · up to 8ae24

The display refresh path preserves the intended framebuffer contents after a successful full refresh, with no remaining actionable merge risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 47.83% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 23 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the primary changes: reducing PaperS3 ghosting and improving partial-update performance.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 979cecd6-5284-48ab-9827-a9fb33350a8d

📥 Commits

Reviewing files that changed from the base of the PR and between 70af88c and 896c09a.

📒 Files selected for processing (5)

• Devices/m5stack-papers3/source/drivers/papers3_display.cpp
• Modules/lvgl-module/source/devices/devices.cpp
• TactilityKernel/include/tactility/drivers/display.h
• TactilityKernel/source/drivers/display.cpp
• TactilityKernel/source/symbols.c

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

[KenVanHoeylandt]

Thank you!