A backend. More...

#include <gp_backend.h>

Collaboration diagram for gp_backend:

[legend]

Data Fields
gp_pixmap *	pixmap
	Pointer to a pixmap an app should draw to.

const char *	name
	Backend name, e.g. "X11".

void(*	flip )(gp_backend *self)
	Flips backend and display buffers.

void(*	update )(gp_backend *self)
	Updates whole display buffer.

void(*	update_rect )(gp_backend *self, gp_coord x0, gp_coord y0, gp_coord x1, gp_coord y1)
	Updates display rectangle.

enum gp_backend_ret(*	set_attr )(gp_backend self, enum gp_backend_attr attr, const void vals)
	Attribute change callback.

void(*	exit )(gp_backend *self)
	Exits the backend.

void(*	poll )(gp_backend *self)
	Non-blocking event loop.

void(*	wait )(gp_backend *self, int timeout_ms)
	Blocking event loop. Blocks until events are ready.

gp_poll	fds
	File descriptors to poll for.

gp_ev_queue *	event_queue
	Queue to store input events.

gp_timer *	timers
	Priority queue for timers.

gp_task_queue *	task_queue
	Task queue.

gp_dlist	input_drivers
	List of input drivers feeding the ev_queue.

void *	clipboard_data
	Clipboard data.

unsigned int	dpi
	A backend DPI if unknown it's set to 0.

Detailed Description

A backend.

This is the main structure that describes a backend API.

Definition at line 175 of file gp_backend.h.

Field Documentation

◆ clipboard_data

void* gp_backend::clipboard_data

Clipboard data.

Pointer to be used by the backend clipboard implementation.

Definition at line 330 of file gp_backend.h.

◆ flip

void(* gp_backend::flip) (gp_backend *self)

Flips backend and display buffers.

This callback swaps buffers between gp_backend::pixmap and currently displayed buffer. Some backends, e.g. SPI displays, does not support this operation, the pointer is NULL and gp_backend_flip() falls back to gp_backend_update().

Definition at line 217 of file gp_backend.h.

Referenced by gp_backend_flip().

◆ input_drivers

gp_dlist gp_backend::input_drivers

List of input drivers feeding the ev_queue.

A double linked list gp_backend_input structures.

The file descriptor has to be registered separatelly to the gp_fds.

Definition at line 323 of file gp_backend.h.

◆ pixmap

gp_pixmap* gp_backend::pixmap

Pointer to a pixmap an app should draw to.

In most cases changes are not updated on a display until gp_backend_flip(), gp_backend_update() or gp_backend_update_rect() is called.

Generally there are three different possible ways how data are updated on a display.

Directly mapped display buffer (e.g. old Linux framebuffer) the pixmap data points directly to a DMA buffer that is periodically send to the display. In this case the gp_backend::flip, gp_backend::update, and gp_backend::update_rect pointers are set to NULL.
Buffers are atomically swapped on update (e.g. Linux DRM). The gp_backend::update_rect is NULL, the gp_backend_update_rect() calls gp_backend_update() and gp_backend::update does copy the old buffer to the new buffer before buffers are swapped.
Buffer is send over a bus to a display (e.g. e-ink or LCD SPI display). In this case the gp_backend::flip pointer is NULL and gp_backend_flip() calls gp_backend::update.

Warning: The pixmap or gp_pixmap::pixels pointers MAY change when data are updated on a display.

Definition at line 204 of file gp_backend.h.

Referenced by gp_backend_h(), gp_backend_pixel_type(), and gp_backend_w().

◆ poll

void(* gp_backend::poll) (gp_backend *self)

Non-blocking event loop.

Backends that have a file descriptor does not set this function and rather insert a file descriptor into the fds array.

Definition at line 285 of file gp_backend.h.

◆ set_attr

enum gp_backend_ret(* gp_backend::set_attr) (gp_backend *self, enum gp_backend_attr attr, const void *vals)

Attribute change callback.

This callback is not supposed to be used directly. Use the nice helpers such as gp_backend_resize() or gp_backend_fullscreen().

Parameters

self	A backend.
attr	Which attribute to set.
vals	An attribute value, the type depends on attribute.

Returns: Returns if attribute was succesfully set or a value in case of a attribute query.

Definition at line 246 of file gp_backend.h.

Referenced by gp_backend_backlight_dec(), gp_backend_backlight_get(), gp_backend_backlight_inc(), gp_backend_cursor_set(), gp_backend_fullscreen(), and gp_backend_set_caption().

◆ update

void(* gp_backend::update) (gp_backend *self)

Updates whole display buffer.

Updates a display to show an image from gp_backend::pixmap. The gp_backend::pixmap data (not necesarilly the gp_pixmap or gp_pixmap::pixels pointers) will keep the image data. For some backends, e.g. Linux DRM this means we are doing a memcpy() from the buffer we are going to display to a buffer that the application will write into.

This pointer may be NULL if gp_pixmap::pixels points directly to a display DMA buffer and in this case the gp_backend_update() is no-op.

Definition at line 233 of file gp_backend.h.

Referenced by gp_backend_update().

◆ update_rect

void(* gp_backend::update_rect) (gp_backend *self, gp_coord x0, gp_coord y0, gp_coord x1, gp_coord y1)

Updates display rectangle.

Updates a (part) of the gp_backend::pixmap buffer on the display.

Some backends does not support partial update (e.g. Linux DRM) and always do a full display update. Other backends needs to round the coordinates to a byte boundary (e.g. E-Ink display). That means that the whole buffer must contain valid data even if we do partial update.

Definition at line 246 of file gp_backend.h.

◆ wait

void(* gp_backend::wait) (gp_backend *self, int timeout_ms)

Blocking event loop. Blocks until events are ready.

Note that events received by a backend are not necessarily translated to input events. So input queue may be empty after Wait has returned.