libei: The region API

libei 1.6.0 A library for Emulated Input

The region API
🥚 EI - The client API

The API to query a struct ei_region for information. More...

## Data Structures
struct | ei_region
| A rectangular region, defined by an x/y offset and a width and a height. More...

## Functions
struct ei_region * | ei_region_ref (struct ei_region *region)
struct ei_region * | ei_region_unref (struct ei_region *region)
void | ei_region_set_user_data (struct ei_region *region, void *user_data)
void * | ei_region_get_user_data (struct ei_region *region)
uint32_t | ei_region_get_x (struct ei_region *region)
uint32_t | ei_region_get_y (struct ei_region *region)
uint32_t | ei_region_get_width (struct ei_region *region)
uint32_t | ei_region_get_height (struct ei_region *region)
const char * | ei_region_get_mapping_id (struct ei_region *region)
| Get the unique identifier (representing an external resource) that is attached to this region, if any.
bool | ei_region_contains (struct ei_region *region, double x, double y)
| Return true if the point x/y (in desktop-wide coordinates) is within region.
bool | ei_region_convert_point (struct ei_region *region, double *x, double *y)
| Convert the point x/y in a desktop-wide coordinate system into the corresponding point relative to the offset of the given region.
double | ei_region_get_physical_scale (struct ei_region *region)
| Return the physical scale for this region.

## Detailed Description

The API to query a struct ei_region for information.

## Function Documentation

## ◆ ei_region_contains()

bool ei_region_contains | ( | struct ei_region * | region,
|  | double | x,
|  | double | y )

Return true if the point x/y (in desktop-wide coordinates) is within region.

## ◆ ei_region_convert_point()

bool ei_region_convert_point | ( | struct ei_region * | region,
|  | double * | x,
|  | double * | y )

Convert the point x/y in a desktop-wide coordinate system into the corresponding point relative to the offset of the given region.

If the point is inside the region, this function returns true and x and y are set to the points with the region offset subtracted. If the point is outside the region, this function returns false and x and y are left unmodified.

## ◆ ei_region_get_height()

uint32_t ei_region_get_height | ( | struct ei_region * | region | ) |

## ◆ ei_region_get_mapping_id()

const char * ei_region_get_mapping_id | ( | struct ei_region * | region | ) |

Get the unique identifier (representing an external resource) that is attached to this region, if any.

This is only available if the EIS implementation supports version 2 or later of the ei_device protocol interface and the EIS implementation chooses to attach such an identifier to the region.

This ID can be used by the client to identify an external resource that has a relationship with this region.

For example the client may receive a data stream with the video data that this region represents. By attaching the same identifier to the data stream and this region the EIS implementation can inform the client that the video data stream and the region represent paired data. Note that in this example use-case, if the stream is resized there may be a transition period where two regions have the same identifier - the old region and the new region with the updated size. A client must be able to handle the case where two mapping ids are identical.

libei does not look at or modify the value of the mapping id. Because the ID is assigned by the caller libei makes no guarantee that the ID is unique and/or corresponds to any particular format.

Since
  1.1

## ◆ ei_region_get_physical_scale()

double ei_region_get_physical_scale | ( | struct ei_region * | region | ) |

Return the physical scale for this region.

The default scale is 1.0.

The regions' coordinate space is in logical pixels in the EIS range. The logical pixels may or may not match the physical pixels on the output range but the mapping from logical pixels to physical pixels is performed by the EIS implementation.

In some use-cases though, relative data from a remote input source needs to be converted by the libei client into an absolute movement on an EIS region. In that case, the physical scale provides the factor to multiply the relative logical input to provide the expected physical relative movement.

For example consider the following dual-monitor setup comprising a 2k and a 4k monitor of the same physical size: The physical layout of the monitors appears like this:

2k 4k
+-------------++-------------+
| || |
| a b || c d |
| || |
+-------------++-------------+

The physical distance ab is the same as the physical distance cd. Where the EIS implementation supports high-dpi screens, the logical distance (in pixels) are identical too.

Where the EIS implementation does not support high-dpi screens, the logical layout of these two monitors appears like this:

2k 4k
+-------------++--------------------------+
| || |
| a b || |
| || |
+-------------+| c d |
| |
| |
| |
+--------------------------+

While the two physical distances ab and cd are still identical, the logical distance cd (in pixels) is twice that of ab. Where a libei client receives relative deltas from an input source and converts that relative input into an absolute position on the screen, it needs to take this into account.

For example, if a remote input source moves by relative 100 logical pixels, the libei client would convert this as a + 100 = b on the region for the 2k screen and send the absolute events to logically change the position from a to b. If the same remote input source moves by relative 100 logical pixels, the libei client would convert this as c + 100 * scale = d on the region for the 4k screen to logically change the position from c to d. While the pixel movement differs, the physical movement as seen by the user is thus identical.

A second possible use-case for the physical scale is to match pixels from one region to their respective counterpart on a different region. For example, if the bottom-right corner of the 2k screen in the illustration above has a coordinate of (x, y), the neighbouring pixel on the physical 4k screen is (0, y * scale).

## ◆ ei_region_get_user_data()

void * ei_region_get_user_data | ( | struct ei_region * | region | ) |

## ◆ ei_region_get_width()

uint32_t ei_region_get_width | ( | struct ei_region * | region | ) |

## ◆ ei_region_get_x()

uint32_t ei_region_get_x | ( | struct ei_region * | region | ) |

## ◆ ei_region_get_y()

uint32_t ei_region_get_y | ( | struct ei_region * | region | ) |

## ◆ ei_region_ref()

struct ei_region * ei_region_ref | ( | struct ei_region * | region | ) |

## ◆ ei_region_set_user_data()

void ei_region_set_user_data | ( | struct ei_region * | region,
|  | void * | user_data )

## ◆ ei_region_unref()

struct ei_region * ei_region_unref | ( | struct ei_region * | region | ) |