From 4ff6e6058d60128ebe43bc1ca4ae3d2b42455e9d Mon Sep 17 00:00:00 2001 From: Yinon Burgansky Date: Wed, 16 Aug 2023 20:13:39 +0300 Subject: [PATCH] docs: improve custom pointer acceleration documentation. - Explain calculation made by the driver. - Provide detailed example with a plot for a custom function. - Fix inaccurate explanation of unit values. Signed-off-by: Yinon Burgansky --- doc/user/meson.build | 1 + doc/user/pointer-acceleration.rst | 32 +- doc/user/svg/ptraccel-custom.svg | 1067 +++++++++++++++++++++++++++++ 3 files changed, 1095 insertions(+), 5 deletions(-) create mode 100644 doc/user/svg/ptraccel-custom.svg diff --git a/doc/user/meson.build b/doc/user/meson.build index 86de6981..4609eb65 100644 --- a/doc/user/meson.build +++ b/doc/user/meson.build @@ -110,6 +110,7 @@ src_rst = files( 'svg/palm-detection.svg', 'svg/pinch-gestures.svg', 'svg/pinch-gestures-softbuttons.svg', + 'svg/ptraccel-custom.svg', 'svg/ptraccel-linear.svg', 'svg/ptraccel-low-dpi.svg', 'svg/ptraccel-touchpad.svg', diff --git a/doc/user/pointer-acceleration.rst b/doc/user/pointer-acceleration.rst index 211bd469..13b33cc2 100644 --- a/doc/user/pointer-acceleration.rst +++ b/doc/user/pointer-acceleration.rst @@ -20,7 +20,7 @@ Pointer acceleration profiles The profile decides the general method of pointer acceleration. libinput currently supports three profiles: **"adaptive"**, **"flat"** and -**custom**. +**"custom"**. - The **adaptive** profile is the default profile for all devices and takes the current speed of the device into account when deciding on acceleration. @@ -231,18 +231,40 @@ limit on how many points may be added. Thus the points defining the custom function are: ``(0 * step, f[0]), (1 * step, f[1]), ..., ((n-1) * step, f[n-1])`` -where ``f`` is a list of ``n`` unitless values defining the acceleration -factor for each velocity. +where ``f`` is a list of ``n`` values defining the output velocity for each +input velocity. +The acceleration factor is defined by the ratio of the output velocity to the +input velocity. When a velocity value does not lie exactly on those points, a linear interpolation of the two closest points will be calculated. When a velocity value is greater than the max point defined, a linear extrapolation of the two biggest points will be calculated. +the calculation made by libinput: :: + + input_delta = device delta units + delta_time = time in ms since last input_delta + input_speed = hypot(input_delta) / delta_time + output_speed = user_custom_function(input_speed) + acceleration_factor = output_speed / input_speed + output_delta = input_delta * acceleration_factor + An example is the curve of ``0.0, 1.0`` with a step of ``1.0``. This curve -is the equivalent of the flat acceleration profile with any input speed `N` -mapped to the same pointer speed `N`. The curve `1.0, 1.0` neutralizes +is the equivalent of the flat acceleration profile with any input speed ``N`` +mapped to the same pointer speed ``N``. The curve ``1.0, 1.0`` neutralizes any input speed differences and results in a fixed pointer speed. +Another example is the custom acceleration function ``x**2``, +sampling the function at ``4`` points up to +a maximum input speed of ``9`` will give us a custom function with +a step of ``3`` and points ``[0.0, 9.0, 36.0, 81.0]``: + +.. figure:: ptraccel-custom.svg + :align: center + +More sampled points can be added to improve the accuracy of the user custom +function. + Supported Movement types: +---------------+---------------------------------+----------------------+ diff --git a/doc/user/svg/ptraccel-custom.svg b/doc/user/svg/ptraccel-custom.svg new file mode 100644 index 00000000..abcc5a1b --- /dev/null +++ b/doc/user/svg/ptraccel-custom.svg @@ -0,0 +1,1067 @@ + + + + + + + + 2023-08-16T19:10:50.848529 + image/svg+xml + + + Matplotlib v3.7.2, https://matplotlib.org/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- 2.34.1