# Display¶

## API Reference¶

### DisplayBuffer¶

class DisplayBuffer

Subclassed by display::SSD1306, display::WaveshareEPaper

Public Functions

void fill(int color)

Fill the entire screen with the given color.

void clear()

Clear the entire screen by filling it with OFF pixels.

int get_width()

Get the width of the image in pixels with rotation applied.

int get_height()

Get the height of the image in pixels with rotation applied.

void draw_pixel_at(int x, int y, int color = COLOR_ON)

Set a single pixel at the specified coordinates to the given color.

void line(int x1, int y1, int x2, int y2, int color = COLOR_ON)

Draw a straight line from the point [x1,y1] to [x2,y2] with the given color.

void horizontal_line(int x, int y, int width, int color = COLOR_ON)

Draw a horizontal line from the point [x,y] to [x+width,y] with the given color.

void vertical_line(int x, int y, int height, int color = COLOR_ON)

Draw a vertical line from the point [x,y] to [x,y+width] with the given color.

void rectangle(int x1, int y1, int width, int height, int color = COLOR_ON)

Draw the outline of a rectangle with the top left point at [x1,y1] and the bottom right point at [x1+width,y1+height].

void filled_rectangle(int x1, int y1, int width, int height, int color = COLOR_ON)

Fill a rectangle with the top left point at [x1,y1] and the bottom right point at [x1+width,y1+height].

void circle(int center_x, int center_xy, int radius, int color = COLOR_ON)

Draw the outline of a circle centered around [center_x,center_y] with the radius radius with the given color.

void filled_circle(int center_x, int center_y, int radius, int color = COLOR_ON)

Fill a circle centered around [center_x,center_y] with the radius radius with the given color.

void print(int x, int y, Font *font, int color, TextAlign align, const char *text)

Print text with the anchor point at [x,y] with font.

Parameters
• x: The x coordinate of the text alignment anchor point.
• y: The y coordinate of the text alignment anchor point.
• font: The font to draw the text with.
• color: The color to draw the text with.
• align: The alignment of the text.
• text: The text to draw.

void print(int x, int y, Font *font, int color, const char *text)

Print text with the top left at [x,y] with font.

Parameters
• x: The x coordinate of the upper left corner.
• y: The y coordinate of the upper left corner.
• font: The font to draw the text with.
• color: The color to draw the text with.
• text: The text to draw.

void print(int x, int y, Font *font, TextAlign align, const char *text)

Print text with the anchor point at [x,y] with font.

Parameters
• x: The x coordinate of the text alignment anchor point.
• y: The y coordinate of the text alignment anchor point.
• font: The font to draw the text with.
• align: The alignment of the text.
• text: The text to draw.

void print(int x, int y, Font *font, const char *text)

Print text with the top left at [x,y] with font.

Parameters
• x: The x coordinate of the upper left corner.
• y: The y coordinate of the upper left corner.
• font: The font to draw the text with.
• text: The text to draw.

void printf(int x, int y, Font *font, int color, TextAlign align, const char *format, ...)

Evaluate the printf-format format and print the result with the anchor point at [x,y] with font.

Parameters
• x: The x coordinate of the text alignment anchor point.
• y: The y coordinate of the text alignment anchor point.
• font: The font to draw the text with.
• color: The color to draw the text with.
• align: The alignment of the text.
• format: The format to use.
• ...: The arguments to use for the text formatting.

void printf(int x, int y, Font *font, int color, const char *format, ...)

Evaluate the printf-format format and print the result with the top left at [x,y] with font.

Parameters
• x: The x coordinate of the upper left corner.
• y: The y coordinate of the upper left corner.
• font: The font to draw the text with.
• color: The color to draw the text with.
• format: The format to use.
• ...: The arguments to use for the text formatting.

void printf(int x, int y, Font *font, TextAlign align, const char *format, ...)

Evaluate the printf-format format and print the result with the anchor point at [x,y] with font.

Parameters
• x: The x coordinate of the text alignment anchor point.
• y: The y coordinate of the text alignment anchor point.
• font: The font to draw the text with.
• align: The alignment of the text.
• format: The format to use.
• ...: The arguments to use for the text formatting.

void printf(int x, int y, Font *font, const char *format, ...)

Evaluate the printf-format format and print the result with the top left at [x,y] with font.

Parameters
• x: The x coordinate of the upper left corner.
• y: The y coordinate of the upper left corner.
• font: The font to draw the text with.
• format: The format to use.
• ...: The arguments to use for the text formatting.

void strftime(int x, int y, Font *font, int color, TextAlign align, const char *format, time::EsphomelibTime time)

Evaluate the strftime-format format and print the result with the anchor point at [x,y] with font.

Parameters
• x: The x coordinate of the text alignment anchor point.
• y: The y coordinate of the text alignment anchor point.
• font: The font to draw the text with.
• color: The color to draw the text with.
• align: The alignment of the text.
• format: The strftime format to use.
• time: The time to format.

void strftime(int x, int y, Font *font, int color, const char *format, time::EsphomelibTime time)

Evaluate the strftime-format format and print the result with the top left at [x,y] with font.

Parameters
• x: The x coordinate of the upper left corner.
• y: The y coordinate of the upper left corner.
• font: The font to draw the text with.
• color: The color to draw the text with.
• format: The strftime format to use.
• time: The time to format.

void strftime(int x, int y, Font *font, TextAlign align, const char *format, time::EsphomelibTime time)

Evaluate the strftime-format format and print the result with the anchor point at [x,y] with font.

Parameters
• x: The x coordinate of the text alignment anchor point.
• y: The y coordinate of the text alignment anchor point.
• font: The font to draw the text with.
• align: The alignment of the text.
• format: The strftime format to use.
• time: The time to format.

void strftime(int x, int y, Font *font, const char *format, time::EsphomelibTime time)

Evaluate the strftime-format format and print the result with the top left at [x,y] with font.

Parameters
• x: The x coordinate of the upper left corner.
• y: The y coordinate of the upper left corner.
• font: The font to draw the text with.
• format: The strftime format to use.
• time: The time to format.

void image(int x, int y, Image *image)

Draw the image with the top-left corner at [x,y] to the screen.

void get_text_bounds(int x, int y, const char *text, Font *font, TextAlign align, int *x1, int *y1, int *width, int *height)

Get the text bounds of the given string.

Parameters
• x: The x coordinate to place the string at, can be 0 if only interested in dimensions.
• y: The y coordinate to place the string at, can be 0 if only interested in dimensions.
• text: The text to measure.
• font: The font to measure the text bounds with.
• align: The alignment of the text. Set to TextAlign::TOP_LEFT if only interested in dimensions.
• x1: A pointer to store the returned x coordinate of the upper left corner in.
• y1: A pointer to store the returned y coordinate of the upper left corner in.
• width: A pointer to store the returned text width in.
• height: A pointer to store the returned text height in.

void set_writer(display_writer_t &&writer)

Internal method to set the display writer lambda.

void set_rotation(DisplayRotation rotation)

Internal method to set the display rotation with.

Protected Functions

void vprintf_(int x, int y, Font *font, int color, TextAlign align, const char *format, va_list arg)
virtual void draw_absolute_pixel_internal_(int x, int y, int color) = 0
virtual int get_height_internal_() = 0
virtual int get_width_internal_() = 0
void init_internal_(uint32_t buffer_length)
void do_update()

Protected Attributes

uint8_t *buffer_ = {nullptr}
DisplayRotation rotation_ = {DISPLAY_ROTATION_0_DEGREES}
optional<display_writer_t> writer_ = {}
const uint8_t COLOR_OFF

Turn the pixel OFF.

const uint8_t COLOR_ON

Turn the pixel ON.

### TextAlign¶

enum TextAlign

TextAlign is used to tell the display class how to position a piece of text.

By default the coordinates you enter for the print*() functions take the upper left corner of the text as the “anchor” point. You can customize this behavior to, for example, make the coordinates refer to the center of the text.

All text alignments consist of an X and Y-coordinate alignment. For the alignment along the X-axis these options are allowed:

• LEFT (x-coordinate of anchor point is on left)
• CENTER_HORIZONTAL (x-coordinate of anchor point is in the horizontal center of the text)
• RIGHT (x-coordinate of anchor point is on right)

For the Y-Axis alignment these options are allowed:

• TOP (y-coordinate of anchor is on the top of the text)
• CENTER_VERTICAL (y-coordinate of anchor is in the vertical center of the text)
• BASELINE (y-coordinate of anchor is on the baseline of the text)
• BOTTOM (y-coordinate of anchor is on the bottom of the text)

These options are then combined to create combined TextAlignment options like:

• TOP_LEFT (default)
• CENTER (anchor point is in the middle of the text bounds)

Values:

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

### Font¶

class Font

Public Functions

Font(std::vector<Glyph> &&glyphs, int baseline, int bottom)

Construct the font with the given glyphs.

Parameters
• glyphs: A vector of glyphs, must be sorted lexicographically.
• baseline: The y-offset from the top of the text to the baseline.
• bottom: The y-offset from the top of the text to the bottom (i.e. height).

int match_next_glyph(const char *str, int *match_length)
void measure(const char *str, int *width, int *x_offset, int *baseline, int *height)
const std::vector<Glyph> &get_glyphs() const

Protected Attributes

std::vector<Glyph> glyphs_
int baseline_
int bottom_
class Glyph

Public Functions

Glyph(const char *aChar, const uint8_t *data_start, uint32_t offset, int offset_x, int offset_y, int width, int height)
bool get_pixel(int x, int y) const
const char *get_char() const
bool compare_to(const char *str) const
int match_length(const char *str) const
void scan_area(int *x1, int *y1, int *width, int *height) const

Protected Attributes

friend display::Glyph::Font
friend display::Glyph::DisplayBuffer
const char *char_
const uint8_t *data_
int offset_x
int offset_y
int width_
int height_

### Image¶

class Image

Public Functions

Image(const uint8_t *data_start, int width, int height)
bool get_pixel(int x, int y) const
int get_width() const
int get_height() const

Protected Attributes

int width_
int height_
const uint8_t *data_start_

### DisplayRotation¶

enum display::DisplayRotation

Values:

DISPLAY_ROTATION_0_DEGREES = 0
DISPLAY_ROTATION_90_DEGREES
DISPLAY_ROTATION_180_DEGREES
DISPLAY_ROTATION_270_DEGREES