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
¶
-
enumerator
PIXEL_FORMAT_MONO01
¶
-
enumerator
PIXEL_FORMAT_MONO10
¶
-
enumerator
PIXEL_FORMAT_ARGB_8888
¶
-
enumerator
PIXEL_FORMAT_RGB_565
¶
-
enumerator
PIXEL_FORMAT_BGR_565
¶
-
enumerator
-
enum
display_screen_info
¶ Values:
-
enumerator
SCREEN_INFO_MONO_VTILED
¶ If selected, one octet represents 8 pixels ordered vertically, otherwise ordered horizontally.
-
enumerator
SCREEN_INFO_MONO_MSB_FIRST
¶ If selected, the MSB represents the first pixel, otherwise MSB represents the last pixel.
-
enumerator
SCREEN_INFO_EPD
¶ Electrophoretic Display.
-
enumerator
SCREEN_INFO_DOUBLE_BUFFER
¶ Screen has two alternating ram buffers
-
enumerator
Functions
-
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 structurex
: x Coordinate of the upper left corner where to write the buffery
: y Coordinate of the upper left corner where to write the bufferdesc
: Pointer to a structure describing the buffer layoutbuf
: Pointer to buffer array
- Return Value
0
: on success else negative errno code.
-
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 structurex
: x Coordinate of the upper left corner where to read fromy
: y Coordinate of the upper left corner where to read fromdesc
: Pointer to a structure describing the buffer layoutbuf
: Pointer to buffer array
- Return Value
0
: on success else negative errno code.
-
void *
display_get_framebuffer
(const struct device *dev)¶ Get pointer to framebuffer for direct access.
- Parameters
dev
: Pointer to device structure
- Return Value
Pointer
: to frame buffer or NULL if direct framebuffer access is not supported
-
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
- Return Value
0
: on success else negative errno code.
-
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
- Return Value
0
: on success else negative errno code.
-
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 structurebrightness
: Brightness in steps of 1/256
- Return Value
0
: on success else negative errno code.
-
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 structurecontrast
: Contrast in steps of 1/256
- Return Value
0
: on success else negative errno code.
-
void
display_get_capabilities
(const struct device *dev, struct display_capabilities *capabilities)¶ Get display capabilities.
- Parameters
dev
: Pointer to device structurecapabilities
: Pointer to capabilities structure to populate
-
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 structurepixel_format
: Pixel format to be used by display
- Return Value
0
: on success else negative errno code.
-
int
display_set_orientation
(const struct device *dev, const enum display_orientation orientation)¶ Set display orientation.
- Parameters
dev
: Pointer to device structureorientation
: Orientation to be used by display
- Return Value
0
: on success else negative errno code.
Variables
-
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
-
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_capabilities
¶ - #include <display.h>
Structure holding display capabilities.
-
struct
display_buffer_descriptor
¶ - #include <display.h>
Structure to describe display data buffer layout.
-
struct
display_driver_api
¶ - #include <display.h>
Display driver API API which a display driver should expose.
-
typedef int (*
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_DS_BLINK_ON
¶
-
GLCD_DS_BLINK_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 displaysize
: 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
- Return
the display feature set associated with the device.
- Parameters
port
: the Grove LCD to get the display features set
-
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
- Return
the input set associated with the device.
- Parameters
port
: the Grove LCD to get the input features set
-
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
- Return
the function features set associated with the device.
- Parameters
port
: the Grove LCD to get the functions set
-
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)
-
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:
- Return
Image bitmap that can be passed e.g. to mb_display_image().
- Parameters
_rows
: Each of the 5 rows represented as a 5-value column array.
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
¶ Loop back to the beginning when reaching the last image.
-
enumerator
Functions
-
struct mb_display *
mb_display_get
(void)¶ Get a pointer to the BBC micro:bit display object.
- Return
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
Functions
-
int
cfb_print
(const struct device *dev, char *str, uint16_t x, uint16_t y)¶ Print a string into the framebuffer.
- Return
0 on success, negative value otherwise
- Parameters
dev
: Pointer to device structure for driver instancestr
: String to printx
: Position in X direction of the beginning of the stringy
: Position in Y direction of the beginning of the string
-
int
cfb_framebuffer_clear
(const struct device *dev, bool clear_display)¶ Clear framebuffer.
- Return
0 on success, negative value otherwise
- Parameters
dev
: Pointer to device structure for driver instanceclear_display
: Clear the display as well
-
int
cfb_framebuffer_invert
(const struct device *dev)¶ Invert Pixels.
- Return
0 on success, negative value otherwise
- Parameters
dev
: Pointer to device structure for driver instance
-
int
cfb_framebuffer_finalize
(const struct device *dev)¶ Finalize framebuffer and write it to display RAM, invert or reorder pixels if necessary.
- Return
0 on success, negative value otherwise
- Parameters
dev
: Pointer to device structure for driver instance
-
int
cfb_get_display_parameter
(const struct device *dev, enum cfb_display_param)¶ Get display parameter.
- Return
Display parameter value
- Parameters
dev
: Pointer to device structure for driver instancecfb_display_param
: One of the display parameters
-
int
cfb_framebuffer_set_font
(const struct device *dev, uint8_t idx)¶ Set font.
- Return
0 on success, negative value otherwise
- Parameters
dev
: Pointer to device structure for driver instanceidx
: Font index
-
int
cfb_get_font_size
(const struct device *dev, uint8_t idx, uint8_t *width, uint8_t *height)¶ Get font size.
- Return
0 on success, negative value otherwise
- Parameters
dev
: Pointer to device structure for driver instanceidx
: Font indexwidth
: Pointers to the variable where the font width will be stored.height
: Pointers to the variable where the font height will be stored.
-
struct
cfb_font
¶ - #include <cfb.h>
-