Interface

Display drivers implement the interface display_struct defined here.

#include <eglib/display.h>

Types

enum display_line_direction_t

Line direction to draw.

DISPLAY_LINE_DIRECTION_RIGHT

Right: x increments.

DISPLAY_LINE_DIRECTION_LEFT

Right: x decrements.

DISPLAY_LINE_DIRECTION_DOWN

Right: y increments.

DISPLAY_LINE_DIRECTION_UP

Right: y decrements.

struct display_comm_struct

Communication bus configuration required by the display.

Buses not supported by the display can be set to NULL.

hal_four_wire_spi_config_t * four_wire_spi

4-Wire SPI

hal_i2c_config_t * i2c

I2C

hal_parallel_8_bit_8080_config_t * parallel_8_bit_8080

Parallel 8-bit 8080

Display driver

struct display_struct

Display driver definition.

Communication with the data bus can be done using the display driver HAL interface functions

Note

eglib_GetDisplayConfig() can be used to retrieve the HAL driver configuration.

Aliased as display_t.

struct display_comm_struct comm

Communication bus configuration required by the display.

void (*)(eglib_t *) init

Pointer to a function that initializes the display based on the driver configuration (eglib_GetDisplayConfig()).

It must initialize the display memory to all black pixels.

void (*)(eglib_t *) sleep_in

Pointer to a function that puts the display in sleep mode.

void (*)(eglib_t *) sleep_out

Pointer to a function that puts the display out of sleep mode.

void (*)(eglib_t *, coordinate_t *, coordinate_t *) get_dimension

Pointer to a function that returns the display dimensions:

Parameters

  • eglib – eglib_t handle.

  • width – Pointer where to write display width to.

  • height – Pointer where to write display height to.

Returns

void.

void (*)(eglib_t *, enum pixel_format_t *) get_pixel_format

Pointer to a function that returns the pixel format used in-memory by the display.

This is used by the frame buffer (eglib_Init_FrameBuffer) to decide how to write pixels to the buffer, which will then be handled by the send_buffer function from display_struct.

Parameters
Returns

pixel_format_t.

void (*)(eglib_t *, coordinate_t, coordinate_t, color_t) draw_pixel_color

Pointer to a function that that draws directly to the display memory at (x, y) using given color.

Some displays can not support this method. Eg: black and white displays, where each bit is a pixel, requires reading a whole byte from the display memory, changing the required bit and sending it back to the display memory. As Eglib does not support reading the display memory, such displays must implement this as an empty function: eglib_Init_FrameBuffer can be used to interface with the display using a frame buffer.

Parameters
void (*)(eglib_t *, coordinate_t, coordinate_t, enum display_line_direction_t, coordinate_t, color_t (*)(eglib_t *)) draw_line

Pointer to a function that draws a line directly to the display memory.

This is meant to be an accelerator for drawing lines for displays that support auto increment/decrement of the memory address written.

A typical implementation should roughly look like:

eglib_CommBegin(eglib);
switch(direction) {
    case DISPLAY_LINE_DIRECTION_RIGHT:
        set_display_memory_address_auto_increment_x(eglib);
        break;
    case DISPLAY_LINE_DIRECTION_LEFT:
        set_display_memory_address_auto_decrement_x(eglib);
        break;
    case DISPLAY_LINE_DIRECTION_DOWN:
        set_display_memory_address_auto_increment_y(eglib);
        break;
    case DISPLAY_LINE_DIRECTION_UP:
        set_display_memory_address_auto_decrement_y(eglib);
        break;
}
set_display_memory_address(eglib, x, y);
while(length--)
    send_pixel_to_memory(eglib, get_next_color(eglib));
eglib_CommEnd(eglib);

For displays that do not support auto increment/decrement of x/y (for all or some cases) the implementation can be set to display_default_draw_line().

Parameters

  • eglib – eglib_t handle.

  • x – line x start.

  • y – line y start.

  • direction – Line enum display_line_direction_t (right, left, down up).

  • length – Line length in pixels.

  • get_next_color – Pointer to a function that must be called for each line pixel to get its color.

void (*)(eglib_t *, void *, coordinate_t, coordinate_t, coordinate_t, coordinate_t) send_buffer

Pointer to a function that sends given buffer to display memory.

Parameters

  • eglib – eglib_t handle.

  • buffer – Pointer to the memory buffer to be sent. The format is dependent on both pixel_format_t from get_pixel_format and the display dimensions from get_dimension.

  • x – X coordinate_t of data to be sent: X pixels lower than x must not be sent to the display.

  • y – Y coordinate_t of data to be sent: Y pixels lower than y must not be sent to the display.

  • width – Width of data to be sent: X pixels greater than x + width must not be sent to the display.

  • height – Height of data to be sent: Y pixels greater than y + height must not be sent to the display.

_Bool (*)(eglib_t *) refresh

Pointer to a function that refreshes the display image.

This method is only relevant to displays such as e-ink / e-paper, where writing to the display memory (draw_pixel_color / send_buffer) does not affect the displayed image: it needs to be sent a refresh command to do so. Other displays (eg: LCD, OLED) can implement this function with an empty body returning false.

A typical implementation of this function will issue the refresh command to the display when first called and then poll the busy data line to return true when refresh is ongoing and false when refresh finished:

if(eglib_IsRefreshing(eglib)) {
        return eglib_GetBusy(eglib);
} else {
        send_refresh_command_to_display(eglib);
        return true;
}

eglib_IsRefreshing() queries the current state of refresh (that eglib keeps track) and eglib_GetBusy() can be used no read the state of the busy data line.

User code can then refresh the display with:

while(eglib_Refresh(eglib));
Parameters
Returns

true when refresh is ongoing and false when refresh finished.

Display Driver Helper Functions

void display_default_draw_line(eglib_t * eglib, coordinate_t x, coordinate_t y, enum display_line_direction_t direction, coordinate_t length, color_t (*)(eglib_t *) get_next_color)

Not accelerated implementation of display_struct draw_line based on draw_pixel_color.

eglib_GetDisplayConfig(eglib)

Returns a pointer to the display driver configuration that was passed to eglib_Init().

HAL Driver Helper Functions

These functions are used by HAL Drivers to interface with the HAL definitions display_comm_struct from the display driver display_struct.

eglib_GetHalFourWireSpiConfigComm(eglib)

Returns hal_four_wire_spi_config_t for display_struct from given eglib_t.

eglib_GetHalI2cConfigComm(eglib)

Returns hal_i2c_config_t for display_struct from given eglib_t.

eglib_GetHalParallel8bit8080ConfigComm(eglib)

Returns hal_parallel_8_bit_8080_t for display_struct from given eglib_t.

eglib_GetI2c7bitSlaveAddr(eglib, dc)
See hal_i2c_config_t get_7bit_slave_addr for details on this

function.

eglib_I2cSend(eglib, i2c_write, dc, bytes, length)
See also

hal_i2c_config_t send for details on this function.

Display Functions

These functions can be used by end users to query and send commands to the display driver.

eglib_GetDimension(eglib, width, height)

Get display dimensions.

Parameters

  • eglib – eglib_t handle.

  • width – Pointer where to write display width to.

  • height – Pointer where to write display height to.

eglib_GetPixelFormat(eglib, pixel_format)

Returns the pixel format used in-memory by the display.

Parameters
Returns

pixel_format_t.

coordinate_t eglib_GetWidth(eglib_t * eglib)

Returns display width as coordinate_t.

coordinate_t eglib_GetHeight(eglib_t * eglib)

Returns display height as coordinate_t.

_Bool eglib_Refresh(eglib_t * eglib)

Refreshes the display image. Only applicable to some displays (eg: e-ink / e-paper). Typical usage:

while(eglib_Refresh(eglib));
Parameters
Returns

true when refresh is ongoing and false when refresh finished.

eglib_IsRefreshing(eglib)

Whether a display refresh initiated by eglib_Refresh() is ongoing