Debian Codegraph @

doc/user/absolute-axes.rst

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