Device-to-screen Calibration

Functions

int libinput_device_config_calibration_has_matrix (struct libinput_device *device)
 Check if the device can be calibrated via a calibration matrix. More...
 
enum libinput_config_status libinput_device_config_calibration_set_matrix (struct libinput_device *device, const float matrix[6])
 Apply the 3x3 transformation matrix to absolute device coordinates. More...
 
int libinput_device_config_calibration_get_matrix (struct libinput_device *device, float matrix[6])
 Return the current calibration matrix for this device. More...
 
int libinput_device_config_calibration_get_default_matrix (struct libinput_device *device, float matrix[6])
 Return the default calibration matrix for this device. More...
 

Detailed Description

Function Documentation

int libinput_device_config_calibration_get_default_matrix ( struct libinput_device device,
float  matrix[6] 
)

Return the default calibration matrix for this device.

On most devices, this is the identity matrix. If the udev property LIBINPUT_CALIBRATION_MATRIX is set on the respective udev device, that property's value becomes the default matrix, see Static device configuration via udev.

Parameters
deviceThe device to configure
matrixSet to the array representing the first two rows of a 3x3 matrix as described in libinput_device_config_calibration_set_matrix().
Returns
0 if no calibration is set and the returned matrix is the identity matrix, 1 otherwise
See also
libinput_device_config_calibration_has_matrix
libinput_device_config_calibration_set_matrix
libinput_device_config_calibration_get_default_matrix
int libinput_device_config_calibration_get_matrix ( struct libinput_device device,
float  matrix[6] 
)

Return the current calibration matrix for this device.

Parameters
deviceThe device to configure
matrixSet to the array representing the first two rows of a 3x3 matrix as described in libinput_device_config_calibration_set_matrix().
Returns
0 if no calibration is set and the returned matrix is the identity matrix, 1 otherwise
See also
libinput_device_config_calibration_has_matrix
libinput_device_config_calibration_set_matrix
libinput_device_config_calibration_get_default_matrix
int libinput_device_config_calibration_has_matrix ( struct libinput_device device)

Check if the device can be calibrated via a calibration matrix.

Parameters
deviceThe device to check
Returns
Non-zero if the device can be calibrated, zero otherwise.
See also
libinput_device_config_calibration_set_matrix
libinput_device_config_calibration_get_matrix
libinput_device_config_calibration_get_default_matrix
enum libinput_config_status libinput_device_config_calibration_set_matrix ( struct libinput_device device,
const float  matrix[6] 
)

Apply the 3x3 transformation matrix to absolute device coordinates.

This matrix has no effect on relative events.

Given a 6-element array [a, b, c, d, e, f], the matrix is applied as

1 [ a b c ] [ x ]
2 [ d e f ] * [ y ]
3 [ 0 0 1 ] [ 1 ]

The translation component (c, f) is expected to be normalized to the device coordinate range. For example, the matrix

1 [ 1 0 1 ]
2 [ 0 1 -1 ]
3 [ 0 0 1 ]

moves all coordinates by 1 device-width to the right and 1 device-height up.

The rotation matrix for rotation around the origin is defined as

1 [ cos(a) -sin(a) 0 ]
2 [ sin(a) cos(a) 0 ]
3 [ 0 0 1 ]

Note that any rotation requires an additional translation component to translate the rotated coordinates back into the original device space. The rotation matrixes for 90, 180 and 270 degrees clockwise are:

1 90 deg cw: 180 deg cw: 270 deg cw:
2 [ 0 -1 1] [ -1 0 1] [ 0 1 0 ]
3 [ 1 0 0] [ 0 -1 1] [ -1 0 1 ]
4 [ 0 0 1] [ 0 0 1] [ 0 0 1 ]
Parameters
deviceThe device to configure
matrixAn array representing the first two rows of a 3x3 matrix as described above.
Returns
A config status code.
See also
libinput_device_config_calibration_has_matrix
libinput_device_config_calibration_get_matrix
libinput_device_config_calibration_get_default_matrix