1.. _absolute_axes: 2 3============================================================================== 4Absolute axes 5============================================================================== 6 7Devices with absolute axes are those that send positioning data for an axis in 8a device-specific coordinate range, defined by a minimum and a maximum value. 9Compare this to relative devices (e.g. a mouse) that can only detect 10directional data, not positional data. 11 12libinput supports three types of devices with absolute axes: 13 14 - multi-touch screens 15 - single-touch screens 16 - :ref:`graphics tablets <tablet-support>` 17 18Touchpads are technically absolute devices but libinput converts the axis values 19to directional motion and posts events as relative events. Touchpads do not count 20as absolute devices in libinput. 21 22For all absolute devices in libinput, the default unit for x/y coordinates is 23in mm off the top left corner on the device, or more specifically off the 24device's sensor. If the device is physically rotated from its natural 25position and this rotation was communicated to libinput (e.g. by setting 26the device left-handed), 27the coordinate origin is the top left corner in the current rotation. 28 29.. _absolute_axes_handling: 30 31------------------------------------------------------------------------------ 32Handling of absolute coordinates 33------------------------------------------------------------------------------ 34 35In most use-cases, absolute input devices are mapped to a single screen. For 36direct input devices such as touchscreens the aspect ratio of the screen and 37the device match. Mapping the input device position to the output position is 38thus a simple mapping between two coordinates. libinput provides the API for 39this with 40 41- **libinput_event_pointer_get_absolute_x_transformed()** for pointer events 42- **libinput_event_touch_get_x_transformed()** for touch events 43 44libinput's API only provides the call to map into a single coordinate range. 45If the coordinate range has an offset, the compositor is responsible for 46applying that offset after the mapping. For example, if the device is mapped 47to the right of two outputs, add the output offset to the transformed 48coordinate. 49 50.. _absolute_axes_nores: 51 52------------------------------------------------------------------------------ 53Devices without x/y resolution 54------------------------------------------------------------------------------ 55 56An absolute device that does not provide a valid resolution is considered 57buggy and must be fixed in the kernel. Some touchpad devices do not 58provide resolution, those devices are correctly handled within libinput 59(touchpads are not absolute devices, as mentioned above). 60 61.. _calibration: 62 63------------------------------------------------------------------------------ 64Calibration of absolute devices 65------------------------------------------------------------------------------ 66 67Absolute devices may require calibration to map precisely into the output 68range required. This is done by setting a transformation matrix, see 69**libinput_device_config_calibration_set_matrix()** which is applied to 70each input coordinate. 71 72.. math:: 73 \begin{pmatrix} 74 cos\theta & -sin\theta & xoff \\ 75 sin\theta & cos\theta & yoff \\ 76 0 & 0 & 1 77 \end{pmatrix} \begin{pmatrix} 78 x \\ y \\ 1 79 \end{pmatrix} 80 81:math:`\theta` is the rotation angle. The offsets :math:`xoff` and :math:`yoff` are 82specified in device dimensions, i.e. a value of 1 equals one device width or 83height. Note that rotation applies to the device's origin, rotation usually 84requires an offset to move the coordinates back into the original range. 85 86The most common matrices are: 87 88- 90 degree clockwise: 89 .. math:: 90 \begin{pmatrix} 91 0 & -1 & 1 \\ 92 1 & 0 & 0 \\ 93 0 & 0 & 1 94 \end{pmatrix} 95- 180 degree clockwise: 96 .. math:: 97 \begin{pmatrix} 98 -1 & 0 & 1 \\ 99 0 & -1 & 1 \\ 100 0 & 0 & 1 101 \end{pmatrix} 102- 270 degree clockwise: 103 .. math:: 104 \begin{pmatrix} 105 0 & 1 & 0 \\ 106 -1 & 0 & 1 \\ 107 0 & 0 & 1 108 \end{pmatrix} 109- reflection along y axis: 110 .. math:: 111 \begin{pmatrix} 112 -1 & 0 & 1 \\ 113 1 & 0 & 0 \\ 114 0 & 0 & 1 115 \end{pmatrix} 116 117See Wikipedia's 118`Transformation Matrix article <http://en.wikipedia.org/wiki/Transformation_matrix>`_ 119for more information on the matrix maths. See 120**libinput_device_config_calibration_get_default_matrix()** for how these 121matrices must be supplied to libinput. 122 123Once applied, any x and y axis value has the calibration applied before it 124is made available to the caller. libinput does not provide access to the 125raw coordinates before the calibration is applied. 126 127.. _absolute_axes_nonorm: 128 129------------------------------------------------------------------------------ 130Why x/y coordinates are not normalized 131------------------------------------------------------------------------------ 132 133x/y are not given in :ref:`normalized coordinates <motion_normalization>` 134([0..1]) for one simple reason: the aspect ratio of virtually all current 135devices is something other than 1:1. A normalized axes thus is only useful to 136determine that the stylus is e.g. at 78% from the left, 34% from the top of 137the device. Without knowing the per-axis resolution, these numbers are 138meaningless. Worse, calculation based on previous coordinates is simply wrong: 139a movement from 0/0 to 50%/50% is not a 45-degree line. 140 141This could be alleviated by providing resolution and information about the 142aspect ratio to the caller. Which shifts processing and likely errors into the 143caller for little benefit. Providing the x/y axes in mm from the outset 144removes these errors. 145