mirror of
https://gitlab.freedesktop.org/libinput/libinput.git
synced 2025-12-25 00:00:14 +01:00
e6cad92005
A better, less ambiguous name than just "datadir" Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
169 lines
7.1 KiB
Text
169 lines
7.1 KiB
Text
/**
|
|
@page trackpoints Trackpoints and Pointing Sticks
|
|
|
|
This page provides an overview of trackpoint handling in libinput, also
|
|
refered to as Pointing Stick or Trackstick. The device itself is usually a
|
|
round plastic stick between the G, H and B keys with a set of buttons below
|
|
the space bar.
|
|
|
|
@image html button-scrolling.svg "A trackpoint"
|
|
|
|
libinput always treats the buttons below the space bar as the buttons that
|
|
belong to the trackpoint even on the few laptops where the buttons are not
|
|
physically wired to the trackpoint device anyway, see @ref t440_support.
|
|
|
|
Trackpoint devices have @ref button_scrolling enabled by default. This may
|
|
interfer with middle-button dragging, if middle-button dragging is required
|
|
by a user then button scrolling must be disabled.
|
|
|
|
@section trackpoint_range Motion range on trackpoints
|
|
|
|
It is difficult to associate motion on a trackpoint with a physical
|
|
reference. Unlike mice or touchpads where the motion can be
|
|
measured in mm, the trackpoint only responds to pressure. Without special
|
|
equipment it is impossible to measure identical pressure values across
|
|
multiple laptops.
|
|
|
|
The values provided by a trackpoint are motion deltas, usually corresponding
|
|
to the pressure applied to the trackstick. For example, pressure towards the
|
|
screen on a laptop provides negative y deltas. The reporting rate increases
|
|
as the pressure increases and once events are reported at the maximum rate,
|
|
the delta values increase. The figure below shows a rough illustration of
|
|
this concept. As the pressure
|
|
decreases, the delta decrease first, then the reporting rate until the
|
|
trackpoint is in a neutral state and no events are reported. Trackpoint data
|
|
is hart to generalize, see
|
|
<a href="https://who-t.blogspot.com/2018/06/observations-on-trackpoint-input-data.html">
|
|
Observations on trackpoint input data</a> for more details.
|
|
|
|
@image html trackpoint-delta-illustration.svg Illustration of the relationship between reporting rate and delta values on a trackpoint
|
|
|
|
The delta range itself can vary greatly between laptops, some devices send a
|
|
maximum delta value of 30, others can go beyond 100. However, the useful
|
|
delta range is a fraction of the maximum range. It is uncomfortable to exert
|
|
sufficient pressure to even get close to the maximum ranges.
|
|
|
|
@section trackpoint_multiplier The magic trackpoint multiplier
|
|
|
|
To accomodate for the wildly different input data on trackpoint, libinput
|
|
uses a multiplier that is applied to input deltas. Trackpoints that send
|
|
comparatively high deltas can be "slowed down", trackpoints that send low
|
|
deltas can be "sped up" to match the expected range. The actual acceleration
|
|
profile is applied to these pre-multiplied deltas.
|
|
|
|
Given a trackpoint delta (dx, dy), a multiplier M and a pointer acceleration
|
|
function f(dx, dy) → (dx', dy'), the algorithm is effectively:
|
|
@verbatim
|
|
f(M * dx, M * dy) → (dx', dy')
|
|
@endverbatim
|
|
|
|
The magic trackpoint multiplier **is not user visible configuration**. It is
|
|
part of the @ref device-quirks system and provided once per device.
|
|
User-specific preferences can be adjusted with the pointer acceleration speed
|
|
setting libinput_device_config_accel_set_speed().
|
|
|
|
@subsection trackpoint_multiplier_adjustment Adjusting the magic trackpoint multiplier
|
|
|
|
This section only applies if:
|
|
- the trackpoint default speed (speed setting 0) is unusably slow or
|
|
unusably fast, **and**
|
|
- the lowest speed setting (-1) is still too fast **or** the highest speed
|
|
setting is still too slow, **and**
|
|
- the @ref device-quirks for this device do not list a trackpoint multiplier
|
|
(see @ref device-quirks-debugging)
|
|
|
|
If the only satisfactory speed settings are less than -0.75 or greater than
|
|
0.75, a multiplier *may* be required.
|
|
|
|
A specific multiplier will apply to **all users with the same laptop
|
|
model**, so proceed with caution. You must be capable/willing to adjust
|
|
device quirks, build libinput from source and restart the session frequently
|
|
to adjust the multiplier. If this does not apply, wait for someone else with
|
|
the same hardware to do this.
|
|
|
|
Finding the correct multiplier is difficult and requires some trial and
|
|
error. The default multiplier is always 1.0. A value between 0.0 and 1.0
|
|
slows the trackpoint down, a value above 1.0 speeds the trackpoint up.
|
|
Values below zero are invalid.
|
|
|
|
@note The multiplier is not a configuration to adjust to personal
|
|
preferences. The multiplier normalizes the input data into a range that can
|
|
then be configured with the speed setting.
|
|
|
|
To adjust the local multiplier, first @ref building_libinput
|
|
"build libinput from git master". It is not required to install libinput
|
|
from git. The below assumes that all @ref building_dependencies are already
|
|
installed.
|
|
|
|
@verbatim
|
|
$ cd path/to/libinput.git
|
|
|
|
# Use an approximate multiplier in the quirks file
|
|
$ cat > quirks/99-trackpont-override.quirks <<EOF
|
|
[Trackpoint Override]
|
|
MatchUdevType=pointingstick
|
|
AttrTrackpointMultiplier=1.0
|
|
EOF
|
|
|
|
# Use your trackpoint's event node. If the Attr does not show up
|
|
# then the quirk does not apply to your trackpoint.
|
|
$ ./builddir/libinput quirks list /dev/input/event18
|
|
AttrTrackpointMultiplier=1.0
|
|
|
|
# Now start a GUI program to debug the trackpoint speed.
|
|
# ESC closes the debug GUI
|
|
$ sudo ./builddir/libinput debug-gui
|
|
@endverbatim
|
|
|
|
Replace the multiplier with an approximate value and the event node with
|
|
your trackpoint's event node. Try to use trackpoint and verify the
|
|
multiplier is good enough. If not, adjust the `.quirks` file and re-run the
|
|
`libinput debug-gui`. Note that the `libinput debug-gui` always feels
|
|
less responsive than libinput would behave in a normal install.
|
|
|
|
Once the trackpoint behaves correctly you are ready to test the system
|
|
libinput:
|
|
|
|
@verbatim
|
|
$ sudo cp quirks/99-trackpoint-override.quirks /etc/libinput/local-overrides.quirks
|
|
@endverbatim
|
|
|
|
Now verify the override is seen by the system libinput
|
|
@verbatim
|
|
$ libinput quirks list
|
|
AttrTrackpointMultiplier=1.0
|
|
@endverbatim
|
|
|
|
If the multiplier is listed, restart your Wayland session or X server. The
|
|
new multiplier is now applied to your trackpoint.
|
|
|
|
If the trackpoint behavior is acceptable, you are ready to submit this file
|
|
upstream. First, find add a more precise match for the device so it only
|
|
applies to the built-in trackpoint on your laptop model. Usually a
|
|
variation of the following is sufficient:
|
|
|
|
@verbatim
|
|
[Trackpoint Override]
|
|
MatchUdevType=pointingstick
|
|
MatchName=*TPPS/2 IBM TrackPoint*
|
|
MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadT440p*
|
|
AttrTrackpointMultiplier=1.0
|
|
@endverbatim
|
|
|
|
Look at your `/sys/class/dmi/id/modalias` file for the values to add. Verify
|
|
that `libinput quirks list` still shows the `AttrTrackpointMultiplier`. If
|
|
it does, then you should @ref reporting_bugs "report a bug" with the contents of
|
|
the file. Alternatively, file a merge request with the data added.
|
|
|
|
|
|
@section trackpoint_range_measure Measuring the trackpoint range
|
|
|
|
This section only applied to libinput version 1.9.x, 1.10.x, and 1.11.x and
|
|
has been removed. See @ref trackpoint_multiplier for versions 1.12.x and later.
|
|
|
|
If using libinput version 1.11.x or earlier, please see
|
|
<a href="https://wayland.freedesktop.org/libinput/doc/1.11.0/trackpoints.html#trackpoint_range_measure">
|
|
the 1.11.0 documentation</a>
|
|
|
|
*/
|
|
|