This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Display Interface

API Reference

Generic Display Interface

group display_interface

Display Interface.

Typedefs

typedef int (*display_blanking_on_api)(const struct device *dev)

Callback API to turn on display blanking See display_blanking_on() for argument description.

typedef int (*display_blanking_off_api)(const struct device *dev)

Callback API to turn off display blanking See display_blanking_off() for argument description.

typedef int (*display_write_api)(const struct device *dev, const uint16_t x, const uint16_t y, const struct display_buffer_descriptor *desc, const void *buf)

Callback API for writing data to the display See display_write() for argument description.

typedef int (*display_read_api)(const struct device *dev, const uint16_t x, const uint16_t y, const struct display_buffer_descriptor *desc, void *buf)

Callback API for reading data from the display See display_read() for argument description.

typedef void *(*display_get_framebuffer_api)(const struct device *dev)

Callback API to get framebuffer pointer See display_get_framebuffer() for argument description.

typedef int (*display_set_brightness_api)(const struct device *dev, const uint8_t brightness)

Callback API to set display brightness See display_set_brightness() for argument description.

typedef int (*display_set_contrast_api)(const struct device *dev, const uint8_t contrast)

Callback API to set display contrast See display_set_contrast() for argument description.

typedef void (*display_get_capabilities_api)(const struct device *dev, struct display_capabilities *capabilities)

Callback API to get display capabilities See display_get_capabilities() for argument description.

typedef int (*display_set_pixel_format_api)(const struct device *dev, const enum display_pixel_format pixel_format)

Callback API to set pixel format used by the display See display_set_pixel_format() for argument description.

typedef int (*display_set_orientation_api)(const struct device *dev, const enum display_orientation orientation)

Callback API to set orientation used by the display See display_set_orientation() for argument description.

Enums

enum display_pixel_format

Display pixel formats.

Display pixel format enumeration.

In case a pixel format consists out of multiple bytes the byte order is big endian.

Values:

enumerator PIXEL_FORMAT_RGB_888 = BIT(0)
enumerator PIXEL_FORMAT_MONO01 = BIT(1)
enumerator PIXEL_FORMAT_MONO10 = BIT(2)
enumerator PIXEL_FORMAT_ARGB_8888 = BIT(3)
enumerator PIXEL_FORMAT_RGB_565 = BIT(4)
enumerator PIXEL_FORMAT_BGR_565 = BIT(5)
enum display_screen_info

Values:

enumerator SCREEN_INFO_MONO_VTILED = BIT(0)

If selected, one octet represents 8 pixels ordered vertically, otherwise ordered horizontally.

enumerator SCREEN_INFO_MONO_MSB_FIRST = BIT(1)

If selected, the MSB represents the first pixel, otherwise MSB represents the last pixel.

enumerator SCREEN_INFO_EPD = BIT(2)

Electrophoretic Display.

enumerator SCREEN_INFO_DOUBLE_BUFFER = BIT(3)

Screen has two alternating ram buffers

enumerator SCREEN_INFO_X_ALIGNMENT_WIDTH = BIT(4)

Screen has x alignment constrained to width.

enum display_orientation

Enumeration with possible display orientation.

Values:

enumerator DISPLAY_ORIENTATION_NORMAL
enumerator DISPLAY_ORIENTATION_ROTATED_90
enumerator DISPLAY_ORIENTATION_ROTATED_180
enumerator DISPLAY_ORIENTATION_ROTATED_270

Functions

static inline int display_write(const struct device *dev, const uint16_t x, const uint16_t y, const struct display_buffer_descriptor *desc, const void *buf)

Write data to display.

Parameters

  • dev – Pointer to device structure

  • x – x Coordinate of the upper left corner where to write the buffer

  • y – y Coordinate of the upper left corner where to write the buffer

  • desc – Pointer to a structure describing the buffer layout

  • buf – Pointer to buffer array

Returns

0 – on success else negative errno code.

static inline int display_read(const struct device *dev, const uint16_t x, const uint16_t y, const struct display_buffer_descriptor *desc, void *buf)

Read data from display.

Parameters

  • dev – Pointer to device structure

  • x – x Coordinate of the upper left corner where to read from

  • y – y Coordinate of the upper left corner where to read from

  • desc – Pointer to a structure describing the buffer layout

  • buf – Pointer to buffer array

Returns

0 – on success else negative errno code.

static inline void *display_get_framebuffer(const struct device *dev)

Get pointer to framebuffer for direct access.

Parameters

  • dev – Pointer to device structure

Returns

Pointer – to frame buffer or NULL if direct framebuffer access is not supported

static inline int display_blanking_on(const struct device *dev)

Turn display blanking on.

This function blanks the complete display. The content of the frame buffer will be retained while blanking is enabled and the frame buffer will be accessible for read and write operations.

In case backlight control is supported by the driver the backlight is turned off. The backlight configuration is retained and accessible for configuration.

In case the driver supports display blanking the initial state of the driver would be the same as if this function was called.

Parameters

  • dev – Pointer to device structure

Returns

0 – on success else negative errno code.

static inline int display_blanking_off(const struct device *dev)

Turn display blanking off.

Restore the frame buffer content to the display. In case backlight control is supported by the driver the backlight configuration is restored.

Parameters

  • dev – Pointer to device structure

Returns

0 – on success else negative errno code.

static inline int display_set_brightness(const struct device *dev, uint8_t brightness)

Set the brightness of the display.

Set the brightness of the display in steps of 1/256, where 255 is full brightness and 0 is minimal.

Parameters

  • dev – Pointer to device structure

  • brightness – Brightness in steps of 1/256

Returns

0 – on success else negative errno code.

static inline int display_set_contrast(const struct device *dev, uint8_t contrast)

Set the contrast of the display.

Set the contrast of the display in steps of 1/256, where 255 is maximum difference and 0 is minimal.

Parameters

  • dev – Pointer to device structure

  • contrast – Contrast in steps of 1/256

Returns

0 – on success else negative errno code.

static inline void display_get_capabilities(const struct device *dev, struct display_capabilities *capabilities)

Get display capabilities.

Parameters

  • dev – Pointer to device structure

  • capabilities – Pointer to capabilities structure to populate

static inline int display_set_pixel_format(const struct device *dev, const enum display_pixel_format pixel_format)

Set pixel format used by the display.

Parameters

  • dev – Pointer to device structure

  • pixel_format – Pixel format to be used by display

Returns

0 – on success else negative errno code.

static inline int display_set_orientation(const struct device *dev, const enum display_orientation orientation)

Set display orientation.

Parameters

  • dev – Pointer to device structure

  • orientation – Orientation to be used by display

Returns

0 – on success else negative errno code.

struct display_capabilities
#include <display.h>

Structure holding display capabilities.

Public Members

uint16_t x_resolution

Display resolution in the X direction

uint16_t y_resolution

Display resolution in the Y direction

uint32_t supported_pixel_formats

Bitwise or of pixel formats supported by the display

uint32_t screen_info

Information about display panel

enum display_pixel_format current_pixel_format

Currently active pixel format for the display

enum display_orientation current_orientation

Current display orientation

struct display_buffer_descriptor
#include <display.h>

Structure to describe display data buffer layout.

Public Members

uint32_t buf_size

Data buffer size in bytes

uint16_t width

Data buffer row width in pixels

uint16_t height

Data buffer column height in pixels

uint16_t pitch

Number of pixels between consecutive rows in the data buffer

struct display_driver_api
#include <display.h>

Display driver API API which a display driver should expose.

Grove LCD Display

group grove_display

Grove display APIs.

Defines

GROVE_LCD_NAME
GLCD_DS_DISPLAY_ON
GLCD_DS_DISPLAY_OFF
GLCD_DS_CURSOR_ON
GLCD_DS_CURSOR_OFF
GLCD_IS_SHIFT_INCREMENT
GLCD_IS_SHIFT_DECREMENT
GLCD_IS_ENTRY_LEFT
GLCD_IS_ENTRY_RIGHT
GLCD_FS_8BIT_MODE
GLCD_FS_ROWS_2
GLCD_FS_ROWS_1
GLCD_FS_DOT_SIZE_BIG
GLCD_FS_DOT_SIZE_LITTLE
GROVE_RGB_WHITE
GROVE_RGB_RED
GROVE_RGB_GREEN
GROVE_RGB_BLUE

Functions

void glcd_print(const struct device *port, char *data, uint32_t size)

Send text to the screen.

Parameters

  • port – Pointer to device structure for driver instance.

  • data – the ASCII text to display

  • size – the length of the text in bytes

void glcd_cursor_pos_set(const struct device *port, uint8_t col, uint8_t row)

Set text cursor position for next additions.

Parameters

  • port – Pointer to device structure for driver instance.

  • col – the column for the cursor to be moved to (0-15)

  • row – the row it should be moved to (0 or 1)

void glcd_clear(const struct device *port)

Clear the current display.

Parameters

  • port – Pointer to device structure for driver instance.

void glcd_display_state_set(const struct device *port, uint8_t opt)

Function to change the display state.

This function provides the user the ability to change the state of the display as per needed. Controlling things like powering on or off the screen, the option to display the cursor or not, and the ability to blink the cursor.

Parameters

  • port – Pointer to device structure for driver instance.

  • opt – An 8bit bitmask of GLCD_DS_* options.

uint8_t glcd_display_state_get(const struct device *port)

return the display feature set associated with the device

Parameters

  • port – the Grove LCD to get the display features set

Returns

the display feature set associated with the device.

void glcd_input_state_set(const struct device *port, uint8_t opt)

Function to change the input state.

This function provides the user the ability to change the state of the text input. Controlling things like text entry from the left or right side, and how far to increment on new text

Parameters

  • port – Pointer to device structure for driver instance.

  • opt – A bitmask of GLCD_IS_* options

uint8_t glcd_input_state_get(const struct device *port)

return the input set associated with the device

Parameters

  • port – the Grove LCD to get the input features set

Returns

the input set associated with the device.

void glcd_function_set(const struct device *port, uint8_t opt)

Function to set the functional state of the display.

This function provides the user the ability to change the state of the display as per needed. Controlling things like the number of rows, dot size, and text display quality.

Parameters

  • port – Pointer to device structure for driver instance.

  • opt – A bitmask of GLCD_FS_* options

uint8_t glcd_function_get(const struct device *port)

return the function set associated with the device

Parameters

  • port – the Grove LCD to get the functions set

Returns

the function features set associated with the device.

void glcd_color_select(const struct device *port, uint8_t color)

Set LCD background to a predefined color.

Parameters

  • port – Pointer to device structure for driver instance.

  • color – One of the predefined color options

void glcd_color_set(const struct device *port, uint8_t r, uint8_t g, uint8_t b)

Set LCD background to custom RGB color value.

Parameters

  • port – Pointer to device structure for driver instance.

  • r – A numeric value for the red color (max is 255)

  • g – A numeric value for the green color (max is 255)

  • b – A numeric value for the blue color (max is 255)

int glcd_initialize(const struct device *port)

Initialize the Grove LCD panel.

Parameters

  • port – Pointer to device structure for driver instance.

Returns

Returns 0 if all passes

BBC micro:bit Display

group mb_display

BBC micro:bit display APIs.

Defines

MB_IMAGE(_rows…)

Generate an image object from a given array rows/columns.

This helper takes an array of 5 rows, each consisting of 5 0/1 values which correspond to the columns of that row. The value 0 means the pixel is disabled whereas a 1 means the pixel is enabled.

The pixels go from left to right and top to bottom, i.e. top-left corner is the first row’s first value, top-right is the first rows last value, and bottom-right corner is the last value of the last (5th) row. As an example, the following would create a smiley face image:

Parameters

  • _rows – Each of the 5 rows represented as a 5-value column array.

Returns

Image bitmap that can be passed e.g. to mb_display_image().

Enums

enum mb_display_mode

Display mode.

First 16 bits are reserved for modes, last 16 for flags.

Values:

enumerator MB_DISPLAY_MODE_DEFAULT

Default mode (“single” for images, “scroll” for text).

enumerator MB_DISPLAY_MODE_SINGLE

Display images sequentially, one at a time.

enumerator MB_DISPLAY_MODE_SCROLL

Display images by scrolling.

enumerator MB_DISPLAY_FLAG_LOOP = BIT(16)

Loop back to the beginning when reaching the last image.

Functions

struct mb_display *mb_display_get(void)

Get a pointer to the BBC micro:bit display object.

Returns

Pointer to display object.

void mb_display_image(struct mb_display *disp, uint32_t mode, int32_t duration, const struct mb_image *img, uint8_t img_count)

Display one or more images on the BBC micro:bit LED display.

This function takes an array of one or more images and renders them sequentially on the micro:bit display. The call is asynchronous, i.e. the processing of the display happens in the background. If there is another image being displayed it will be canceled and the new one takes over.

Parameters

  • disp – Display object.

  • mode – One of the MB_DISPLAY_MODE_* options.

  • duration – Duration how long to show each image (in milliseconds), or SYS_FOREVER_MS.

  • img – Array of image bitmaps (struct mb_image objects).

  • img_count – Number of images in ‘img’ array.

void mb_display_print(struct mb_display *disp, uint32_t mode, int32_t duration, const char *fmt, ...)

Print a string of characters on the BBC micro:bit LED display.

This function takes a printf-style format string and outputs it in a scrolling fashion to the display.

The call is asynchronous, i.e. the processing of the display happens in the background. If there is another image or string being displayed it will be canceled and the new one takes over.

Parameters

  • disp – Display object.

  • mode – One of the MB_DISPLAY_MODE_* options.

  • duration – Duration how long to show each character (in milliseconds), or SYS_FOREVER_MS.

  • fmt – printf-style format string

  • ... – Optional list of format arguments.

void mb_display_stop(struct mb_display *disp)

Stop the ongoing display of an image.

Parameters

  • disp – Display object.

struct mb_image
#include <mb_display.h>

Representation of a BBC micro:bit display image.

This struct should normally not be used directly, rather created using the MB_IMAGE() macro.

Monochrome Character Framebuffer

group monochrome_character_framebuffer

Public Monochrome Character Framebuffer API.

Defines

FONT_ENTRY_DEFINE(_name, _width, _height, _caps, _data, _fc, _lc)

Macro for creating a font entry.

Parameters

  • _name – Name of the font entry.

  • _width – Width of the font in pixels

  • _height – Height of the font in pixels.

  • _caps – Font capabilities.

  • _data – Raw data of the font.

  • _fc – Character mapped to first font element.

  • _lc – Character mapped to last font element.

Enums

enum cfb_display_param

Values:

enumerator CFB_DISPLAY_HEIGH = 0
enumerator CFB_DISPLAY_WIDTH
enumerator CFB_DISPLAY_PPT
enumerator CFB_DISPLAY_ROWS
enumerator CFB_DISPLAY_COLS
enum cfb_font_caps

Values:

enumerator CFB_FONT_MONO_VPACKED = BIT(0)
enumerator CFB_FONT_MONO_HPACKED = BIT(1)
enumerator CFB_FONT_MSB_FIRST = BIT(2)

Functions

int cfb_print(const struct device *dev, char *str, uint16_t x, uint16_t y)

Print a string into the framebuffer.

Parameters

  • dev – Pointer to device structure for driver instance

  • str – String to print

  • x – Position in X direction of the beginning of the string

  • y – Position in Y direction of the beginning of the string

Returns

0 on success, negative value otherwise

int cfb_framebuffer_clear(const struct device *dev, bool clear_display)

Clear framebuffer.

Parameters

  • dev – Pointer to device structure for driver instance

  • clear_display – Clear the display as well

Returns

0 on success, negative value otherwise

int cfb_framebuffer_invert(const struct device *dev)

Invert Pixels.

Parameters

  • dev – Pointer to device structure for driver instance

Returns

0 on success, negative value otherwise

int cfb_framebuffer_finalize(const struct device *dev)

Finalize framebuffer and write it to display RAM, invert or reorder pixels if necessary.

Parameters

  • dev – Pointer to device structure for driver instance

Returns

0 on success, negative value otherwise

int cfb_get_display_parameter(const struct device *dev, enum cfb_display_param)

Get display parameter.

Parameters

  • dev – Pointer to device structure for driver instance

  • cfb_display_param – One of the display parameters

Returns

Display parameter value

int cfb_framebuffer_set_font(const struct device *dev, uint8_t idx)

Set font.

Parameters

  • dev – Pointer to device structure for driver instance

  • idx – Font index

Returns

0 on success, negative value otherwise

int cfb_get_font_size(const struct device *dev, uint8_t idx, uint8_t *width, uint8_t *height)

Get font size.

Parameters

  • dev – Pointer to device structure for driver instance

  • idx – Font index

  • width – Pointers to the variable where the font width will be stored.

  • height – Pointers to the variable where the font height will be stored.

Returns

0 on success, negative value otherwise

int cfb_get_numof_fonts(const struct device *dev)

Get number of fonts.

Parameters

  • dev – Pointer to device structure for driver instance

Returns

number of fonts

int cfb_framebuffer_init(const struct device *dev)

Initialize Character Framebuffer.

Parameters

  • dev – Pointer to device structure for driver instance

Returns

0 on success, negative value otherwise

struct cfb_font
#include <cfb.h>