The region API

Data Structures
struct	eis_region
	Regions are only available on devices of type EIS_DEVICE_TYPE_VIRTUAL. More...

Functions
void	eis_region_set_size (struct eis_region *region, uint32_t w, uint32_t h)
	This call has no effect if called after eis_region_add()
void	eis_region_set_offset (struct eis_region *region, uint32_t x, uint32_t y)
	This call has no effect if called after eis_region_add()
void	eis_region_set_physical_scale (struct eis_region *region, double scale)
	Set the physical scale for this region.
void	eis_region_set_mapping_id (struct eis_region *region, const char *mapping_id)
	Attach a unique identifier representing an external resource to this region.
const char *	eis_region_get_mapping_id (struct eis_region *region)
	Get the unique ID for this region previously set by this caller, if any, or NULL if the client does not support region mapping id or no region ID has been set.
void	eis_region_add (struct eis_region *region)
	Add the given region to its device.
struct eis_region *	eis_region_ref (struct eis_region *region)
struct eis_region *	eis_region_unref (struct eis_region *region)
void *	eis_region_get_user_data (struct eis_region *region)
void	eis_region_set_user_data (struct eis_region *region, void *user_data)
uint32_t	eis_region_get_x (struct eis_region *region)
uint32_t	eis_region_get_y (struct eis_region *region)
uint32_t	eis_region_get_width (struct eis_region *region)
uint32_t	eis_region_get_height (struct eis_region *region)
double	eis_region_get_physical_scale (struct eis_region *region)
bool	eis_region_contains (struct eis_region *region, double x, double y)

Detailed Description

The API to query a struct eis_region for information

Function Documentation

eis_region_add()

void eis_region_add

(

struct eis_region *

region

)

Add the given region to its device.

Once added, the region will be sent to the client when the caller calls eis_device_add() later.

Adding the same region twice will be silently ignored.

eis_region_contains()

bool eis_region_contains	(	struct eis_region *	region,
		double	x,
		double	y )

See also

ei_region_contains

eis_region_get_height()

uint32_t eis_region_get_height

(

struct eis_region *

region

)

eis_region_get_mapping_id()

const char * eis_region_get_mapping_id

(

struct eis_region *

region

)

Get the unique ID for this region previously set by this caller, if any, or NULL if the client does not support region mapping id or no region ID has been set.

Region IDs require the client to support the ei_device interface version 2 or later. This function can be used to detect support for this interface: after eis_region_add() this region's ID is set to NULL if the client does not support that interface version.

In other words, if a caller sets a region ID with eis_region_set_mapping_id() and that region ID is returned after eis_region_add(), the client has been notified of the region ID.

Since

1.1

eis_region_get_physical_scale()

double eis_region_get_physical_scale

(

struct eis_region *

region

)

eis_region_get_user_data()

void * eis_region_get_user_data

(

struct eis_region *

region

)

eis_region_get_width()

uint32_t eis_region_get_width

(

struct eis_region *

region

)

eis_region_get_x()

uint32_t eis_region_get_x

(

struct eis_region *

region

)

eis_region_get_y()

uint32_t eis_region_get_y

(

struct eis_region *

region

)

eis_region_ref()

struct eis_region * eis_region_ref

(

struct eis_region *

region

)

eis_region_set_mapping_id()

void eis_region_set_mapping_id	(	struct eis_region *	region,
		const char *	mapping_id )

Attach a unique identifier representing an external resource to this region.

libeis does not look at or modify the value, it is passed through to the client if the client supports ei_device interface version 2 or later. Because the ID is assigned by the caller libei makes no guarantee that the ID is indeed unique and/or corresponds to any particular format.

This ID can be used by the caller to identify an external resource that has a relationship with this region. For example, a caller may have a data stream with the video data that this region represents. By attaching the same identifier to the data stream and this region a client (who needs to be aware of this approach) can pair the video data stream with the region. 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.

This function has no effect if called after eis_device_add()

Since

1.1

eis_region_set_offset()

void eis_region_set_offset	(	struct eis_region *	region,
		uint32_t	x,
		uint32_t	y )

This call has no effect if called after eis_region_add()

eis_region_set_physical_scale()

void eis_region_set_physical_scale	(	struct eis_region *	region,
		double	scale )

Set the physical scale for this region.

If unset, the scale defaults to 1.0.

A scale value of less or equal to 0.0 will be silently ignored.

This call has no effect if called after eis_region_add()

See ei_region_get_physical_scale() for details.

eis_region_set_size()

void eis_region_set_size	(	struct eis_region *	region,
		uint32_t	w,
		uint32_t	h )

This call has no effect if called after eis_region_add()

eis_region_set_user_data()

void eis_region_set_user_data	(	struct eis_region *	region,
		void *	user_data )

eis_region_unref()

struct eis_region * eis_region_unref

(

struct eis_region *

region

)