display.h

Go to the documentation of this file.

#pragma once
 
#include <cstdarg>
#include <vector>
 
#include "rect.h"
 
#include "esphome/core/color.h"
#include "esphome/core/automation.h"
#include "esphome/core/defines.h"
#include "esphome/core/helpers.h"
#include "esphome/core/time.h"
#include "esphome/core/log.h"
#include "display_color_utils.h"
 
#ifdef USE_GRAPH
#include "esphome/components/graph/graph.h"
#endif
 
#ifdef USE_QR_CODE
#include "esphome/components/qr_code/qr_code.h"
#endif
 
#ifdef USE_GRAPHICAL_DISPLAY_MENU
#include "esphome/components/graphical_display_menu/graphical_display_menu.h"
#endif
 
namespace esphome::display {
 
enum class TextAlign {
  TOP = 0x00,
  CENTER_VERTICAL = 0x01,
  BASELINE = 0x02,
  BOTTOM = 0x04,
 
  LEFT = 0x00,
  CENTER_HORIZONTAL = 0x08,
  RIGHT = 0x10,
 
  TOP_LEFT = TOP | LEFT,
  TOP_CENTER = TOP | CENTER_HORIZONTAL,
  TOP_RIGHT = TOP | RIGHT,
 
  CENTER_LEFT = CENTER_VERTICAL | LEFT,
  CENTER = CENTER_VERTICAL | CENTER_HORIZONTAL,
  CENTER_RIGHT = CENTER_VERTICAL | RIGHT,
 
  BASELINE_LEFT = BASELINE | LEFT,
  BASELINE_CENTER = BASELINE | CENTER_HORIZONTAL,
  BASELINE_RIGHT = BASELINE | RIGHT,
 
  BOTTOM_LEFT = BOTTOM | LEFT,
  BOTTOM_CENTER = BOTTOM | CENTER_HORIZONTAL,
  BOTTOM_RIGHT = BOTTOM | RIGHT,
};
 
enum class ImageAlign {
  TOP = 0x00,
  CENTER_VERTICAL = 0x01,
  BOTTOM = 0x02,
 
  LEFT = 0x00,
  CENTER_HORIZONTAL = 0x04,
  RIGHT = 0x08,
 
  TOP_LEFT = TOP | LEFT,
  TOP_CENTER = TOP | CENTER_HORIZONTAL,
  TOP_RIGHT = TOP | RIGHT,
 
  CENTER_LEFT = CENTER_VERTICAL | LEFT,
  CENTER = CENTER_VERTICAL | CENTER_HORIZONTAL,
  CENTER_RIGHT = CENTER_VERTICAL | RIGHT,
 
  BOTTOM_LEFT = BOTTOM | LEFT,
  BOTTOM_CENTER = BOTTOM | CENTER_HORIZONTAL,
  BOTTOM_RIGHT = BOTTOM | RIGHT,
 
  HORIZONTAL_ALIGNMENT = LEFT | CENTER_HORIZONTAL | RIGHT,
  VERTICAL_ALIGNMENT = TOP | CENTER_VERTICAL | BOTTOM
};
 
enum DisplayType {
  DISPLAY_TYPE_BINARY = 1,
  DISPLAY_TYPE_GRAYSCALE = 2,
  DISPLAY_TYPE_COLOR = 3,
};
 
enum DisplayRotation {
  DISPLAY_ROTATION_0_DEGREES = 0,
  DISPLAY_ROTATION_90_DEGREES = 90,
  DISPLAY_ROTATION_180_DEGREES = 180,
  DISPLAY_ROTATION_270_DEGREES = 270,
};
 
constexpr bool rotation_swaps_axes(DisplayRotation rotation) {
  return rotation == DISPLAY_ROTATION_90_DEGREES || rotation == DISPLAY_ROTATION_270_DEGREES;
}
 
const int EDGES_TRIGON = 3;
const int EDGES_TRIANGLE = 3;
const int EDGES_TETRAGON = 4;
const int EDGES_QUADRILATERAL = 4;
const int EDGES_PENTAGON = 5;
const int EDGES_HEXAGON = 6;
const int EDGES_HEPTAGON = 7;
const int EDGES_OCTAGON = 8;
const int EDGES_NONAGON = 9;
const int EDGES_ENNEAGON = 9;
const int EDGES_DECAGON = 10;
const int EDGES_HENDECAGON = 11;
const int EDGES_DODECAGON = 12;
const int EDGES_TRIDECAGON = 13;
const int EDGES_TETRADECAGON = 14;
const int EDGES_PENTADECAGON = 15;
const int EDGES_HEXADECAGON = 16;
 
const float ROTATION_0_DEGREES = 0.0;
const float ROTATION_45_DEGREES = 45.0;
const float ROTATION_90_DEGREES = 90.0;
const float ROTATION_180_DEGREES = 180.0;
const float ROTATION_270_DEGREES = 270.0;
 
enum RegularPolygonVariation {
  VARIATION_POINTY_TOP = 0,
  VARIATION_FLAT_TOP = 1,
};
 
enum RegularPolygonDrawing {
  DRAWING_OUTLINE = 0,
  DRAWING_FILLED = 1,
};
 
class Display;
class DisplayPage;
 
template<typename T> class DisplayWriter {
 public:
  DisplayWriter() : type_(NONE) {}
 
  // For stateless lambdas (convertible to function pointer): use function pointer (4 bytes)
  template<typename F>
  DisplayWriter(F f)
    requires std::invocable<F, T &> && std::convertible_to<F, void (*)(T &)>
      : type_(STATELESS_LAMBDA) {
    this->stateless_f_ = f;  // Implicit conversion to function pointer
  }
 
  // For stateful lambdas and std::function (not convertible to function pointer): use std::function* (heap allocated)
  // This handles backwards compatibility with external components
  template<typename F>
  DisplayWriter(F f)
    requires std::invocable<F, T &> && (!std::convertible_to<F, void (*)(T &)>)
      : type_(LAMBDA) {
    this->f_ = new std::function<void(T &)>(std::move(f));
  }
 
  // Copy constructor
  DisplayWriter(const DisplayWriter &other) : type_(other.type_) {
    if (type_ == LAMBDA) {
      this->f_ = new std::function<void(T &)>(*other.f_);
    } else if (type_ == STATELESS_LAMBDA) {
      this->stateless_f_ = other.stateless_f_;
    }
  }
 
  // Move constructor
  DisplayWriter(DisplayWriter &&other) noexcept : type_(other.type_) {
    if (type_ == LAMBDA) {
      this->f_ = other.f_;
      other.f_ = nullptr;
    } else if (type_ == STATELESS_LAMBDA) {
      this->stateless_f_ = other.stateless_f_;
    }
    other.type_ = NONE;
  }
 
  // Assignment operators
  DisplayWriter &operator=(const DisplayWriter &other) {
    if (this != &other) {
      this->~DisplayWriter();
      new (this) DisplayWriter(other);
    }
    return *this;
  }
 
  DisplayWriter &operator=(DisplayWriter &&other) noexcept {
    if (this != &other) {
      this->~DisplayWriter();
      new (this) DisplayWriter(std::move(other));
    }
    return *this;
  }
 
  ~DisplayWriter() {
    if (type_ == LAMBDA) {
      delete this->f_;
    }
    // STATELESS_LAMBDA/NONE: no cleanup needed (function pointer or empty)
  }
 
  bool has_value() const { return this->type_ != NONE; }
 
  void call(T &display) const {
    switch (this->type_) {
      case STATELESS_LAMBDA:
        this->stateless_f_(display);  // Direct function pointer call
        break;
      case LAMBDA:
        (*this->f_)(display);  // std::function call
        break;
      case NONE:
      default:
        break;
    }
  }
 
  // Operator() for convenience
  void operator()(T &display) const { this->call(display); }
 
  // Operator* for backwards compatibility with (*writer_)(*this) pattern
  DisplayWriter &operator*() { return *this; }
  const DisplayWriter &operator*() const { return *this; }
 
 protected:
  enum : uint8_t {
    NONE,
    LAMBDA,
    STATELESS_LAMBDA,
  } type_;
 
  union {
    std::function<void(T &)> *f_;
    void (*stateless_f_)(T &);
  };
};
 
// Type alias for Display writer - uses optimized DisplayWriter instead of std::function
using display_writer_t = DisplayWriter<Display>;
 
// Callers usually pass `this`; checking a copy keeps GCC's -Wnonnull-compare quiet.
#define LOG_DISPLAY(prefix, type, obj) \
  if (auto *log_display_obj = (obj); log_display_obj != nullptr) { \
    ESP_LOGCONFIG(TAG, \
                  prefix type "\n" \
                              "%s  Rotations: %d °\n" \
                              "%s  Dimensions: %dpx x %dpx", \
                  prefix, log_display_obj->get_rotation(), prefix, log_display_obj->get_width(), \
                  log_display_obj->get_height()); \
  }
 
inline constexpr Color COLOR_OFF(0, 0, 0, 0);
inline constexpr Color COLOR_ON(255, 255, 255, 255);
 
class BaseImage {
 public:
  virtual void draw(int x, int y, Display *display, Color color_on, Color color_off) = 0;
  virtual int get_width() const = 0;
  virtual int get_height() const = 0;
};
 
class BaseFont {
 public:
  virtual void print(int x, int y, Display *display, Color color, const char *text, Color background) = 0;
  virtual void measure(const char *str, int *width, int *x_offset, int *baseline, int *height) = 0;
};
 
class Display : public PollingComponent {
 public:
  virtual void fill(Color color);
  virtual void clear();
 
  virtual int get_width() { return this->get_width_internal(); }
  virtual int get_height() { return this->get_height_internal(); }
 
  int get_native_width() { return this->get_width_internal(); }
  int get_native_height() { return this->get_height_internal(); }
 
  inline void draw_pixel_at(int x, int y) { this->draw_pixel_at(x, y, COLOR_ON); }
 
  virtual void draw_pixel_at(int x, int y, Color color) = 0;
 
  void draw_pixels_at(int x_start, int y_start, int w, int h, const uint8_t *ptr, ColorBitness bitness, bool big_endian,
                      int x_offset, int y_offset, int x_pad) {
    this->draw_pixels_internal(x_start, y_start, w, h, ptr, bitness, big_endian, x_offset, y_offset, x_pad);
  }
 
  void draw_pixels_at(int x_start, int y_start, int w, int h, const uint8_t *ptr, ColorBitness bitness,
                      bool big_endian) {
    this->draw_pixels_internal(x_start, y_start, w, h, ptr, bitness, big_endian, 0, 0, 0);
  }
 
  // Remove before 2027.5.0
  ESPDEPRECATED(
      "Pixels are always RGB: call draw_pixels_at() without the ColorOrder, and override draw_pixels_internal() "
      "to copy blocks. Removed in 2027.5.0",
      "2026.11.0")
  virtual void draw_pixels_at(int x_start, int y_start, int w, int h, const uint8_t *ptr, ColorOrder order,
                              ColorBitness bitness, bool big_endian, int x_offset, int y_offset, int x_pad);
 
  // Remove before 2027.5.0
  ESPDEPRECATED("Pixels are always RGB, drop the ColorOrder argument. Removed in 2027.5.0", "2026.11.0")
  void draw_pixels_at(int x_start, int y_start, int w, int h, const uint8_t *ptr, ColorOrder order,
                      ColorBitness bitness, bool big_endian) {
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
    this->draw_pixels_at(x_start, y_start, w, h, ptr, order, bitness, big_endian, 0, 0, 0);
#pragma GCC diagnostic pop
  }
 
  void line(int x1, int y1, int x2, int y2, Color color = COLOR_ON);
 
  void line_at_angle(int x, int y, int angle, int length, Color color = COLOR_ON);
 
  void line_at_angle(int x, int y, int angle, int start_radius, int stop_radius, Color color = COLOR_ON);
 
  void horizontal_line(int x, int y, int width, Color color = COLOR_ON);
 
  void vertical_line(int x, int y, int height, Color color = COLOR_ON);
 
  void rectangle(int x1, int y1, int width, int height, Color color = COLOR_ON);
 
  void filled_rectangle(int x1, int y1, int width, int height, Color color = COLOR_ON);
 
  void circle(int center_x, int center_xy, int radius, Color color = COLOR_ON);
 
  void filled_circle(int center_x, int center_y, int radius, Color color = COLOR_ON);
 
  void filled_ring(int center_x, int center_y, int radius1, int radius2, Color color = COLOR_ON);
  void filled_gauge(int center_x, int center_y, int radius1, int radius2, int progress, Color color = COLOR_ON);
 
  void triangle(int x1, int y1, int x2, int y2, int x3, int y3, Color color = COLOR_ON);
 
  void filled_triangle(int x1, int y1, int x2, int y2, int x3, int y3, Color color = COLOR_ON);
 
  void get_regular_polygon_vertex(int vertex_id, int *vertex_x, int *vertex_y, int center_x, int center_y, int radius,
                                  int edges, RegularPolygonVariation variation = VARIATION_POINTY_TOP,
                                  float rotation_degrees = ROTATION_0_DEGREES);
 
  void regular_polygon(int x, int y, int radius, int edges, RegularPolygonVariation variation = VARIATION_POINTY_TOP,
                       float rotation_degrees = ROTATION_0_DEGREES, Color color = COLOR_ON,
                       RegularPolygonDrawing drawing = DRAWING_OUTLINE);
  void regular_polygon(int x, int y, int radius, int edges, RegularPolygonVariation variation, Color color,
                       RegularPolygonDrawing drawing = DRAWING_OUTLINE);
  void regular_polygon(int x, int y, int radius, int edges, Color color,
                       RegularPolygonDrawing drawing = DRAWING_OUTLINE);
 
  void filled_regular_polygon(int x, int y, int radius, int edges,
                              RegularPolygonVariation variation = VARIATION_POINTY_TOP,
                              float rotation_degrees = ROTATION_0_DEGREES, Color color = COLOR_ON);
  void filled_regular_polygon(int x, int y, int radius, int edges, RegularPolygonVariation variation, Color color);
  void filled_regular_polygon(int x, int y, int radius, int edges, Color color);
 
  void print(int x, int y, BaseFont *font, Color color, TextAlign align, const char *text,
             Color background = COLOR_OFF);
 
  void print(int x, int y, BaseFont *font, Color color, const char *text, Color background = COLOR_OFF);
 
  void print(int x, int y, BaseFont *font, TextAlign align, const char *text);
 
  void print(int x, int y, BaseFont *font, const char *text);
 
  void printf(int x, int y, BaseFont *font, Color color, Color background, TextAlign align, const char *format, ...)
      __attribute__((format(printf, 8, 9)));
 
  void printf(int x, int y, BaseFont *font, Color color, TextAlign align, const char *format, ...)
      __attribute__((format(printf, 7, 8)));
 
  void printf(int x, int y, BaseFont *font, Color color, const char *format, ...) __attribute__((format(printf, 6, 7)));
 
  void printf(int x, int y, BaseFont *font, TextAlign align, const char *format, ...)
      __attribute__((format(printf, 6, 7)));
 
  void printf(int x, int y, BaseFont *font, const char *format, ...) __attribute__((format(printf, 5, 6)));
 
  void strftime(int x, int y, BaseFont *font, Color color, Color background, TextAlign align, const char *format,
                ESPTime time) __attribute__((format(strftime, 8, 0)));
 
  void strftime(int x, int y, BaseFont *font, Color color, TextAlign align, const char *format, ESPTime time)
      __attribute__((format(strftime, 7, 0)));
 
  void strftime(int x, int y, BaseFont *font, Color color, const char *format, ESPTime time)
      __attribute__((format(strftime, 6, 0)));
 
  void strftime(int x, int y, BaseFont *font, TextAlign align, const char *format, ESPTime time)
      __attribute__((format(strftime, 6, 0)));
 
  void strftime(int x, int y, BaseFont *font, const char *format, ESPTime time) __attribute__((format(strftime, 5, 0)));
 
  void image(int x, int y, BaseImage *image, Color color_on = COLOR_ON, Color color_off = COLOR_OFF);
 
  void image(int x, int y, BaseImage *image, ImageAlign align, Color color_on = COLOR_ON, Color color_off = COLOR_OFF);
 
#ifdef USE_GRAPH
  void graph(int x, int y, graph::Graph *graph, Color color_on = COLOR_ON);
 
  void legend(int x, int y, graph::Graph *graph, Color color_on = COLOR_ON);
#endif  // USE_GRAPH
 
#ifdef USE_QR_CODE
  void qr_code(int x, int y, qr_code::QrCode *qr_code, Color color_on = COLOR_ON, int scale = 1);
#endif
 
#ifdef USE_GRAPHICAL_DISPLAY_MENU
  void menu(int x, int y, graphical_display_menu::GraphicalDisplayMenu *menu, int width, int height);
#endif  // USE_GRAPHICAL_DISPLAY_MENU
 
  void get_text_bounds(int x, int y, const char *text, BaseFont *font, TextAlign align, int *x1, int *y1, int *width,
                       int *height);
 
  void set_writer(display_writer_t &&writer);
 
  void show_page(DisplayPage *page);
  void show_next_page();
  void show_prev_page();
 
  void set_pages(std::vector<DisplayPage *> pages);
 
  const DisplayPage *get_active_page() const { return this->page_; }
 
#ifdef DISPLAY_PAGE_CHANGE_CALLBACK_COUNT
  template<typename F> void add_on_page_change_callback(F &&callback) {
    this->page_change_callback_.add(std::forward<F>(callback));
  }
#endif
 
  virtual void set_rotation(DisplayRotation rotation);
 
  // Internal method to set display auto clearing.
  void set_auto_clear(bool auto_clear_enabled) { this->auto_clear_enabled_ = auto_clear_enabled; }
 
  virtual DisplayRotation get_rotation() const { return this->rotation_; }
 
  virtual bool pixel_axes_swapped() const { return rotation_swaps_axes(this->rotation_); }
 
  virtual DisplayType get_display_type() = 0;
 
  void start_clipping(Rect rect);
  void start_clipping(int16_t left, int16_t top, int16_t right, int16_t bottom) {
    start_clipping(Rect(left, top, right - left, bottom - top));
  };
 
  void extend_clipping(Rect rect);
  void extend_clipping(int16_t left, int16_t top, int16_t right, int16_t bottom) {
    this->extend_clipping(Rect(left, top, right - left, bottom - top));
  };
 
  void shrink_clipping(Rect rect);
  void shrink_clipping(uint16_t left, uint16_t top, uint16_t right, uint16_t bottom) {
    this->shrink_clipping(Rect(left, top, right - left, bottom - top));
  };
 
  void end_clipping();
 
  Rect get_clipping() const;
 
  bool is_clipping() const { return !this->clipping_rectangle_.empty(); }
 
  bool ESPHOME_ALWAYS_INLINE is_point_clipped(int x, int y) const {
    return this->is_clipping() && !this->clipping_rectangle_.back().inside(x, y);
  }
 
  bool clip(int x, int y);
 
  void test_card();
  void show_test_card() { this->show_test_card_ = true; }
 
 protected:
  virtual void draw_pixels_internal(int x_start, int y_start, int w, int h, const uint8_t *ptr, ColorBitness bitness,
                                    bool big_endian, int x_offset, int y_offset, int x_pad);
  bool clamp_x_(int x, int w, int &min_x, int &max_x);
  bool clamp_y_(int y, int h, int &min_y, int &max_y);
  void vprintf_(int x, int y, BaseFont *font, Color color, Color background, TextAlign align, const char *format,
                va_list arg);
 
  void do_update_();
  void clear_clipping_();
 
  void ESPHOME_ALWAYS_INLINE feed_wdt_per_pixel_() {
    if (++this->wdt_pixel_counter_ == 0)
      this->feed_wdt_pixel_slow_();
  }
  void feed_wdt_pixel_slow_();
 
  virtual int get_height_internal() = 0;
  virtual int get_width_internal() = 0;
 
  void filled_flat_side_triangle_(int x1, int y1, int x2, int y2, int x3, int y3, Color color);
  void sort_triangle_points_by_y_(int *x1, int *y1, int *x2, int *y2, int *x3, int *y3);
 
  DisplayRotation rotation_{DISPLAY_ROTATION_0_DEGREES};
  display_writer_t writer_{};
  DisplayPage *page_{nullptr};
#ifdef DISPLAY_PAGE_CHANGE_CALLBACK_COUNT
  StaticCallbackManager<DISPLAY_PAGE_CHANGE_CALLBACK_COUNT, void(DisplayPage *, DisplayPage *)> page_change_callback_;
#endif
  bool auto_clear_enabled_{true};
  std::vector<Rect> clipping_rectangle_;
  uint8_t wdt_pixel_counter_{0};
  bool show_test_card_{false};
};
 
class DisplayPage final {
 public:
  DisplayPage(display_writer_t writer);
  void show();
  void show_next();
  void show_prev();
  void set_parent(Display *parent) { this->parent_ = parent; }
  void set_prev(DisplayPage *prev) { this->prev_ = prev; }
  void set_next(DisplayPage *next) { this->next_ = next; }
  const display_writer_t &get_writer() const;
 
 protected:
  Display *parent_;
  display_writer_t writer_;
  DisplayPage *prev_{nullptr};
  DisplayPage *next_{nullptr};
};
 
inline void Display::show_next_page() { this->page_->show_next(); }
inline void Display::show_prev_page() { this->page_->show_prev(); }
 
template<typename... Ts> class DisplayPageShowAction final : public Action<Ts...> {
 public:
  TEMPLATABLE_VALUE(DisplayPage *, page)
 
  void play(const Ts &...x) override {
    auto *page = this->page_.value(x...);
    if (page != nullptr) {
      page->show();
    }
  }
};
 
const LogString *text_align_to_string(TextAlign textalign);
 
}  // namespace esphome::display