Debian Codegraph @

doc/user/trackpoint-configuration.rst

raw
1 .. _trackpoint_configuration:
2
3 ==============================================================================
4 Trackpoint configuration
5 ==============================================================================
6
7 The sections below describe the trackpoint magic multiplier and how to apply
8 it to your local device. See :ref:`trackpoint_range` for an explanation on
9 why this multiplier is needed.
10
11 .. note:: The magic trackpoint multiplier **is not user visible configuration**. It is
12 part of the :ref:`device-quirks` system and provided once per device.
13
14 User-specific preferences can be adjusted with the
15 :ref:`config_pointer_acceleration` setting.
16
17 .. _trackpoint_multiplier:
18
19 ------------------------------------------------------------------------------
20 The magic trackpoint multiplier
21 ------------------------------------------------------------------------------
22
23 To accommodate for the wildly different input data on trackpoint, libinput
24 uses a multiplier that is applied to input deltas. Trackpoints that send
25 comparatively high deltas can be "slowed down", trackpoints that send low
26 deltas can be "sped up" to match the expected range. The actual acceleration
27 profile is applied to these pre-multiplied deltas.
28
29 Given a trackpoint delta ``(dx, dy)``, a multiplier ``M`` and a pointer acceleration
30 function ``f(dx, dy) → (dx', dy')``, the algorithm is effectively:
31
32 ::
33
34 f(M * dx, M * dy) → (dx', dy')
35
36 .. _trackpoint_multiplier_adjustment:
37
38 ..............................................................................
39 Adjusting the magic trackpoint multiplier
40 ..............................................................................
41
42 This section only applies if:
43
44 - the trackpoint default speed (speed setting 0) is unusably slow or
45 unusably fast, **and**
46 - the lowest speed setting (-1) is still too fast **or** the highest speed
47 setting is still too slow, **and**
48 - the :ref:`device-quirks` for this device do not list a trackpoint multiplier
49 (see :ref:`device-quirks-debugging`)
50
51 If the only satisfactory speed settings are less than -0.75 or greater than
52 0.75, a multiplier *may* be required.
53
54 A specific multiplier will apply to **all users with the same laptop
55 model**, so proceed with caution. You must be capable/willing to adjust
56 device quirks, build libinput from source and restart the session frequently
57 to adjust the multiplier. If this does not apply, wait for someone else with
58 the same hardware to do this.
59
60 Finding the correct multiplier is difficult and requires some trial and
61 error. The default multiplier is always 1.0. A value between 0.0 and 1.0
62 slows the trackpoint down, a value above 1.0 speeds the trackpoint up.
63 Values below zero are invalid.
64
65 .. warning:: The multiplier is not a configuration to adjust to personal
66 preferences. The multiplier normalizes the input data into a range that
67 can then be configured with the speed setting.
68
69 To adjust the local multiplier, first
70 :ref:`build libinput from git master <building_libinput>`. It is not
71 required to install libinput from git. The below assumes that all
72 :ref:`building_dependencies` are already
73 installed.
74
75
76 ::
77
78 $ cd path/to/libinput.git
79
80 # Use an approximate multiplier in the quirks file
81 $ cat > quirks/99-trackpoint-override.quirks <<EOF
82 [Trackpoint Override]
83 MatchUdevType=pointingstick
84 AttrTrackpointMultiplier=1.0
85 EOF
86
87 # Use your trackpoint's event node. If the Attr does not show up
88 # then the quirk does not apply to your trackpoint.
89 $ ./builddir/libinput quirks list /dev/input/event18
90 AttrTrackpointMultiplier=1.0
91
92 # Now start a GUI program to debug the trackpoint speed.
93 # ESC closes the debug GUI
94 $ sudo ./builddir/libinput debug-gui
95
96
97 Replace the multiplier with an approximate value and the event node with
98 your trackpoint's event node. Try to use trackpoint and verify the
99 multiplier is good enough. If not, adjust the ``.quirks`` file and re-run the
100 ``libinput debug-gui``. Note that the ``libinput debug-gui`` always feels
101 less responsive than libinput would behave in a normal install.
102
103 Once the trackpoint behaves correctly you are ready to test the system
104 libinput:
105
106
107 ::
108
109 $ sudo cp quirks/99-trackpoint-override.quirks /etc/libinput/local-overrides.quirks
110
111
112 Now verify the override is seen by the system libinput
113
114 ::
115
116 $ libinput quirks list
117 AttrTrackpointMultiplier=1.0
118
119
120 If the multiplier is listed, restart your Wayland session or X server. The
121 new multiplier is now applied to your trackpoint.
122
123 If the trackpoint behavior is acceptable, you are ready to submit this file
124 upstream. First, find add a more precise match for the device so it only
125 applies to the built-in trackpoint on your laptop model. Usually a
126 variation of the following is sufficient:
127
128
129 ::
130
131 [Trackpoint Override]
132 MatchUdevType=pointingstick
133 MatchName=*TPPS/2 IBM TrackPoint*
134 MatchDMIModalias=dmi:*:svnLENOVO:*:pvrThinkPadT440p:*
135 AttrTrackpointMultiplier=1.0
136
137
138 Look at your ``/sys/class/dmi/id/modalias`` file for the values to add. Verify
139 that ``libinput quirks list`` still shows the ``AttrTrackpointMultiplier``. If
140 it does, then you should :ref:`report a bug <reporting_bugs>` with the contents of
141 the file. Alternatively, file a merge request with the data added.
142
143
144 .. _trackpoint_range_measure:
145
146 ------------------------------------------------------------------------------
147 Measuring the trackpoint range
148 ------------------------------------------------------------------------------
149
150 This section only applied to libinput version 1.9.x, 1.10.x, and 1.11.x and
151 has been removed. See :ref:`trackpoint_multiplier` for versions 1.12.x and later.
152
153 If using libinput version 1.11.x or earlier, please see
154 `the 1.11.0 documentation <https://wayland.freedesktop.org/libinput/doc/1.11.0/trackpoints.html#trackpoint_range_measure>`_