adolforeyna/tactility
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

M5Stack PaperS3 display driver improved (#647)

Browse Source
This commit is contained in:
Shadowtrance
2026-09-09 05:57:41 +10:00
committed by GitHub
parent 1b16184a72
commit 2496dea5c2
7 changed files with 347 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Devices/m5stack-papers3/source/drivers/papers3_display.cpp
+140 -14
View File
@@ -7,8 +7,10 @@
#include <tactility/error.h>
#include <tactility/log.h>
#include <tactility/module.h>
#include <tactility/time.h>
#include "epd_board_m5papers3.h"
#include <epd_board.h>
#include <epdiy.h>
#include <esp_heap_caps.h>
@@ -19,6 +21,70 @@
#define TAG "Papers3Display"
#define GET_CONFIG(device) (static_cast<const Papers3DisplayConfig*>((device)->config))
// Fast partial updates are always MODE_DU (strict black/white); config->quality_draw_mode is
// only used for the periodic full-quality pass.
static constexpr EpdDrawMode FAST_DRAW_MODE = MODE_DU;
// A partial update covering at least this fraction of the panel is a full-screen content change
// (e.g. an app switch rebuilding the whole window, see lvgl.md) rather than a small widget
// redraw, and is promoted to a quality refresh immediately.
static constexpr float FULL_AREA_QUALITY_THRESHOLD = 0.6f;
// Bounds worst-case ghost accumulation during sustained fast-mode interaction (e.g. scrolling),
// regardless of idle time. LVGL's PARTIAL-mode draw buffer covers vres/10 rows (see
// lvgl-module/source/devices/devices.cpp's buffer_height), so a single full-screen redraw is
// already ~10 tiles - this must clear a full sweep comfortably, or a normal full-screen redraw
// gets promoted to slow GC16 partway through.
static constexpr uint32_t QUALITY_REFRESH_PARTIAL_COUNT = 20;
// Cleans up ghosting left behind after interaction stops, since nothing else triggers a refresh
// once draw_bitmap() calls stop arriving. Matches the M5Stack official demo's timer.
static constexpr uint32_t QUALITY_REFRESH_IDLE_SECONDS = 10;
// LVGL's PARTIAL render mode flushes one draw_bitmap() call per still-unjoined dirty rect, so
// one visual refresh is usually several back-to-back calls, not one; this holds quality mode
// across a sibling rect's near-zero gap so they don't end up on inconsistent modes. Must stay
// well under a GC16 draw's own duration (400ms+), or it also bridges the much larger gap between
// separate real frames and pins a whole multi-frame interaction to GC16.
static constexpr uint32_t QUALITY_HOLD_MS = 50;
// epd_fullclear() (white fill + GC16 draw + 3-cycle black/white flash, see epdiy's
// highlevel.c/render.c) only runs once, at boot (papers3_display_init()), never periodically:
// it wipes the whole panel, and this driver has no way to force LVGL to redraw everything
// afterward - only whatever rect is drawn next gets restored, leaving the rest blank.
// 4x4 ordered (Bayer) dither thresholds, spread evenly across a 0-15 nibble range.
static constexpr uint8_t BAYER_4X4[4][4] = {
{ 0, 8, 2, 10 },
{ 12, 4, 14, 6 },
{ 3, 11, 1, 9 },
{ 15, 7, 13, 5 },
};
// Dithers an 8-bit luminance sample (0x00=black..0xFF=white) down to a 4-bit nibble
// (0x0=black..0xF=white, matching EPDiy's MODE_PACKING_2PPB), spreading the rounding error
// spatially instead of truncating every pixel the same way - this is what turns flat/banded
// output into something that reads as smooth grayscale.
static inline uint8_t dither_to_nibble(uint8_t luminance, int32_t x, int32_t y) {
// BAYER_4X4 is 0-15; scaled by 17 it spans a full 0-255 quantization step (one increment of
// luminance*15), so the dither bias is actually comparable to the rounding it perturbs
// instead of a few percent of one step.
const uint32_t threshold = BAYER_4X4[y & 3][x & 3] * 17U;
const uint32_t level = (static_cast<uint32_t>(luminance) * 15U + threshold) / 255U;
return static_cast<uint8_t>(level > 15U ? 15U : level);
}
// Binary variant for MODE_DU, which only supports pure black/white (see epdiy.h) - dithering
// still applies so a partial-update area doesn't look coarser than the quality pass that
// preceded it.
static inline uint8_t dither_to_bw_nibble(uint8_t luminance, int32_t x, int32_t y) {
// *16 (not 17) keeps the max threshold at 240, strictly below 255 - otherwise luminance 0xFF
// (pure white) would tie the top Bayer cell's threshold and the strict ">" would misclassify
// it as black.
const uint32_t threshold = BAYER_4X4[y & 3][x & 3] * 16U;
return luminance > threshold ? 0xF : 0x0;
}
extern "C" {
extern Module m5stack_papers3_module;
@@ -34,6 +100,15 @@ struct Papers3DisplayInternal {
// Scratch buffer for the grayscale8->EPDiy(4bpp packed, 2px/byte) conversion in draw_bitmap().
uint8_t* packed_buffer;
bool powered;
uint32_t panel_pixel_count;
// Fast (MODE_DU) partial updates since the last quality refresh; see
// QUALITY_REFRESH_PARTIAL_COUNT.
uint32_t partial_count_since_quality;
// get_ticks() at the last quality refresh; see QUALITY_REFRESH_IDLE_SECONDS.
TickType_t last_quality_refresh_tick;
// While get_ticks() < this, every draw_bitmap() call uses quality mode regardless of the
// other triggers; see QUALITY_HOLD_MS.
TickType_t quality_hold_until_tick;
};
static void power_on(Papers3DisplayInternal* internal) {
@@ -64,9 +139,48 @@ static error_t papers3_display_init(Device* device) {
// pass, leaving a faint ghost. Run a full clear now, before LVGL's first flush ever reaches
// draw_bitmap(), so it never has to undo content LVGL already put on screen.
epd_fullclear(&internal->hl_state, config->temperature_celsius);
internal->partial_count_since_quality = 0;
internal->last_quality_refresh_tick = get_ticks();
internal->quality_hold_until_tick = 0;
return ERROR_NONE;
}
// Decides whether this update should be a full-quality (config->quality_draw_mode) refresh or
// a fast MODE_DU one. Read-only - see commit_quality_mode_decision() for the state this decision
// leads to.
static bool should_use_quality_mode(Papers3DisplayInternal* internal, int32_t width, int32_t height) {
const TickType_t now = get_ticks();
const uint32_t area = static_cast<uint32_t>(width) * static_cast<uint32_t>(height);
const bool is_full_screen_change = area >= static_cast<uint32_t>(
static_cast<float>(internal->panel_pixel_count) * FULL_AREA_QUALITY_THRESHOLD
);
const bool partial_count_exceeded = internal->partial_count_since_quality >= QUALITY_REFRESH_PARTIAL_COUNT;
// Idle refresh is too problematic to worth the possible gains. So it isn't done on purpose.
// Ghosting is very minimal now anyway (it's still around but way less bad)
const bool idle_exceeded = now - internal->last_quality_refresh_tick >= seconds_to_ticks(QUALITY_REFRESH_IDLE_SECONDS);
const bool within_hold = now < internal->quality_hold_until_tick;
return is_full_screen_change || partial_count_exceeded || idle_exceeded || within_hold;
}
// Applies should_use_quality_mode()'s decision, but only commits the quality-mode reset once the
// draw actually succeeded - a failed quality refresh must not make a still-ghosting panel look
// freshly cleaned to every trigger above. A failed fast update still counts toward the partial
// count, since it was still MODE_DU content, not a clean slate.
static void commit_quality_mode_decision(Papers3DisplayInternal* internal, bool used_quality, bool draw_succeeded) {
if (used_quality) {
if (draw_succeeded) {
const TickType_t now = get_ticks();
internal->partial_count_since_quality = 0;
internal->last_quality_refresh_tick = now;
internal->quality_hold_until_tick = now + millis_to_ticks(QUALITY_HOLD_MS);
}
} else {
internal->partial_count_since_quality++;
}
}
// Reports GRAYSCALE8 (not MONOCHROME) so LVGL uses partial/tile updates instead of forcing
// full-frame - the bridge hardcodes full-frame for MONOCHROME/I1 regardless of capability flags.
// So draw_bitmap is called once per changed tile, not necessarily the whole panel.
@@ -76,11 +190,12 @@ static error_t papers3_display_draw_bitmap(Device* device, int32_t x_start, int3
const int32_t width = x_end - x_start;
const int32_t height = y_end - y_start;
const bool use_quality = should_use_quality_mode(internal, width, height);
// color_data is DISPLAY_COLOR_FORMAT_GRAYSCALE8: row-major, 1 byte/pixel luminance
// (0x00=black..0xFF=white, matching LVGL's L8). EPDiy wants 4bpp packed (2px/byte, 0x0=black,
// 0xF=white) - a plain >>4 truncation preserves all 16 real gray levels the panel supports
// (this panel is not B/W-only; see MODE_GC16/GL16 in papers3-display.yaml's draw-mode doc).
// 0xF=white); Bayer dithering (full 16-level for the quality pass, binary for MODE_DU)
// spreads the rounding error instead of a flat truncation.
const auto* src = static_cast<const uint8_t*>(color_data);
const size_t src_stride = static_cast<size_t>(width);
const size_t packed_stride = static_cast<size_t>(width + 1) / 2;
@@ -90,12 +205,18 @@ static error_t papers3_display_draw_bitmap(Device* device, int32_t x_start, int3
uint8_t* dst_row = internal->packed_buffer + static_cast<size_t>(row) * packed_stride;
int32_t col = 0;
for (; col + 2 <= width; col += 2) {
const uint8_t p0 = src_row[col] >> 4U;
const uint8_t p1 = src_row[col + 1] >> 4U;
const uint8_t p0 = use_quality
? dither_to_nibble(src_row[col], x_start + col, y_start + row)
: dither_to_bw_nibble(src_row[col], x_start + col, y_start + row);
const uint8_t p1 = use_quality
? dither_to_nibble(src_row[col + 1], x_start + col + 1, y_start + row)
: dither_to_bw_nibble(src_row[col + 1], x_start + col + 1, y_start + row);
dst_row[col / 2] = static_cast<uint8_t>((p1 << 4U) | p0);
}
if (col < width) { // odd width: last column has no pair, low nibble unused
dst_row[col / 2] = static_cast<uint8_t>(src_row[col] >> 4U);
dst_row[col / 2] = use_quality
? dither_to_nibble(src_row[col], x_start + col, y_start + row)
: dither_to_bw_nibble(src_row[col], x_start + col, y_start + row);
}
}
@@ -108,13 +229,15 @@ static error_t papers3_display_draw_bitmap(Device* device, int32_t x_start, int3
power_on(internal);
epd_draw_rotated_image(update_area, internal->packed_buffer, internal->framebuffer);
const auto draw_mode = use_quality ? config->quality_draw_mode : FAST_DRAW_MODE;
auto draw_result = epd_hl_update_area(
&internal->hl_state,
static_cast<EpdDrawMode>(config->draw_mode | MODE_PACKING_2PPB),
static_cast<EpdDrawMode>(draw_mode | MODE_PACKING_2PPB),
config->temperature_celsius,
update_area
);
commit_quality_mode_decision(internal, use_quality, draw_result == EPD_DRAW_SUCCESS);
return draw_result == EPD_DRAW_SUCCESS ? ERROR_NONE : ERROR_RESOURCE;
}
@@ -133,13 +256,11 @@ static DisplayColorFormat papers3_display_get_color_format(Device*) {
return DISPLAY_COLOR_FORMAT_GRAYSCALE8;
}
// epd_width()/epd_height() are the panel's native, unrotated dimensions (display->width/height in
// epdiy.c) - epd_rotated_display_width()/height() swap them for EPD_ROT_PORTRAIT/INVERTED_PORTRAIT.
// epd_draw_rotated_image() clamps its input rect against the *rotated* dims and epd_draw_pixel()
// applies the rotation transform on top of that (see _rotate() in epdiy.c), so both LVGL's canvas
// size and draw_bitmap()'s rect must be in rotated-space, not native-space - using the native
// epd_width()/epd_height() here fed rotated-space code a landscape-sized canvas, which produced
// exactly the "rotated + landscape" symptom this was fixed for.
// epd_width()/epd_height() are the panel's native, unrotated dimensions; epd_rotated_display_
// width()/height() swap them for EPD_ROT_PORTRAIT/INVERTED_PORTRAIT. epd_draw_rotated_image()
// clamps its input rect against the rotated dims and epd_draw_pixel() applies the rotation
// transform on top of that (see _rotate() in epdiy.c), so both LVGL's canvas size and
// draw_bitmap()'s rect must be in rotated-space, not native-space.
static uint16_t papers3_display_get_resolution_x(Device*) {
return static_cast<uint16_t>(epd_rotated_display_width());
}
@@ -232,6 +353,11 @@ static error_t start(Device* device) {
return ERROR_OUT_OF_MEMORY;
}
internal->panel_pixel_count = static_cast<uint32_t>(epd_rotated_display_width()) * static_cast<uint32_t>(epd_rotated_display_height());
internal->partial_count_since_quality = 0;
internal->last_quality_refresh_tick = get_ticks();
internal->quality_hold_until_tick = 0;
device_set_driver_data(device, internal);
LOG_I(TAG, "EPDiy initialized (%dx%d native, %dx%d rotated)", epd_width(), epd_height(), epd_rotated_display_width(), epd_rotated_display_height());