An abstraction for display, keyboard and mouse. More...

#include <core/gp_types.h>
#include <utils/gp_timer.h>
#include <utils/gp_list.h>
#include <utils/gp_poll.h>
#include <input/gp_ev_queue.h>
#include <input/gp_task.h>
#include <backends/gp_types.h>

Data Structures
struct	gp_backend
	A backend. More...

Enumerations
enum	gp_backend_attr { GP_BACKEND_ATTR_SIZE , GP_BACKEND_ATTR_TITLE , GP_BACKEND_ATTR_FULLSCREEN , GP_BACKEND_ATTR_CURSOR }
	Backend attributes. More...

enum	gp_backend_ret { GP_BACKEND_OK = 0 , GP_BACKEND_OFF = 0 , GP_BACKEND_ON = 1 , GP_BACKEND_NOTSUPP = -1 , GP_BACKEND_EINVAL = -2 , GP_BACKEND_CONNERR = -3 }
	A return value from the backend set_attr callback. More...

enum	gp_backend_fullscreen_req { GP_BACKEND_FULLSCREEN_OFF = 0 , GP_BACKEND_FULLSCREEN_ON = 1 , GP_BACKEND_FULLSCREEN_TOGGLE = 2 , GP_BACKEND_FULLSCREEN_QUERY = 3 }
	Fullscreen request type. More...

enum	gp_backend_cursor_req { GP_BACKEND_CURSOR_ARROW , GP_BACKEND_CURSOR_TEXT_EDIT , GP_BACKEND_CURSOR_CROSSHAIR , GP_BACKEND_CURSOR_HAND , GP_BACKEND_CURSOR_MAX , GP_BACKEND_CURSOR_SHOW = 0xc000 , GP_BACKEND_CURSOR_HIDE = 0x8000 }
	Cursor types. More...

Functions
static void	gp_backend_flip (gp_backend *self)
	Copies whole backend pixmap to a display.

void	gp_backend_update_rect_xyxy (gp_backend *self, gp_coord x0, gp_coord y0, gp_coord x1, gp_coord y1)
	Copies a rectangle from backend pixmap to a display.

static void	gp_backend_update_rect (gp_backend *self, gp_coord x0, gp_coord y0, gp_coord x1, gp_coord y1)
	Copies a rectangle from backend pixmap to a display.

static void	gp_backend_update_rect_xywh (gp_backend *self, gp_coord x, gp_coord y, gp_size w, gp_size h)
	Copies a rectangle from backend pixmap to a display.

static void	gp_backend_poll_add (gp_backend self, gp_fd fd)
	Add a file descriptor to the backend poll loop.

static void	gp_backend_poll_rem (gp_backend self, gp_fd fd)
	Removes a file descriptor to the backend poll loop.

static gp_fd *	gp_backend_poll_rem_by_fd (gp_backend *self, int fd)
	Removes a file descriptor to the backend poll loop.

static enum gp_backend_ret	gp_backend_cursor_set (gp_backend *self, enum gp_backend_cursor_req cursor)
	Sets backend cursor type.

void	gp_backend_exit (gp_backend *self)
	Exits the backend.

void	gp_backend_poll (gp_backend *self)
	Polls a backend for events.

gp_event *	gp_backend_ev_poll (gp_backend *self)
	Returns an event from the queue, polls the backend for events if the queue is empty.

void	gp_backend_wait (gp_backend *self)
	Waits for a backend events.

gp_event *	gp_backend_ev_wait (gp_backend *self)
	Returns an event from the queue, wait the backend for events if the queue is empty.

void	gp_backend_timer_add (gp_backend self, gp_timer timer)
	Adds a timer to backend.

void	gp_backend_timer_rem (gp_backend self, gp_timer timer)
	Removes timer from backend timer queue.

static unsigned int	gp_backend_timers_queued (gp_backend *self)
	Returns number of timers scheduled in backend.

int	gp_backend_timer_timeout (gp_backend *self)
	Returns time to the closest timer timeout.

static enum gp_backend_ret	gp_backend_set_caption (gp_backend backend, const char caption)
	Sets backend caption, if supported.

int	gp_backend_resize (gp_backend *backend, uint32_t w, uint32_t h)
	Request backend resize.

static enum gp_backend_ret	gp_backend_fullscreen (gp_backend *backend, enum gp_backend_fullscreen_req req)
	Reuqests to change fullscreen mode.

int	gp_backend_resize_ack (gp_backend *self)
	Resize acknowledge.

void	gp_backend_task_ins (gp_backend self, gp_task task)
	Inserts a task into the task queue.

void	gp_backend_task_rem (gp_backend self, gp_task task)
	Removes a task from the task queue.

void	gp_backend_task_queue_set (gp_backend self, gp_task_queue task_queue)
	Sets the backend task_queue and starts task processing.

static void	gp_backend_ev_flush (gp_backend *self)
	Removes all events from the event queue.

static unsigned int	gp_backend_ev_queued (gp_backend *self)
	Returns a number of events in the backend event queue.

static gp_event *	gp_backend_ev_get (gp_backend *self)
	Removes and returns a pointer to a first event in the queue.

static gp_event *	gp_backend_ev_peek (gp_backend *self)
	Returns a pointer to a first event in the queue.

static void	gp_backend_ev_put_back (gp_backend self, gp_event ev)
	Puts back an event that has been just removed from the queue.

Detailed Description

An abstraction for display, keyboard and mouse.

The gp_backend is unified API for managing xserver, framebuffer, waylaynd, drm, e-ink display, etc. along with support for input devices, e.g. mouse, keyboard and keymaps. It also implements timers and tasks so that work can be schedulled.

In contrast to other graphics libraries we do not try to create unified initalization interface that would match specialities for every possible backend. Rather than that we are trying to create API that is the same for all backends, once initalization is done. This is implemented by optional backend attributes that may or may not be supported by a backend.

Definition in file gp_backend.h.

Enumeration Type Documentation

◆ gp_backend_attr

enum gp_backend_attr

Backend attributes.

Enumerator
GP_BACKEND_ATTR_SIZE	Window change request. The attribute value is an array with two integers.
GP_BACKEND_ATTR_TITLE	Window title change request. The attribute value is an UTF8 string.
GP_BACKEND_ATTR_FULLSCREEN	Fullscreen mode change request. The attribute value is enum gp_backend_fullscreen_req.
GP_BACKEND_ATTR_CURSOR	Cursor modifications. The attribute value is enum gp_backend_cursor_req.

Definition at line 42 of file gp_backend.h.

◆ gp_backend_cursor_req

enum gp_backend_cursor_req

Cursor types.

Enumerator
GP_BACKEND_CURSOR_ARROW	Arrow default cursor type.
GP_BACKEND_CURSOR_TEXT_EDIT	Text edit cursor.
GP_BACKEND_CURSOR_CROSSHAIR	Crosshair.
GP_BACKEND_CURSOR_HAND	Used typicaly while howering over links.
GP_BACKEND_CURSOR_MAX	Last cursor + 1.
GP_BACKEND_CURSOR_SHOW	Shows cursor.
GP_BACKEND_CURSOR_HIDE	Hides cursor.

Definition at line 122 of file gp_backend.h.

◆ gp_backend_fullscreen_req

enum gp_backend_fullscreen_req

Fullscreen request type.

Enumerator
GP_BACKEND_FULLSCREEN_OFF	Request fullscreen to be turned off.
GP_BACKEND_FULLSCREEN_ON	Request fullscreen to be turned on.
GP_BACKEND_FULLSCREEN_TOGGLE	Toggle fullscreen state.
GP_BACKEND_FULLSCREEN_QUERY	Query fullscreen state. Returns the fullscreen state one of GP_BACKEND_ON, GP_BACKEND_OFF or an error e.g. GP_BACKEND_NOTSUPP if fullscreen is not supported.

Definition at line 103 of file gp_backend.h.

◆ gp_backend_ret

enum gp_backend_ret

A return value from the backend set_attr callback.

All error states are negative, for fucntions that sets attribute success is 0 and for functions that query an attribute the return is either >= 0 for success, or negative for errors.

Enumerator
GP_BACKEND_OK	Atrribute set succesfully.
GP_BACKEND_OFF	Attribute is disabled.
GP_BACKEND_ON	Attribute is enabled.
GP_BACKEND_NOTSUPP	Unsupported attribute. Not all backends support all attributes.
GP_BACKEND_EINVAL	Invalid value. E.g. an attempt to set windows size to 0x0 pixels or resize window in a fullscreen mode.
GP_BACKEND_CONNERR	Connection error.

Definition at line 76 of file gp_backend.h.

Function Documentation

◆ gp_backend_cursor_set()

static enum gp_backend_ret gp_backend_cursor_set	(	gp_backend *	self,
		enum gp_backend_cursor_req	cursor
	)

inlinestatic

Sets backend cursor type.

If supported changes backend cursor to the requested type, disables or enables a cursor.

Parameters

self	A backend.
cursor	A cursor type.

Returns: A GP_BACKEND_OK if cursor was modified, GP_BACKEND_NOTSUPP if backend cursor cannot be set.

Definition at line 384 of file gp_backend.h.

References GP_BACKEND_ATTR_CURSOR, GP_BACKEND_NOTSUPP, and gp_backend::set_attr.

◆ gp_backend_ev_flush()

static void gp_backend_ev_flush ( gp_backend * self )

inlinestatic

Removes all events from the event queue.

Parameters

self	A backend.

Definition at line 646 of file gp_backend.h.

References gp_ev_queue_flush().

◆ gp_backend_ev_get()

static gp_event * gp_backend_ev_get ( gp_backend * self )

inlinestatic

Removes and returns a pointer to a first event in the queue.

Warning: The pointer to the event is valid only until the next call to a function that modifies the queue. That includes the functions that fill in the queue e.g. gp_backend_wait().

Parameters

self	A backend.

Returns: A pointer to an event or NULL if queue is empty.

Definition at line 673 of file gp_backend.h.

References gp_ev_queue_get().

◆ gp_backend_ev_peek()

static gp_event * gp_backend_ev_peek ( gp_backend * self )

inlinestatic

Returns a pointer to a first event in the queue.

Unlike the gp_backend_ev_get() the event is not removed from the queue.

Warning: The pointer to the event is valid only until the next call to a function that modifies the queue. That includes the functions that fill in the queue e.g. gp_backend_wait().

Parameters

self	A backend.

Returns: A pointer to an event or NULL if queue is empty.

Definition at line 690 of file gp_backend.h.

References gp_ev_queue_peek().

◆ gp_backend_ev_poll()

gp_event * gp_backend_ev_poll ( gp_backend * self )

Returns an event from the queue, polls the backend for events if the queue is empty.

This combines a gp_backend_poll() and gp_backend_ev_get() into a one function. The call to gp_backend_poll() may generate more than one event so the function tries to return events from the queue first and only if the queue is empty it reaches to the backend to try to fill the queue.

The function is supposed to be called in a loop:

gp_event *ev;
 
while ((ev = gp_backend_ev_poll(backend)) {
     // Event processing has to be done here
 
     // To avoid bussy loop we have to sleep here
     usleep(100);
}

Parameters

self	A backend.

Returns: An event or NULL if queue was empty and no events were generated by by backend.

◆ gp_backend_ev_put_back()

static void gp_backend_ev_put_back	(	gp_backend *	self,
		gp_event *	ev
	)

inlinestatic

Puts back an event that has been just removed from the queue.

This can undo a last call to gp_backend_ev_get() by putting the event that has been just removed back into the queue.

Warning: An attempt to put back more than one evevent or an event that wasn't removed from the top of the queue is not supported.

Parameters

self	A backend.
ev	An event to be put back into the queue.

Definition at line 707 of file gp_backend.h.

References gp_ev_queue_put_back().

◆ gp_backend_ev_queued()

static unsigned int gp_backend_ev_queued ( gp_backend * self )

inlinestatic

Returns a number of events in the backend event queue.

Parameters

self	A backend.

Returns: A number of events queued.

Definition at line 658 of file gp_backend.h.

References gp_ev_queue_events().

◆ gp_backend_ev_wait()

gp_event * gp_backend_ev_wait ( gp_backend * self )

Returns an event from the queue, wait the backend for events if the queue is empty.

This combines a gp_backend_wait() and gp_backend_ev_get() into a one function. The call to gp_backend_wait() may generate more than one event so the function tries to return events from the queue first and only if the queue is empty it reaches to the backend to try to fill the queue.

The function is supposed to be called in a loop:

for (;;) {
     gp_event *ev = gp_backend_ev_wait(backend));
 
     // Event processing has to be done here
}

Parameters

self	A backend.

Returns: An event.

◆ gp_backend_exit()

void gp_backend_exit ( gp_backend * self )

Exits the backend.

This functions deinitializes the backend. E.g. closes all file descriptors, frees memory, etc.

Warning: It's important to call this before the application exits since some backends, e.g. framebuffer, cannot be recovered unless we return the underlying facility to the original state.

Parameters

self	A backend.

◆ gp_backend_flip()

static void gp_backend_flip ( gp_backend * self )

inlinestatic

Copies whole backend pixmap to a display.

Majority of the backends are double buffered, that means that changes done to gp_backend::pixmap are not propagated to the display memory buffer unless they are copied explicitly. This call copies the complete backend pixmap to the display.

Parameters

self	A backend.

Definition at line 279 of file gp_backend.h.

References gp_backend::flip.

◆ gp_backend_fullscreen()

static enum gp_backend_ret gp_backend_fullscreen	(	gp_backend *	backend,
		enum gp_backend_fullscreen_req	req
	)

inlinestatic

Reuqests to change fullscreen mode.

Parameters

backend	A backend.
req	A fullscreen request.

Returns: GP_BACKEND_OK on success, negative on failure. In the case of GP_BACKEND_FULLSCREEN_QUERY it's either GP_BACKEND_ON, GP_BACKEND_OFF or an error, most commonly GP_BACKEND_NOTSUPP.

Definition at line 576 of file gp_backend.h.

References GP_BACKEND_ATTR_FULLSCREEN, GP_BACKEND_NOTSUPP, and gp_backend::set_attr.

◆ gp_backend_poll()

void gp_backend_poll ( gp_backend * self )

Polls a backend for events.

This is a non-blocking function that fills the events into the backend event queue.

Parameters

self	A backend.

◆ gp_backend_poll_add()

static void gp_backend_poll_add	(	gp_backend *	self,
		gp_fd *	fd
	)

inlinestatic

Add a file descriptor to the backend poll loop.

Parameters

self	A backend.
fd	A file descriptor with a callback.

Definition at line 345 of file gp_backend.h.

References gp_backend::fds, and gp_poll_add().

◆ gp_backend_poll_rem()

static void gp_backend_poll_rem	(	gp_backend *	self,
		gp_fd *	fd
	)

inlinestatic

Removes a file descriptor to the backend poll loop.

Parameters

self	A backend.
fd	A file descriptor with a callback.

Definition at line 356 of file gp_backend.h.

References gp_backend::fds, and gp_poll_rem().

◆ gp_backend_poll_rem_by_fd()

static gp_fd * gp_backend_poll_rem_by_fd	(	gp_backend *	self,
		int	fd
	)

inlinestatic

Removes a file descriptor to the backend poll loop.

Parameters

self	A backend.
fd	A file descriptor used to look up the gp_fd structure.

Definition at line 367 of file gp_backend.h.

References gp_backend::fds, and gp_poll_rem_by_fd().

◆ gp_backend_resize()

int gp_backend_resize	(	gp_backend *	backend,
		uint32_t	w,
		uint32_t	h
	)

Request backend resize.

When the backend size matches the requested width and height no action is done.

If a resize request is granted the backend sends GP_EV_SYS event type with GP_EV_SYS_RESIZE code and the new width and height in the struct gp_ev_sys. Upon receiving this event the application must stop any access to the gp_backend::pixmap and call gp_backend_resize_ack() to signal to the backend that it's safe to resize the buffers. Once that is done the application can start drawing to the new and resized gp_backend::pixmap.

Returns: When resizing is not possible or not implemented non zero is returned.

◆ gp_backend_resize_ack()

int gp_backend_resize_ack ( gp_backend * self )

Resize acknowledge.

You must call this right after you application has received resize event. For a multithreaded application all threads that operate on the backend pixmap must be stopped first.

After this call returns the backend pixmap has been resized, that means that at least the width, height, and pixels of gp_backend::pixmap are different and the content of the gp_pixmap::pixels is undefined.

This call also resizes the window, display, screen size in the backend gp_ev_queue.

If the function fails the best action to take is to save application data and exit as the backend may be in undefined state.

Parameters

self	A backend.

Returns: Zero on success, non-zero otherwise.

◆ gp_backend_set_caption()

static enum gp_backend_ret gp_backend_set_caption	(	gp_backend *	backend,
		const char *	caption
	)

inlinestatic

Sets backend caption, if supported.

Caption is an UTF8 string that is usually shown in the window title.

Returns: On success GP_BACKEND_OK is returned. When setting caption is not possible or implemented GP_BACKEND_NOTSUPP is returned.

Definition at line 540 of file gp_backend.h.

References GP_BACKEND_ATTR_TITLE, GP_BACKEND_NOTSUPP, and gp_backend::set_attr.

◆ gp_backend_task_ins()

void gp_backend_task_ins	(	gp_backend *	self,
		gp_task *	task
	)

Inserts a task into the task queue.

Tasks are executed sequentionally and input processing is blocked during task execution.

Warning: When backend is created there is no task queue, to be able to schedulle tasks user has to allocate and set the task queue first.

Parameters

self	A backend.
task	A task to be inserted into the task queue.

◆ gp_backend_task_queue_set()

void gp_backend_task_queue_set	(	gp_backend *	self,
		gp_task_queue *	task_queue
	)

Sets the backend task_queue and starts task processing.

By default backends does not have a task queue populated. Applications that require a task queue have to allocate and initialize the queue then pass it to the backend with this function.

Parameters

self	A backend.
task_queue	A pointer to initialized task_queue.

◆ gp_backend_task_rem()

void gp_backend_task_rem	(	gp_backend *	self,
		gp_task *	task
	)

Removes a task from the task queue.

Parameters

self	A backend.
task	A task to be removed from the task queue.

◆ gp_backend_timer_add()

void gp_backend_timer_add	(	gp_backend *	self,
		gp_timer *	timer
	)

Adds a timer to backend.

If timer callback is NULL a #gp_ev with GP_EV_TMR type is pushed into the backend event queue once timer expires.

Parameters

self	A backend.
timer	A timer.

◆ gp_backend_timer_rem()

void gp_backend_timer_rem	(	gp_backend *	self,
		gp_timer *	timer
	)

Removes timer from backend timer queue.

Parameters

self	A backend.
timer	A timer.

◆ gp_backend_timer_timeout()

int gp_backend_timer_timeout ( gp_backend * self )

Returns time to the closest timer timeout.

Parameters

self	A backend.

Returns: Returns a timeout to a closest timer in ms or -1. Can be passed directly to poll(2).

◆ gp_backend_timers_queued()

static unsigned int gp_backend_timers_queued ( gp_backend * self )

inlinestatic

Returns number of timers scheduled in backend.

Parameters

self	A backend.

Definition at line 517 of file gp_backend.h.

References gp_timer_queue_size(), and gp_backend::timers.

◆ gp_backend_update_rect()

static void gp_backend_update_rect	(	gp_backend *	self,
		gp_coord	x0,
		gp_coord	y0,
		gp_coord	x1,
		gp_coord	y1
	)

inlinestatic

Copies a rectangle from backend pixmap to a display.

This is an alias for gp_backend_update_rect_xyxy().

Parameters

self	A backend.
x0	First x coordinate of the rectangle.
y0	First y coordinate of the rectangle.
x1	Last x coordinate of the rectangle.
y1	Last y coordinate of the rectangle.

Definition at line 314 of file gp_backend.h.

References gp_backend_update_rect_xyxy().

◆ gp_backend_update_rect_xywh()

static void gp_backend_update_rect_xywh	(	gp_backend *	self,
		gp_coord	x,
		gp_coord	y,
		gp_size	w,
		gp_size	h
	)

inlinestatic

Copies a rectangle from backend pixmap to a display.

This is a version of gp_backend_update_rect_xyxy() with width and height.

Parameters

self	A backend.
x	Left x coordinate of the rectangle.
y	Top y coordinate of the rectangle.
w	Rectangle width.
h	Rectangle height.

Definition at line 332 of file gp_backend.h.

References gp_backend_update_rect_xyxy().

◆ gp_backend_update_rect_xyxy()

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

Copies a rectangle from backend pixmap to a display.

Majority of the backends are double buffered, that means that changes done to gp_backend::pixmap are not propagated to the display memory buffer unless they are copied explicitly. This call copies a rectanlge from backend pixmap to the display.

Parameters

self	A backend.
x0	First x coordinate of the rectangle.
y0	First y coordinate of the rectangle.
x1	Last x coordinate of the rectangle.
y1	Last y coordinate of the rectangle.

Referenced by gp_backend_update_rect(), and gp_backend_update_rect_xywh().

◆ gp_backend_wait()

void gp_backend_wait ( gp_backend * self )

Waits for a backend events.

This is a blocking call that fills the events into the backend event queue.

Once this call returns the events from the event queue must be processed.

The event processing may look like:

for (;;) {
     gp_event *ev;
 
     gp_backend_wait(backend);
 
     while ((ev = gp_backend_ev_get(backend)) {
     // Event processing has to be done here
     }
}

Parameters

self	A backend.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ gp_backend_attr

◆ gp_backend_cursor_req

◆ gp_backend_fullscreen_req

◆ gp_backend_ret

Function Documentation

◆ gp_backend_cursor_set()

◆ gp_backend_ev_flush()

◆ gp_backend_ev_get()

◆ gp_backend_ev_peek()

◆ gp_backend_ev_poll()

◆ gp_backend_ev_put_back()

◆ gp_backend_ev_queued()

◆ gp_backend_ev_wait()

◆ gp_backend_exit()

◆ gp_backend_flip()

◆ gp_backend_fullscreen()

◆ gp_backend_poll()

◆ gp_backend_poll_add()

◆ gp_backend_poll_rem()

◆ gp_backend_poll_rem_by_fd()

◆ gp_backend_resize()

◆ gp_backend_resize_ack()

◆ gp_backend_set_caption()

◆ gp_backend_task_ins()

◆ gp_backend_task_queue_set()

◆ gp_backend_task_rem()

◆ gp_backend_timer_add()

◆ gp_backend_timer_rem()

◆ gp_backend_timer_timeout()

◆ gp_backend_timers_queued()

◆ gp_backend_update_rect()

◆ gp_backend_update_rect_xywh()

◆ gp_backend_update_rect_xyxy()

◆ gp_backend_wait()