ra8_display_pal_eink.c

Go to the documentation of this file.

 
#include "ra8_display_pal_eink.h"
 
#include <stddef.h>
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_display_pal.h"
#include "ra8_display_pal_internal.h"
#include "ra8_epaper.h"
#include "ra8_err.h"
#include "ra8_log.h"

static const char* const s_tag = "ra8_display_pal_eink";

typedef struct {
  display_caps_t caps;        
  display_fb_t   fb;          
  bool           initialised; 
} eink_ctx_t;

static eink_ctx_t s_eink_ctx;

typedef enum : uint32_t {
  k_eink_rgb565_bpp         = 2U,      
  k_eink_refresh_quality_us = 450000U, 
  k_eink_line_max_px        = 4096U,   
  k_eink_luma_r             = 77U,     
  k_eink_luma_g             = 150U,    
  k_eink_luma_b             = 29U,     
  k_eink_luma_shift         = 8U,      
  k_eink_nibble_shift       = 4U,      
  k_eink_px_per_byte_4bpp   = 2U,      
  k_eink_nibble_mask        = 0x0FU,   
  k_eink_white_nibble       = 0x0FU,   
} ra8_display_pal_eink_const_t;

typedef enum : uint16_t {
  k_eink_r5_shift = 11U,   
  k_eink_g6_shift = 5U,    
  k_eink_r5_mask  = 0x1FU, 
  k_eink_g6_mask  = 0x3FU, 
  k_eink_b5_mask  = 0x1FU, 
} ra8_display_pal_eink_rgb_t;

static uint8_t s_eink_line[k_eink_line_max_px];
 
/* =============================================================================
 * Conversion + mapping helpers
 * =============================================================================
 */
 
uint8_t ra8_display_pal_eink_luma_from_rgb565(uint16_t px)
{
  const uint32_t r5 = (uint32_t)((px >> (uint16_t)k_eink_r5_shift) & (uint16_t)k_eink_r5_mask);
  const uint32_t g6 = (uint32_t)((px >> (uint16_t)k_eink_g6_shift) & (uint16_t)k_eink_g6_mask);
  const uint32_t b5 = (uint32_t)(px & (uint16_t)k_eink_b5_mask);
  /* Expand 5/6-bit channels to 8-bit by bit-replication (0->0, max->255). */
  const uint32_t r8   = (r5 << 3U) | (r5 >> 2U);
  const uint32_t g8   = (g6 << 2U) | (g6 >> 4U);
  const uint32_t b8   = (b5 << 3U) | (b5 >> 2U);
  const uint32_t luma = ((r8 * (uint32_t)k_eink_luma_r) + (g8 * (uint32_t)k_eink_luma_g) +
                         (b8 * (uint32_t)k_eink_luma_b)) >>
                        (uint32_t)k_eink_luma_shift;
  return (uint8_t)luma;
}

RA8_INTERNAL
static ra8_epaper_waveform_t internal_eink_waveform(display_refresh_hint_t hint)
{
  if (hint == k_display_refresh_fast) {
    return k_ra8_epaper_wf_a2;
  }
  if (hint == k_display_refresh_init) {
    return k_ra8_epaper_wf_init;
  }
  return k_ra8_epaper_wf_gc16;
}

RA8_INTERNAL
static ra8_err_t internal_eink_validate_cfg(const display_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg->framebuffer, s_tag, "cfg->framebuffer");
  if (cfg->width_px == 0U || cfg->height_px == 0U) {
    return k_ra8_err_invalid_arg;
  }
  if (cfg->pixfmt != k_display_pixfmt_rgb565) {
    return k_ra8_err_not_supported;
  }
  if (cfg->width_px > (uint16_t)k_eink_line_max_px) {
    return k_ra8_err_invalid_arg;
  }
  /* The IT8951 descriptor is BSP-supplied through panel_timing. */
  if (cfg->panel_timing == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  const uint32_t need_bytes =
    (uint32_t)cfg->width_px * (uint32_t)cfg->height_px * (uint32_t)k_eink_rgb565_bpp;
  if (cfg->framebuffer_bytes < need_bytes) {
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static void internal_eink_snapshot(const display_cfg_t* cfg)
{
  const uint32_t stride                   = (uint32_t)cfg->width_px * (uint32_t)k_eink_rgb565_bpp;
  s_eink_ctx.caps.width_px                = cfg->width_px;
  s_eink_ctx.caps.height_px               = cfg->height_px;
  s_eink_ctx.caps.pixfmt                  = k_display_pixfmt_rgb565;
  s_eink_ctx.caps.stride_bytes            = stride;
  s_eink_ctx.caps.refresh_latency_us_typ  = (uint32_t)k_eink_refresh_quality_us;
  s_eink_ctx.caps.supports_partial_update = true;
  s_eink_ctx.caps.continuous_refresh      = false;
 
  s_eink_ctx.fb.pixels       = cfg->framebuffer;
  s_eink_ctx.fb.width_px     = cfg->width_px;
  s_eink_ctx.fb.height_px    = cfg->height_px;
  s_eink_ctx.fb.stride_bytes = stride;
  s_eink_ctx.fb.pixfmt       = k_display_pixfmt_rgb565;
  s_eink_ctx.initialised     = true;
}

RA8_INTERNAL
static ra8_err_t internal_eink_check_rect(const display_caps_t* caps, display_rect_t r)
{
  if (r.x > caps->width_px) {
    return k_ra8_err_invalid_arg;
  }
  if (r.y > caps->height_px) {
    return k_ra8_err_invalid_arg;
  }
  if ((uint32_t)r.x + (uint32_t)r.w > (uint32_t)caps->width_px) {
    return k_ra8_err_invalid_arg;
  }
  if ((uint32_t)r.y + (uint32_t)r.h > (uint32_t)caps->height_px) {
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static void internal_eink_pack_row_4bpp(const uint16_t* src, uint16_t width)
{
  const uint32_t px_per_byte = (uint32_t)k_eink_px_per_byte_4bpp;
  for (uint32_t col = 0U; col < (uint32_t)width; col += px_per_byte) {
    /* The controller keeps only the high nibble of an 8 bpp byte, so
     * dropping the low nibble here costs nothing optically and halves the
     * bytes on the wire. */
    const uint8_t  hi_px           = ra8_display_pal_eink_luma_from_rgb565(src[col]);
    const uint32_t next            = col + 1U;
    const uint8_t  lo_px           = (next < (uint32_t)width)
                                       ? ra8_display_pal_eink_luma_from_rgb565(src[next])
                                       : (uint8_t)(k_eink_white_nibble << k_eink_nibble_shift);
    const uint8_t  hi_n            = (uint8_t)((hi_px >> k_eink_nibble_shift) & k_eink_nibble_mask);
    const uint8_t  lo_n            = (uint8_t)((lo_px >> k_eink_nibble_shift) & k_eink_nibble_mask);
    s_eink_line[col / px_per_byte] = (uint8_t)((uint8_t)(hi_n << k_eink_nibble_shift) | lo_n);
  }
}

RA8_INTERNAL
static ra8_err_t internal_eink_load_rect(const eink_ctx_t* c, display_rect_t rect)
{
  const uint16_t* fb    = (const uint16_t*)c->fb.pixels;
  const uint32_t  width = (uint32_t)c->fb.width_px;
  for (uint16_t row = 0U; row < rect.h; ++row) {
    const uint16_t* src = &fb[(((uint32_t)rect.y + row) * width) + rect.x];
    internal_eink_pack_row_4bpp(src, rect.w);
    const ra8_epaper_area_t area = {.x      = rect.x,
                                    .y      = (uint16_t)(rect.y + row),
                                    .width  = rect.w,
                                    .height = 1U};
    size_t                  need = 0U;
    const ra8_err_t         serr = ra8_epaper_image_bytes(&area, k_ra8_epaper_pf_4bpp, &need);
    if (serr != k_ra8_ok) {
      return serr;
    }
    const ra8_err_t err = ra8_epaper_load_image(&area,
                                                s_eink_line,
                                                need,
                                                k_ra8_epaper_pf_4bpp,
                                                k_ra8_epaper_endian_little);
    if (err != k_ra8_ok) {
      return err;
    }
  }
  return k_ra8_ok;
}
 
/* =============================================================================
 * Vtable callbacks
 * =============================================================================
 */

RA8_INTERNAL
static ra8_err_t internal_eink_init(const display_cfg_t* cfg, void** out_ctx)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg");
  RA8_CHECK_NULL_PTR(out_ctx, s_tag, "out_ctx");
  const ra8_err_t v = internal_eink_validate_cfg(cfg);
  if (v != k_ra8_ok) {
    return v;
  }
  if (s_eink_ctx.initialised) {
    ra8_log_error(s_tag, "internal_eink_init: already initialised");
    return k_ra8_err_busy;
  }
  const ra8_err_t err = ra8_epaper_init((const ra8_epaper_cfg_t*)cfg->panel_timing);
  if (err != k_ra8_ok) {
    ra8_log_error(s_tag, "internal_eink_init: ra8_epaper_init failed");
    return err;
  }
  internal_eink_snapshot(cfg);
  *out_ctx = &s_eink_ctx;
  ra8_log_info(s_tag, "internal_eink_init: IT8951 backend bound");
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_eink_get_caps(const void* ctx, display_caps_t* out)
{
  RA8_CHECK_NULL_PTR(ctx, s_tag, "ctx");
  RA8_CHECK_NULL_PTR(out, s_tag, "out");
  *out = ((const eink_ctx_t*)ctx)->caps;
  return k_ra8_ok;
}

RA8_INTERNAL
/* cppcheck-suppress constParameterCallback -- display_pal_ops_t fixes this callback's context type as void*. */
static ra8_err_t internal_eink_get_framebuffer(void* ctx, display_fb_t* out)
{
  RA8_CHECK_NULL_PTR(ctx, s_tag, "ctx");
  RA8_CHECK_NULL_PTR(out, s_tag, "out");
  *out = ((const eink_ctx_t*)ctx)->fb;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_eink_flush(void* ctx, display_rect_t rect, display_refresh_hint_t hint)
{
  RA8_CHECK_NULL_PTR(ctx, s_tag, "ctx");
  const eink_ctx_t* c = (const eink_ctx_t*)ctx;
  const ra8_err_t   v = internal_eink_check_rect(&c->caps, rect);
  if (v != k_ra8_ok) {
    return v;
  }
  const ra8_err_t lerr = internal_eink_load_rect(c, rect);
  if (lerr != k_ra8_ok) {
    return lerr;
  }
  const ra8_epaper_area_t area = {.x = rect.x, .y = rect.y, .width = rect.w, .height = rect.h};
  return ra8_epaper_display_area(&area, internal_eink_waveform(hint));
}

RA8_INTERNAL
static ra8_err_t internal_eink_clear(void* ctx, uint32_t color)
{
  RA8_CHECK_NULL_PTR(ctx, s_tag, "ctx");
  eink_ctx_t*    c            = (eink_ctx_t*)ctx;
  uint16_t*      pixels       = (uint16_t*)c->fb.pixels;
  const uint32_t pixels_total = (uint32_t)c->fb.width_px * (uint32_t)c->fb.height_px;
  const uint16_t rgb565       = (uint16_t)(color & (uint32_t)UINT16_MAX);
  for (uint32_t i = 0U; i < pixels_total; ++i) {
    pixels[i] = rgb565;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_eink_deinit(void* ctx)
{
  RA8_CHECK_NULL_PTR(ctx, s_tag, "ctx");
  eink_ctx_t*     c   = (eink_ctx_t*)ctx;
  const ra8_err_t err = ra8_epaper_sleep();
  c->initialised      = false;
  c->fb.pixels        = nullptr;
  return err;
}
 
/* =============================================================================
 * Public iface instance
 * =============================================================================
 */
 
const display_backend_iface_t k_display_backend_eink_it8951 = {
  .init            = internal_eink_init,
  .get_caps        = internal_eink_get_caps,
  .get_framebuffer = internal_eink_get_framebuffer,
  .flush           = internal_eink_flush,
  .clear           = internal_eink_clear,
  .deinit          = internal_eink_deinit,
};