Debian Codegraph @

doc/user/tablet-support.rst

raw
1 .. _tablet-support:
2
3 ==============================================================================
4 Tablet support
5 ==============================================================================
6
7 This page provides details about the graphics tablet
8 support in libinput. Note that the term "tablet" in libinput refers to
9 graphics tablets only (e.g. Wacom Intuos), not to tablet devices like the
10 Apple iPad.
11
12 .. figure:: tablet.svg
13 :align: center
14
15 Illustration of a graphics tablet
16
17 .. _tablet-tools:
18
19 ------------------------------------------------------------------------------
20 Pad buttons vs. tablet tools
21 ------------------------------------------------------------------------------
22
23 Most tablets provide two types of devices. The physical tablet often
24 provides a number of buttons and a touch ring or strip. Interaction on the
25 drawing surface of the tablet requires a tool, usually in the shape of a
26 stylus. The libinput interface exposed by devices with the
27 **LIBINPUT_DEVICE_CAP_TABLET_TOOL** capability applies only to events generated
28 by tools.
29
30 Buttons, rings or strips on the physical tablet hardware (the "pad") are
31 exposed by devices with the **LIBINPUT_DEVICE_CAP_TABLET_PAD** capability.
32 Pad events do not require a tool to be in proximity. Note that both
33 capabilities may exist on the same device though usually they are split
34 across multiple kernel devices.
35
36 .. figure:: tablet-interfaces.svg
37 :align: center
38
39 Difference between Pad and Tool buttons
40
41 Touch events on the tablet integrated into a screen itself are exposed
42 through the **LIBINPUT_DEVICE_CAP_TOUCH** capability. Touch events on a
43 standalone tablet are exposed through the **LIBINPUT_DEVICE_CAP_POINTER**
44 capability. In both cases, the kernel usually provides a separate event
45 node for the touch device, resulting in a separate libinput device.
46 See **libinput_device_get_device_group()** for information on how to associate
47 the touch part with other devices exposed by the same physical hardware.
48
49 .. _tablet-tip:
50
51 ------------------------------------------------------------------------------
52 Tool tip events vs. tool button events
53 ------------------------------------------------------------------------------
54
55 The primary use of a tablet tool is to draw on the surface of the tablet.
56 When the tool tip comes into contact with the surface, libinput sends an
57 event of type **LIBINPUT_EVENT_TABLET_TOOL_TIP**, and again when the tip
58 ceases contact with the surface.
59
60 Tablet tools may send button events; these are exclusively for extra buttons
61 unrelated to the tip. A button event is independent of the tip and can while
62 the tip is down or up.
63
64 Some tablet tools' pressure detection is too sensitive, causing phantom
65 touches when the user only slightly brushes the surfaces. For example, some
66 tools are capable of detecting 1 gram of pressure.
67
68 libinput uses a device-specific pressure threshold to determine when the tip
69 is considered logically down. As a result, libinput may send a nonzero
70 pressure value while the tip is logically up. Most application can and
71 should ignore pressure information until they receive the event of type
72 **LIBINPUT_EVENT_TABLET_TOOL_TIP**. Applications that require extremely
73 fine-grained pressure sensitivity should use the pressure data instead of
74 the tip events to determine a logical tip down state and treat the tip
75 events like axis events otherwise.
76
77 Note that the pressure threshold to trigger a logical tip event may be zero
78 on some devices. On tools without pressure sensitivity, determining when a
79 tip is down is device-specific.
80
81 .. _tablet-relative-motion:
82
83 ------------------------------------------------------------------------------
84 Relative motion for tablet tools
85 ------------------------------------------------------------------------------
86
87 libinput calculates the relative motion vector for each event and converts
88 it to the same coordinate space that a normal mouse device would use. For
89 the caller, this means that the delta coordinates returned by
90 **libinput_event_tablet_tool_get_dx()** and
91 **libinput_event_tablet_tool_get_dy()** can be used identical to the delta
92 coordinates from any other pointer event. Any resolution differences between
93 the x and y axes are accommodated for, a delta of N/N represents a 45 degree
94 diagonal move on the tablet.
95
96 The delta coordinates are available for all tablet events, it is up to the
97 caller to decide when a tool should be used in relative mode. It is
98 recommended that mouse and lens cursor tool default to relative mode and
99 all pen-like tools to absolute mode.
100
101 If a tool in relative mode must not use pointer acceleration, callers
102 should use the absolute coordinates returned by
103 **libinput_event_tablet_tool_get_x()** and libinput_event_tablet_tool_get_y()
104 and calculate the delta themselves. Callers that require exact physical
105 distance should also use these functions to calculate delta movements.
106
107 .. _tablet-axes:
108
109 ------------------------------------------------------------------------------
110 Special axes on tablet tools
111 ------------------------------------------------------------------------------
112
113 A tablet tool usually provides additional information beyond x/y positional
114 information and the tip state. A tool may provide the distance to the tablet
115 surface and the pressure exerted on the tip when in contact. Some tablets
116 additionally provide tilt information along the x and y axis.
117
118 .. figure:: tablet-axes.svg
119 :align: center
120
121 Illustration of the distance, pressure and tilt axes
122
123 The granularity and precision of the distance and pressure axes varies
124 between tablet devices and cannot usually be mapped into a physical unit.
125 libinput normalizes distance and pressure into the [0, 1] range.
126
127 While the normalization range is identical for these axes, a caller should
128 not interpret identical values as identical across axes, i.e. a value v1 on
129 the distance axis has no relation to the same value v1 on the pressure axis.
130
131 The tilt axes provide the angle in degrees between a vertical line out of
132 the tablet and the top of the stylus. The angle is measured along the x and
133 y axis, respectively, a positive tilt angle thus means that the stylus' top
134 is tilted towards the logical right and/or bottom of the tablet.
135
136 .. _tablet-fake-proximity:
137
138 ------------------------------------------------------------------------------
139 Handling of proximity events
140 ------------------------------------------------------------------------------
141
142 libinput's **LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY** events notify a caller
143 when a tool comes into sensor range or leaves the sensor range. On some
144 tools this range does not represent the physical range but a reduced
145 tool-specific logical range. If the range is reduced, this is done
146 transparent to the caller.
147
148 For example, the Wacom mouse and lens cursor tools are usually
149 used in relative mode, lying flat on the tablet. Movement typically follows
150 the interaction normal mouse movements have, i.e. slightly lift the tool and
151 place it in a separate location. The proximity detection on Wacom
152 tablets however extends further than the user may lift the mouse, i.e. the
153 tool may not be lifted out of physical proximity. For such tools, libinput
154 provides software-emulated proximity.
155
156 Events from the pad do not require proximity, they may be sent any time.
157
158 .. _tablet-pressure-offset:
159
160 ------------------------------------------------------------------------------
161 Pressure offset on worn-out tools
162 ------------------------------------------------------------------------------
163
164 When a tool is used for an extended period it can wear down physically. A
165 worn-down tool may never return a zero pressure value. Even when hovering
166 above the surface, the pressure value returned by the tool is nonzero,
167 creating a fake surface touch and making interaction with the tablet less
168 predictable.
169
170 libinput automatically detects pressure offsets and rescales the remaining
171 pressure range into the available range, making pressure-offsets transparent
172 to the caller. A tool with a pressure offset will thus send a 0 pressure
173 value for the detected offset and nonzero pressure values for values higher
174 than that offset.
175
176 Some limitations apply to avoid misdetection of pressure offsets,
177 specifically:
178
179 - pressure offset is only detected on proximity in, and if a device is
180 capable of detection distances,
181 - pressure offset is only detected if the distance between the tool and the
182 tablet is high enough,
183 - pressure offset is only used if it is 50% or less of the pressure range
184 available to the tool. A pressure offset higher than 50% indicates either
185 a misdetection or a tool that should be replaced, and
186 - if a pressure value less than the current pressure offset is seen, the
187 offset resets to that value.
188
189 Pressure offsets are not detected on **LIBINPUT_TABLET_TOOL_TYPE_MOUSE**
190 and **LIBINPUT_TABLET_TOOL_TYPE_LENS** tools.
191
192
193 .. _tablet-pressure-range:
194
195 ------------------------------------------------------------------------------
196 Custom tablet tool pressure ranges
197 ------------------------------------------------------------------------------
198
199 On tablets supporting pressure, libinput provides that hardware pressure as
200 a logical range of ``0.0`` up to ``1.0`` for the maximum supported pressure.
201 By default, the hardware range thus maps into the following logical range::
202
203
204 hw minimum hw maximum
205 hw range: |------|-----------------------------------|
206 logical range: |----|-----------------------------------|
207 0.0 | 1.0
208 Tip
209
210 Note that libinput always has some built-in thresholds to filter out erroneous
211 touches with near-zero pressure but otherwise the hardware range maps as-is
212 into the logical range. The :ref:`tip event <tablet-tip>` threshold is defined
213 within this range.
214
215 For some use-cases the full hardware range is not suitable, it may require either
216 too light a pressure for the user to interact or it may require too hard a
217 pressure before the logical maximum is reached. libinput provides
218 the **libinput_tablet_tool_config_pressure_range_set()** function that allows
219 reducing the usable range of the tablet::
220
221 hw minimum hw maximum
222 hw range: |----------|-------------------------------|
223 adjusted range: |------|---------------------|
224 logical range: |----|---------------------|
225 0.0 | 1.0
226 Tip
227
228 A reduced range as shown above will result in
229
230 - all hw pressure below the new minimum to register as logical pressure ``0.0``
231 - all hw pressure above the new maximum to register as logical pressure ``1.0``
232 - the tip event threshold to be relative to the new minimum
233
234 In other words, adjusting the pressure range of a tablet tool is equivalent to
235 reducing the hardware range of said tool. Note that where a custom pressure
236 range is set, detection of :ref:`tablet-pressure-offset` is disabled.
237
238 .. _tablet-serial-numbers:
239
240 ------------------------------------------------------------------------------
241 Tracking unique tools
242 ------------------------------------------------------------------------------
243
244 Some tools provide hardware information that enables libinput to uniquely
245 identify the physical device. For example, tools compatible with the Wacom
246 Intuos 4, Intuos 5, Intuos Pro and Cintiq series are uniquely identifiable
247 through a serial number. libinput does not specify how a tool can be
248 identified uniquely, a caller should use **libinput_tablet_tool_is_unique()** to
249 check if the tool is unique.
250
251 libinput creates a struct libinput_tablet_tool on the first proximity in of
252 this tool. By default, this struct is destroyed on proximity out and
253 re-initialized on the next proximity in. If a caller keeps a reference to
254 the tool by using **libinput_tablet_tool_ref()** libinput re-uses this struct
255 whenever that same physical tool comes into proximity on any tablet
256 recognized by libinput. It is possible to attach tool-specific virtual state
257 to the tool. For example, a graphics program such as the GIMP may assign a
258 specific color to each tool, allowing the artist to use the tools like
259 physical pens of different color. In multi-tablet setups it is also
260 possible to track the tool across devices.
261
262 If the tool does not have a unique identifier, libinput creates a single
263 struct libinput_tablet_tool per tool type on each tablet the tool is used
264 on.
265
266 .. _tablet-tool-types:
267
268 ------------------------------------------------------------------------------
269 Vendor-specific tablet tool types
270 ------------------------------------------------------------------------------
271
272 libinput supports a number of high-level tool types that describe the
273 general interaction expected with the tool. For example, a user would expect
274 a tool of type **LIBINPUT_TABLET_TOOL_TYPE_PEN** to interact with a
275 graphics application taking pressure and tilt into account. The default
276 virtual tool assigned should be a drawing tool, e.g. a virtual pen or brush.
277 A tool of type **LIBINPUT_TABLET_TOOL_TYPE_ERASER** would normally be
278 mapped to an eraser-like virtual tool. See **libinput_tablet_tool_type**
279 for the list of all available tools.
280
281 Vendors may provide more fine-grained information about the tool in use by
282 adding a hardware-specific tool ID. libinput provides this ID to the caller
283 with **libinput_tablet_tool_get_tool_id()** but makes no promises about the
284 content or format of the ID.
285
286 libinput currently supports Wacom-style tool IDs as provided on the Wacom
287 Intuos 3, 4, 5, Wacon Cintiq and Wacom Intuos Pro series. The tool ID can
288 be used to distinguish between e.g. a Wacom Classic Pen or a Wacom Pro Pen.
289 It is the caller's responsibility to interpret the tool ID.
290
291 .. _tablet-bounds:
292
293 ------------------------------------------------------------------------------
294 Out-of-bounds motion events
295 ------------------------------------------------------------------------------
296
297 Some tablets integrated into a screen (e.g. Wacom Cintiq 24HD, 27QHD and
298 13HD series, etc.) have a sensor larger than the display area. libinput uses
299 the range advertised by the kernel as the valid range unless device-specific
300 quirks are present. Events outside this range will produce coordinates that
301 may be negative or larger than the tablet's width and/or height. It is up to
302 the caller to ignore these events.
303
304 .. figure:: tablet-out-of-bounds.svg
305 :align: center
306
307 Illustration of the out-of-bounds area on a tablet
308
309 In the image above, the display area is shown in black. The red area around
310 the display illustrates the sensor area that generates input events. Events
311 within this area will have negative coordinate or coordinates larger than
312 the width/height of the tablet.
313
314 If events outside the logical bounds of the input area are scaled into a
315 custom range with **libinput_event_tablet_tool_get_x_transformed()** and
316 **libinput_event_tablet_tool_get_y_transformed()** the resulting value may be
317 less than 0 or larger than the upper range provided. It is up to the caller
318 to test for this and handle or ignore these events accordingly.
319
320 .. _tablet-pad-buttons:
321
322 ------------------------------------------------------------------------------
323 Tablet pad button numbers
324 ------------------------------------------------------------------------------
325
326 Tablet Pad buttons are numbered sequentially, starting with button 0. Thus
327 button numbers returned by **libinput_event_tablet_pad_get_button_number()**
328 have no semantic meaning, a notable difference to the button codes returned
329 by other libinput interfaces (e.g. **libinput_event_tablet_tool_get_button()**).
330
331 The Linux kernel requires all input events to have semantic event codes,
332 but generic buttons like those on a pad cannot easily be assigned semantic
333 codes. The kernel supports generic codes in the form of BTN_0 through to
334 BTN_9 and additional unnamed space up until code 0x10f. Additional generic
335 buttons are available as BTN_A in the range dedicated for gamepads and
336 joysticks. Thus, tablet with a large number of buttons have to map across
337 two semantic ranges, have to use unnamed kernel button codes or risk leaking
338 into an unrelated range. libinput transparently maps the kernel event codes
339 into a sequential button range on the pad. Callers should use external
340 sources like libwacom to associate button numbers to their position on the
341 tablet.
342
343 Some buttons may have expected default behaviors. For example, on Wacom
344 Intuos Pro series tablets, the button inside the touch ring is expected to
345 switch between modes, see :ref:`tablet-pad-modes`. Callers should use
346 external sources like libwacom to identify which buttons have semantic
347 behaviors.
348
349 .. _tablet-left-handed:
350
351 ------------------------------------------------------------------------------
352 Tablets in left-handed mode
353 ------------------------------------------------------------------------------
354
355 Left-handed mode on tablet devices usually means rotating the physical
356 tablet by 180 degrees to move the tablet pad button area to right side of
357 the tablet. When left-handed mode is enabled on a tablet device (see
358 **libinput_device_config_left_handed_set()**) the tablet tool and tablet pad
359 behavior changes. In left-handed mode, the tools' axes are adjusted
360 so that the origin of each axis remains the logical north-east of
361 the physical tablet. For example, the x and y axes are inverted and the
362 positive x/y coordinates are down/right of the top-left corner of the tablet
363 in its current orientation. On a tablet pad, the ring and strip are
364 similarly adjusted. The origin of the ring and strips remain the top-most
365 point.
366
367 .. figure:: tablet-left-handed.svg
368 :align: center
369
370 Tablet axes in right- and left-handed mode
371
372 Pad buttons are not affected by left-handed mode; the number of each button
373 remains the same even when the perceived physical location of the button
374 changes. This is a conscious design decision:
375
376 - Tablet pad buttons do not have intrinsic semantic meanings. Re-ordering
377 the button numbers would not change any functionality.
378 - Button numbers should not be exposed directly to the user but handled in
379 the intermediate layers. Re-ordering button numbers thus has no
380 user-visible effect.
381 - Re-ordering button numbers may complicate the intermediate layers.
382
383 Left-handed mode is only available on some tablets, some tablets are
384 symmetric and thus do not support left-handed mode. libinput requires
385 libwacom to determine if a tablet is capable of being switched to
386 left-handed mode.
387
388 .. _tablet-pad-modes:
389
390 ------------------------------------------------------------------------------
391 Tablet pad modes
392 ------------------------------------------------------------------------------
393
394 Tablet pad modes are virtual groupings of button, ring and strip
395 functionality. A caller may assign different functionalities depending on
396 the mode the tablet is in. For example, in mode 0 the touch ring may emulate
397 scrolling, in mode 1 the touch ring may emulate zooming, etc. libinput
398 handles the modes and mode switching but does not assign specific
399 functionality to buttons, rings or strips based on the mode. It is up to the
400 caller to decide whether the mode only applies to buttons, rings and strips
401 or only to rings and strips (this is the case with the Wacom OS X and
402 Windows driver).
403
404 The availability of modes on a touchpad usually depends on visual feedback
405 such as LEDs around the touch ring. If no visual feedback is available, only
406 one mode may be available.
407
408 Mode switching is controlled by libinput and usually toggled by one or
409 more buttons on the device. For example, on the Wacom Intuos 4, 5, and
410 Pro series tablets the mode button is the button centered in the touch
411 ring and toggles the modes sequentially. On the Wacom Cintiq 24HD the
412 three buttons next to each touch ring allow for directly changing the
413 mode to the desired setting.
414
415 Multiple modes may exist on the tablet, libinput uses the term "mode group"
416 for such groupings of buttons that share a mode and mode toggle. For
417 example, the Wacom Cintiq 24HD has two separate mode groups, one for the
418 left set of buttons, strips, and touch rings and one for the right set.
419 libinput handles the mode groups independently and returns the mode for each
420 button as appropriate. The mode group is static for the lifetime of the
421 device.
422
423 .. figure:: tablet-intuos-modes.svg
424 :align: center
425
426 Modes on an Intuos Pro-like tablet
427
428 In the image above, the Intuos Pro-like tablet provides 4 LEDs to indicate
429 the currently active modes. The button inside the touch ring cycles through
430 the modes in a clockwise fashion. The upper-right LED indicates that the
431 currently active mode is 1, based on 0-indexed mode numbering.
432 **libinput_event_tablet_pad_get_mode()** would thus return 1 for all button and
433 ring events on this tablet. When the center button is pressed, the mode
434 switches to mode 2, the LED changes to the bottom-right and
435 **libinput_event_tablet_pad_get_mode()** returns 2 for the center button event
436 and all subsequent events.
437
438 .. figure:: tablet-cintiq24hd-modes.svg
439 :align: center
440
441 Modes on an Cintiq 24HD-like tablet
442
443 In the image above, the Cintiq 24HD-like tablet provides 3 LEDs on each side
444 of the tablet to indicate the currently active mode for that group of
445 buttons and the respective ring. The buttons next to the touch ring select
446 the mode directly. The two LEDs indicate that the mode for the left set of
447 buttons is currently 0, the mode for the right set of buttons is currently
448 1, based on 0-indexed mode numbering. **libinput_event_tablet_pad_get_mode()**
449 would thus return 0 for all button and ring events on the left and 1 for all
450 button and ring events on the right. When one of the three mode toggle
451 buttons on the right is pressed, the right mode switches to that button's
452 mode but the left mode remains unchanged.
453
454 .. _tablet-touch-arbitration:
455
456 ------------------------------------------------------------------------------
457 Tablet touch arbitration
458 ------------------------------------------------------------------------------
459
460 "Touch arbitration" is the terminology used when touch events are suppressed
461 while the pen is in proximity. Since it is almost impossible to use a stylus
462 or other tool without triggering touches with the hand holding the tool,
463 touch arbitration serves to reduce the number of accidental inputs.
464 The wacom kernel driver currently provides touch arbitration but for other
465 devices arbitration has to be done in userspace.
466
467 libinput uses the **libinput_device_group** to decide on touch arbitration
468 and automatically discards touch events whenever a tool is in proximity.
469 The exact behavior is device-dependent.
470
471 .. _tablet-area:
472
473 ------------------------------------------------------------------------------
474 Tablet area
475 ------------------------------------------------------------------------------
476
477 External tablet devices such as e.g. the Wacom Intuos series can be configured
478 to reduce the available logical input area. Typically the logical input area
479 is equivalent to the physical input area but it can be reduced with the
480 **libinput_device_config_area_set_rectangle()** call. Once reduced, input
481 events outside the logical input area are ignored and the logical input area
482 acts as if it represented the extents of the physical tablet.
483
484 .. figure:: tablet-area.svg
485 :align: center
486
487 Tablet area configuration example
488
489 In the image above, the area is set to the rectangle 0.25/0.25 to 0.5/0.75.
490 Even though the tool is roughly at the physical position ``0.5 * width`` and
491 ``0.75 * height``, the return values of
492 **libinput_event_tablet_tool_get_x_transformed()** and
493 **libinput_event_tablet_tool_get_y_transformed()** would be close to the
494 maximum provided in this call.
495
496 The size of the tablet reported by **libinput_device_get_size()** always reflects
497 the physical area, not the logical area.
498
499 .. _tablet-eraser-button:
500
501 ------------------------------------------------------------------------------
502 Tablet eraser buttons
503 ------------------------------------------------------------------------------
504
505 Tablet tools come in a variety of forms but the most common one is a
506 pen-like tool. Some of these pen-like tools have a virtual eraser at the
507 tip of the tool - inverting the tool brings the eraser into proximity.
508
509 .. figure:: tablet-eraser-invert.svg
510 :align: center
511
512 An pen-like tool used as pen and as eraser by inverting it
513
514 Having an eraser as a separate tool is beneficial in many applications as the
515 eraser tool can be assigned different functionality (colors, paint tools, etc.)
516 that is easily available.
517
518 However, a large proportion of tablet pens have an "eraser button". By
519 pressing the button the pen switches to be an eraser tool.
520 On the data level this is not done via a button event, instead the firmware
521 will pretend the pen tool going out of proximity and the eraser coming
522 into proximity immediately after - as if the tool was physically inverted.
523
524 .. figure:: tablet-eraser-button.svg
525 :align: center
526
527 An pen-like tool used as pen and as eraser by pressing the eraser button
528
529 Microsoft mandates this behavior (see
530 `Windows Pen States <https://learn.microsoft.com/en-us/windows-hardware/design/component-guidelines/windows-pen-states>`_
531 for details) and thus the overwhelming majority of devices will have
532 an eraser button that virtually inverts the pen.
533
534 Enforcing an eraser button means that users have one button less on the
535 stylus that they would have otherwise. For some users the eraser button
536 is in an inconvenient location, others don't want an eraser button at all.
537
538 libinput provides an eraser button configuration that allows disabling the
539 eraser button and turning it into a normal button event. If the eraser button
540 is disabled, pressing that button will generate a normal tablet tool button
541 event.
542
543 This configuration is only available on pens with an eraser button, not on
544 with an invert-type eraser.