- Generated by
1.16.1
|
ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
|
Pluggable page-turn refresh-cadence policy for bistable (e-ink) panels. More...
Go to the source code of this file.
Data Structures | |
| struct | display_policy_t |
| Caller-owned policy state (zero heap; init once, decide per turn). More... | |
| struct | display_policy_decision_t |
| What the app should pass to display_flush for this event. More... | |
Enumerations | |
| enum | display_policy_kind_t : uint8_t { k_display_policy_fast_only = 0U , k_display_policy_quality = 1U , k_display_policy_fast_clean = 2U } |
| Selectable refresh-cadence strategies (chosen at display_policy_init). More... | |
| enum | display_turn_event_t : uint8_t { k_display_event_open = 0U , k_display_event_turn = 1U , k_display_event_chapter = 2U } |
| The page-transition event the policy reacts to. More... | |
| enum | display_policy_const_t : uint16_t { k_display_policy_clean_every_default = 8U , k_display_policy_clean_every_min = 1U , k_display_policy_clean_every_max = 256U } |
| Bounds for the periodic-clean cadence (no magic numbers). More... | |
Functions | |
| ra8_err_t | display_policy_init (display_policy_t *p, display_policy_kind_t kind, uint16_t clean_every) |
| Initialise a refresh-cadence policy. | |
| ra8_err_t | display_policy_decide (display_policy_t *p, display_turn_event_t event, display_policy_decision_t *out) |
| Decide the flush parameters for one page-transition event. | |
| ra8_err_t | display_policy_full_rect (uint16_t w, uint16_t h, display_rect_t *out) |
| Build the full-page damage rectangle for a page turn. | |
Pluggable page-turn refresh-cadence policy for bistable (e-ink) panels.
E-ink panels are bistable: every display_flush is a real, visible panel update whose cost and ghosting depend on the chosen display_refresh_hint_t (fast A2 ghosts but is snappy; clean GC16 is slow but clears ghosting; INIT is a full white reset). A reader must therefore decide, per page turn, WHICH waveform and WHICH update extent (full vs partial rect) to use.
This module isolates that decision behind a small, pure strategy object so the application stays format- and panel-agnostic (Dependency Inversion): the app feeds page-turn events in and gets a display_policy_decision_t out, then applies it via display_flush. The strategy is selectable at init (display_policy_kind_t), so the cadence can be chosen dynamically – snappy fast-only, always-clean quality, or the default fast-with-periodic-clean that trades a periodic clean GC16 against A2 ghosting build-up.
Pure logic: no MMIO, no heap, no I/O. Continuous-refresh (LCD) backends do not need it – it is inert there (every hint behaves the same on a scan-out panel).
[Ring 4 / Display] {World: NS}
Definition in file ra8_display_pal_policy.h.
| enum display_policy_const_t : uint16_t |
Bounds for the periodic-clean cadence (no magic numbers).
| Enumerator | |
|---|---|
| k_display_policy_clean_every_default | Default GC16 every N fast turns. |
| k_display_policy_clean_every_min | Clamp floor (every turn is clean). |
| k_display_policy_clean_every_max | Clamp ceiling. |
Definition at line 72 of file ra8_display_pal_policy.h.
| enum display_policy_kind_t : uint8_t |
Selectable refresh-cadence strategies (chosen at display_policy_init).
Picks the trade-off between turn latency and ghosting. The app may switch strategy dynamically by re-initialising the policy.
Definition at line 48 of file ra8_display_pal_policy.h.
| enum display_turn_event_t : uint8_t |
The page-transition event the policy reacts to.
| Enumerator | |
|---|---|
| k_display_event_open | Book/first page opened – wants a clean INIT. |
| k_display_event_turn | Ordinary next/prev page turn. |
| k_display_event_chapter | Chapter-boundary turn – wants a clean refresh. |
Definition at line 60 of file ra8_display_pal_policy.h.
|
nodiscard |
Decide the flush parameters for one page-transition event.
| [in,out] | p | Policy state (counter updated). |
| [in] | event | The page-transition that occurred. |
| [out] | out | Receives the waveform hint + full/partial extent. |
| k_ra8_ok | Decision written. |
| k_ra8_err_null_ptr | p or out is NULL. |
| k_ra8_err_invalid_arg | event out of range. |
p was initialised by display_policy_init. out points to writable storage. out holds a valid hint and the counter reflects the event. p nor out is modified. Definition at line 131 of file ra8_display_pal_policy.c.
References display_policy_decision_t::full_update, display_policy_decision_t::hint, internal_decide_fast_clean(), k_display_event_chapter, k_display_event_open, k_display_policy_fast_clean, k_display_policy_fast_only, k_display_policy_quality, k_display_refresh_fast, k_display_refresh_init, k_display_refresh_quality, k_ra8_err_invalid_arg, k_ra8_ok, display_policy_t::kind, RA8_CHECK_NULL_PTR, ra8_log_error, s_tag_policy, and display_policy_t::turns_since_clean.
Referenced by er_flush_event().
|
nodiscard |
Build the full-page damage rectangle for a page turn.
A page turn repaints the whole content area, so the partial-update rect is the full framebuffer. Apps that repaint only a sub-region (e.g. a status line) can build their own display_rect_t instead.
| [in] | w | Framebuffer width in pixels (> 0). |
| [in] | h | Framebuffer height in pixels (> 0). |
| [out] | out | Receives the {0,0,w,h} rectangle. |
| k_ra8_ok | Rectangle written. |
| k_ra8_err_null_ptr | out is NULL. |
| k_ra8_err_invalid_arg | w or h is 0. |
out points to writable storage. w and h are non-zero. out == {0,0,w,h}. out is unmodified. Definition at line 167 of file ra8_display_pal_policy.c.
References display_rect_t::h, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_error, s_tag_policy, display_rect_t::w, display_rect_t::x, and display_rect_t::y.
Referenced by er_flush_event().
|
nodiscard |
Initialise a refresh-cadence policy.
Selects the strategy and (for k_display_policy_fast_clean) the clean cadence, then resets the turn counter. The policy is then driven one event at a time via display_policy_decide.
| [out] | p | Policy state to initialise. |
| [in] | kind | Strategy to run. |
| [in] | clean_every | GC16 cadence for k_display_policy_fast_clean; clamped to [min,max]; ignored by the other strategies. |
| k_ra8_ok | Initialised. |
| k_ra8_err_null_ptr | p is NULL. |
| k_ra8_err_invalid_arg | kind out of range. |
p points to writable storage. kind is a defined display_policy_kind_t. p is unmodified. Definition at line 118 of file ra8_display_pal_policy.c.
References display_policy_t::clean_every, internal_clamp_clean_every(), k_display_policy_fast_clean, k_ra8_err_invalid_arg, k_ra8_ok, display_policy_t::kind, RA8_CHECK_NULL_PTR, ra8_log_error, s_tag_policy, and display_policy_t::turns_since_clean.
Referenced by main().
1.16.1