Display API updates to better support EPD displays

[andysan]

Background

Bistable (EPD) displays are usually slow to update (multiple seconds). In some cases, such displays support faster partial updates. However, many vendors recommend that a full update is performed at regular intervals.

Since updating an EPD display takes a long time, the GD7965 driver implements a mechanism to inhibit updates while blanking is on and then request a full update when blanking is turned off. #47447 implements similar behaviour for SSD16xx. This works well in practice, but seems like a slight abuse of the existing API.

To make matters somewhat more complicated, the controllers we currently support have slightly different mechanisms to support partial updates:

• The SSD16xx contains two internal framebuffers and is able to automatically tracks the regions that need to be updated on a partial refresh (this is currently not supported by the driver).
• The GD7965 requires that a the driver specifies a rectangular window of pixels to update.

The GD7965 driver implements partial updates for all writes unless blanking is on. SSD16xx currently always requests a full refresh on every write which makes some LVGL applications painfully slow.

Problems in the current API

1. There is no way to manually request a full refresh. A workaround could be to make the refresh when blanking turns off a full refresh by convention. However, this would make it harder to implement efficient partial updates in the SSD16xx driver.

2. There is currently no documented way to batch multiple writes into one update. Blanking seems to be the convention though.

3. There is currently no way to detect if partial updates are supported.

Proposed solutions

Problem 1 - alternative 1

Add an API to discover optional device capabilities and set flags. Discovery could use the existing capabilities API by adding a supported_flags field to thedisplay_capabilities struct. A new APIs to query and update flags would be needed. The user of the API would set a DISPLAY_FLAG_PARTIAL_UPDATES flag to request that future writes are committed using partial updates.

Display drivers that support partial updates would be free to decide how to handle updates when blanking turns off. The SSD16xx driver could use partial updates in this case. The GD7965 driver would need to track the number of writes and request a full update if multiple regions have been updated. Alternatively, it could try to track the region that needs to be updated and by extending the update rectangle to cover the union of all writes.

Problem 1 - alternative 2

The same functionality could be implemented using a pair of functions, display_partial_on and display_partial_off, but it seems like that solution wouldn't scale if more state is needed for other display types in the future.

Problem 1 - alternative 3

Add an API to force a full refresh. For example: display_epd_full_refresh.

This could either be included instead of alternative 1 and 2 above in which case a partial update would always be performed if the display driver supports it. It could also be combined with one of the proposals above and used as a mechanism to force a full refresh (to reduce ghosting) without updating the screen contents.

Problem 2 - alternative 1

Update the documentation to describe the convention when using EPD displays.

Problem 2 - alternative 2

If we have a flags mechanism, a cleaner approach might be to have a DISPLAY_FLAG_INHIBIT_REFRESH.

Problem 3

Make partial updates discoverable using the existing capabilities mechanism. It might be worth distinguishing between window (GD7965) and full-screen partial updates (SSD16xx). Clients of the API could use this information to periodically request a full refresh to reduce ghosting.

LVGL interaction

It should be possible to extend lvgl_flush_cb_mono to request blanking when using an EPD display. Blanking can be turned off when the last chunk has been rendered by querying lv_disp_flush_is_last. This works well for full-screen updates and partial updates on the SSD16xx. Displays implementing update windows may be more problematic (GD7965) since it might effectively disable partial updates unless the driver tracks keeps track of the rectangles updated and dynamically adjusts.