Display Interface
API Reference
Generic Display Interface
- group display_interface
Display Interface.
- Since
1.14
- Version
0.8.0
Defines
-
DISPLAY_BITS_PER_PIXEL(fmt)
Bits required per pixel for display format.
This macro expands to the number of bits required for a given display format. It can be used to allocate a framebuffer based on a given display format type
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:
-
enum display_screen_info
Display screen information.
Values:
-
enumerator SCREEN_INFO_MONO_VTILED = BIT(0)
If selected, one octet represents 8 pixels ordered vertically, otherwise ordered horizontally.
-
enumerator SCREEN_INFO_MONO_VTILED = BIT(0)
-
enum display_orientation
Enumeration with possible display orientation.
Values:
-
enumerator DISPLAY_ORIENTATION_NORMAL
No rotation.
-
enumerator DISPLAY_ORIENTATION_ROTATED_90
Rotated 90 degrees clockwise.
-
enumerator DISPLAY_ORIENTATION_ROTATED_180
Rotated 180 degrees clockwise.
-
enumerator DISPLAY_ORIENTATION_ROTATED_270
Rotated 270 degrees clockwise.
-
enumerator DISPLAY_ORIENTATION_NORMAL
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
- Return values:
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
- Return values:
0 – on success else negative errno code.
-ENOSYS – if not implemented.
-
static inline void *display_get_framebuffer(const struct device *dev)
Get pointer to framebuffer for direct access.
- Parameters:
dev – Pointer to device structure
- Return values:
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
- Return values:
0 – on success else negative errno code.
-ENOSYS – if not implemented.
-
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
- Return values:
0 – on success else negative errno code.
-ENOSYS – if not implemented.
-
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
- Return values:
0 – on success else negative errno code.
-ENOSYS – if not implemented.
-
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
- Return values:
0 – on success else negative errno code.
-ENOSYS – if not implemented.
-
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
- Return values:
0 – on success else negative errno code.
-ENOSYS – if not implemented.
-
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
- Return values:
0 – on success else negative errno code.
-ENOSYS – if not implemented.
-
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.
-
uint16_t x_resolution
-
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.
Grove LCD Display
- group grove_display
Grove display APIs.
Defines
-
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 *dev, char *data, uint32_t size)
Send text to the screen.
- Parameters:
dev – 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 *dev, uint8_t col, uint8_t row)
Set text cursor position for next additions.
- Parameters:
dev – 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 *dev)
Clear the current display.
- Parameters:
dev – Pointer to device structure for driver instance.
-
void glcd_display_state_set(const struct device *dev, 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:
dev – Pointer to device structure for driver instance.
opt – An 8bit bitmask of GLCD_DS_* options.
-
uint8_t glcd_display_state_get(const struct device *dev)
return the display feature set associated with the device
- Parameters:
dev – 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 *dev, 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:
dev – Pointer to device structure for driver instance.
opt – A bitmask of GLCD_IS_* options
-
uint8_t glcd_input_state_get(const struct device *dev)
return the input set associated with the device
- Parameters:
dev – the Grove LCD to get the input features set
- Returns:
the input set associated with the device.
-
void glcd_function_set(const struct device *dev, 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:
dev – Pointer to device structure for driver instance.
opt – A bitmask of GLCD_FS_* options
-
uint8_t glcd_function_get(const struct device *dev)
return the function set associated with the device
- Parameters:
dev – the Grove LCD to get the functions set
- Returns:
the function features set associated with the device.
-
void glcd_color_select(const struct device *dev, uint8_t color)
Set LCD background to a predefined color.
- Parameters:
dev – Pointer to device structure for driver instance.
color – One of the predefined color options
-
void glcd_color_set(const struct device *dev, uint8_t r, uint8_t g, uint8_t b)
Set LCD background to custom RGB color value.
- Parameters:
dev – 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)
-
GLCD_DS_DISPLAY_ON
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_MODE_DEFAULT
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.
-
MB_IMAGE(_rows...)
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, const char *const 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_draw_text(const struct device *dev, const char *const str, int16_t x, int16_t y)
Print a string into the framebuffer.
For compare to cfb_print, cfb_draw_text accept non tile-aligned coords and not line wrapping.
- 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_draw_point(const struct device *dev, const struct cfb_position *pos)
Draw a point.
- Parameters:
dev – Pointer to device structure for driver instance
pos – position of the point
- Returns:
0 on success, negative value otherwise
-
int cfb_draw_line(const struct device *dev, const struct cfb_position *start, const struct cfb_position *end)
Draw a line.
- Parameters:
dev – Pointer to device structure for driver instance
start – start position of the line
end – end position of the line
- Returns:
0 on success, negative value otherwise
-
int cfb_draw_rect(const struct device *dev, const struct cfb_position *start, const struct cfb_position *end)
Draw a rectangle.
- Parameters:
dev – Pointer to device structure for driver instance
start – Top-Left position of the rectangle
end – Bottom-Right position of the rectangle
- 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_invert_area(const struct device *dev, uint16_t x, uint16_t y, uint16_t width, uint16_t height)
Invert Pixels in selected area.
- Parameters:
dev – Pointer to device structure for driver instance
x – Position in X direction of the beginning of area
y – Position in Y direction of the beginning of area
width – Width of area in pixels
height – Height of area in pixels
- 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_set_kerning(const struct device *dev, int8_t kerning)
Set font kerning (spacing between individual letters).
- Parameters:
dev – Pointer to device structure for driver instance
kerning – Font kerning
- 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
-
struct cfb_font
- #include <cfb.h>
-
struct cfb_position
- #include <cfb.h>
-
FONT_ENTRY_DEFINE(_name, _width, _height, _caps, _data, _fc, _lc)