Display connection. More...

Collaboration diagram for Display Connection:

Detailed Description

Display connection.

A display represents a connection to the Desktop Window Manager (DWM).

The display system IS thread safe, but the rest of the Patchwork library may not be. The display connection can thus be used to synchronize multiple threads when working with windows, etc.

There are two things of note for performance when using a display. First, commands are batched and sent together when display_cmds_flush() is called. Second, the display uses a internal pipe to store events that cant be processed immediately and this means that if a thread calls display_push() another thread blocking on display_next() will unblock since its blocking on both the displays DWM connection and the internal pipe.

Data Structures
struct	display_t
	Opaque display structure. More...

Typedefs
typedef struct display	display_t

Functions
display_t *	display_new (void)
	Create a new display connection.

void	display_free (display_t *disp)
	Free a display connection.

bool	display_is_connected (display_t *disp)
	Check if the display connection is still connected.

void	display_disconnect (display_t *disp)
	Disconnect the display connection.

void *	display_cmd_alloc (display_t *disp, cmd_type_t type, uint64_t size)
	Allocate a section of the displays command buffer.

void	display_cmds_flush (display_t *disp)
	Flush the display's command buffer.

uint64_t	display_next (display_t disp, event_t event, clock_t timeout)
	Retrieve the next event from the display connection.

uint64_t	display_poll (display_t disp, pollfd_t fds, uint64_t nfds, clock_t timeout)
	Poll the display connection for events together with other file descriptors.

void	display_push (display_t disp, surface_id_t target, event_type_t type, void data, uint64_t size)
	Push an event to the display's internal event queue.

uint64_t	display_wait (display_t disp, event_t event, event_type_t expected)
	Wait for the display to receive an event of the expected type.

uint64_t	display_emit (display_t disp, surface_id_t target, event_type_t type, void data, uint64_t size)
	Emit an event to a target surface.

uint64_t	display_dispatch (display_t disp, const event_t event)
	Dispatch an event to the appropriate surface.

uint64_t	display_dispatch_pending (display_t *disp, event_type_t type, surface_id_t target)
	Dispatch all events currently in the display's internal event queue of a specific type and target.

uint64_t	display_subscribe (display_t *disp, event_type_t type)
	Subscribe to events of a specific type.

uint64_t	display_unsubscribe (display_t *disp, event_type_t type)
	Unsubscribe from events of a specific type.

uint64_t	display_get_surface_info (display_t disp, surface_id_t id, surface_info_t info)
	Get information about a surface.

uint64_t	display_set_focus (display_t *disp, surface_id_t id)
	Set the focus to a surface.

uint64_t	display_set_is_visible (display_t *disp, surface_id_t id, bool isVisible)
	Set the visibility of a surface.

uint64_t	display_get_screen (display_t disp, rect_t rect, uint64_t index)
	Get the rectangle of a screen.

Typedef Documentation

◆ display_t

typedef struct display display_t

Definition at line 39 of file display.h.

Function Documentation

◆ display_new()

display_t * display_new ( void )

Create a new display connection.

Returns: On success, a The display connection. On failure, NULL and errno is set.

Definition at line 36 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_free()

void display_free ( display_t * disp )

Free a display connection.

Parameters

disp	The display connection.

Definition at line 119 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_is_connected()

bool display_is_connected ( display_t * disp )

Check if the display connection is still connected.

Parameters

disp	The display connection.

Returns: true if connected, false otherwise.

Definition at line 155 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_disconnect()

void display_disconnect ( display_t * disp )

Disconnect the display connection.

After calling this function, the display connection will be marked as disconnected and no further commands or events will be processed.

Will not free the display connection, use display_free() for that.

Parameters

disp	The display connection.

Definition at line 168 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_cmd_alloc()

void * display_cmd_alloc	(	display_t *	disp,
		cmd_type_t	type,
		uint64_t	size
	)

Allocate a section of the displays command buffer.

The display batches commands together in its command buffer, where each command is prefixed with a cmd_header_t and has a variable size.

Parameters

disp	The display connection.
type	Type of command to allocate.
size	Size of the command data to allocate.

Returns: Pointer to the allocated command data, or NULL on failure and errno is set.

Definition at line 180 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_cmds_flush()

void display_cmds_flush ( display_t * disp )

Flush the display's command buffer.

This will send all queued commands to the DWM.

Parameters

disp	The display connection.

Definition at line 205 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_next()

uint64_t display_next	(	display_t *	disp,
		event_t *	event,
		clock_t	timeout
	)

Retrieve the next event from the display connection.

Parameters

disp	The display connection.
event	Output pointer to store the retrieved event.
timeout	Maximum time to wait for an event, if `CLOCKS_NEVER` will wait indefinitely.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 220 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_poll()

uint64_t display_poll	(	display_t *	disp,
		pollfd_t *	fds,
		uint64_t	nfds,
		clock_t	timeout
	)

Poll the display connection for events together with other file descriptors.

Parameters

disp	The display connection.
fds	Array of file descriptors to poll alongside the display connection.
nfds	Number of file descriptors in the array.
timeout	Maximum time to wait for an event, if `CLOCKS_NEVER` will wait indefinitely.

Returns: On success, number of file descriptors with events (not including the display connection). On failure, returns ERR and errno is set.

Definition at line 295 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_push()

void display_push	(	display_t *	disp,
		surface_id_t	target,
		event_type_t	type,
		void *	data,
		uint64_t	size
	)

Push an event to the display's internal event queue.

This will not send the event to the DWM, instead it will be stored in the display's internal event queue and can be retrieved using display_next().

Parameters

disp	The display connection.
target	Target surface ID for the event.
type	Type of event.
data	Pointer to the event data, can be `NULL` if `size` is `0`.
size	Size of the event data, must be less than `EVENT_MAX_DATA`.

Definition at line 356 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_wait()

uint64_t display_wait	(	display_t *	disp,
		event_t *	event,
		event_type_t	expected
	)

Wait for the display to receive an event of the expected type.

This function will block until an event of the expected type is received.

Any other events received while waiting will be pushed back to the display's internal event queue.

Parameters

disp	The display connection.
event	Output pointer to store the retrieved event.
expected	The expected event type to wait for.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 374 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_emit()

uint64_t display_emit	(	display_t *	disp,
		surface_id_t	target,
		event_type_t	type,
		void *	data,
		uint64_t	size
	)

Emit an event to a target surface.

This function will construct an event and dispatch it to the target surface.

Parameters

disp	The display connection.
target	Target surface ID for the event, if `SURFACE_ID_NONE` the event is sent to all surfaces.
type	Type of event.
data	Pointer to the event data, can be `NULL` if `size` is `0`.
size	Size of the event data, must be less than `EVENT_MAX_DATA`.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 426 of file display.c.

Here is the call graph for this function:

◆ display_dispatch()

uint64_t display_dispatch	(	display_t *	disp,
		const event_t *	event
	)

Dispatch an event to the appropriate surface.

Will flush the display's command buffer after dispatching the event.

Parameters

disp	The display connection.
event	The event to dispatch.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 447 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_dispatch_pending()

uint64_t display_dispatch_pending	(	display_t *	disp,
		event_type_t	type,
		surface_id_t	target
	)

Dispatch all events currently in the display's internal event queue of a specific type and target.

Parameters

disp	The display connection.
type	The event type to check for.
target	The target surface ID for the events, if `SURFACE_ID_NONE` all events are dispatched.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 479 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_subscribe()

uint64_t display_subscribe	(	display_t *	disp,
		event_type_t	type
	)

Subscribe to events of a specific type.

Should only be used for events sent by the DWM.

Parameters

disp	The display connection.
type	The event type to subscribe to.

Definition at line 516 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_unsubscribe()

uint64_t display_unsubscribe	(	display_t *	disp,
		event_type_t	type
	)

Unsubscribe from events of a specific type.

Should only be used for events sent by the DWM.

Parameters

disp	The display connection.
type	The event type to unsubscribe from.

Definition at line 535 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_get_surface_info()

uint64_t display_get_surface_info	(	display_t *	disp,
		surface_id_t	id,
		surface_info_t *	info
	)

Get information about a surface.

Uses a CMD_SURFACE_REPORT command to request information about the specified surface from the DWM.

Parameters

disp	The display connection.
id	The surface ID to query.
info	Output pointer to store the surface information.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 554 of file display.c.

Here is the call graph for this function:

◆ display_set_focus()

uint64_t display_set_focus	(	display_t *	disp,
		surface_id_t	id
	)

Set the focus to a surface.

Can apply to any surface, not just ones owned by the client.

Parameters

disp	The display connection.
id	The surface ID to set focus to.

Definition at line 581 of file display.c.

Here is the call graph for this function:

◆ display_set_is_visible()

uint64_t display_set_is_visible	(	display_t *	disp,
		surface_id_t	id,
		bool	isVisible
	)

Set the visibility of a surface.

Can apply to any surface, not just ones owned by the client.

Parameters

disp	The display connection.
id	The surface ID to set visibility for.
isVisible	Whether the surface should be visible.

Definition at line 595 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ display_get_screen()

uint64_t display_get_screen	(	display_t *	disp,
		rect_t *	rect,
		uint64_t	index
	)

Get the rectangle of a screen.

Parameters

disp	The display connection.
rect	Output pointer to store the rectangle of the screen.
index	Index of the screen to query, only `0` is supported currently.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 610 of file display.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Detailed Description

Data Structures

Typedefs

Functions

Typedef Documentation

◆ display_t

Function Documentation

◆ display_new()

◆ display_free()

◆ display_is_connected()

◆ display_disconnect()

◆ display_cmd_alloc()

◆ display_cmds_flush()

◆ display_next()

◆ display_poll()

◆ display_push()

◆ display_wait()

◆ display_emit()

◆ display_dispatch()

◆ display_dispatch_pending()

◆ display_subscribe()

◆ display_unsubscribe()

◆ display_get_surface_info()

◆ display_set_focus()

◆ display_set_is_visible()

◆ display_get_screen()