Merge branch 'wip/custom-pointer-acceleration-function-v2'

1 files changed, 56 insertions, 0 deletions

diff --git a/src/libinput.h b/src/libinput.h
index 828cf6b4..857dcdfa 100644
--- a/src/libinput.h
+++ b/src/libinput.h
@@ -4494,6 +4494,12 @@ libinput_device_config_accel_is_available(struct libinput_device *device);
  * range. libinput picks the semantically closest acceleration step if the
  * requested value does not match a discrete setting.
  *
+ * If the current acceleration profile is @ref
+ * LIBINPUT_CONFIG_ACCEL_PROFILE_DEVICE_SPEED_CURVE, the behavior of the
+ * device will not change but future calls to
+ * libinput_device_config_accel_get_speed() will reflect the updated speed
+ * setting.
+ *
  * @param device The device to configure
  * @param speed The normalized speed, in a range of [-1, 1]
  *
@@ -4544,6 +4550,44 @@ libinput_device_config_accel_get_default_speed(struct libinput_device *device);
 
 /**
  * @ingroup config
+ *
+ * Sets a curve point on the custom acceleration function for this device.
+ * This function must be called after setting the type of the acceleration
+ * to @ref LIBINPUT_CONFIG_ACCEL_PROFILE_DEVICE_SPEED_CURVE and sets
+ * exactly one point on the device's acceleration curve.
+ *
+ * This function must be called multiple times to define a full acceleration
+ * curve. libinput uses linear interpolation between each defined curve
+ * point to calculate the appropriate factor. Any speed below or above the
+ * lowest or highest point defined is capped to the factor at the lowest or
+ * highest point, respectively. See @ref ptraccel-device-speed for a
+ * detailed explanation on this behavior.
+ *
+ * The behavior of the acceleration function depends on the type of the
+ * profile:
+ * - @ref LIBINPUT_CONFIG_ACCEL_PROFILE_DEVICE_SPEED_CURVE : the input data
+ *   a is velocity in device units per millisecond, f(a) is a unitless
+ *   factor. This factor is applied to the incoming delta so that a delta
+ *   (x, y) is  accelerated to the delta (f(a) * x, f(a) *y). The velocity
+ *   is calculated by libinput based on the current and previous deltas and
+ *   their timestamps. See @ref ptraccel-device-speed for details.
+ *
+ * @note libinput has a maximum limit for how many curve points may be set
+ * and will quietly drop curve points exceeding this limit. This limit is
+ * not expected to be hit by any reasonable caller.
+ *
+ * Submitting a curve point with the same value as a previous curve point
+ * overwrites that value. There is no facility to remove curve points,
+ * switch the device to a different profile and back again to reset.
+ *
+ * @return 0 on success or nonzero otherwise
+ */
+enum libinput_config_status
+libinput_device_config_accel_set_curve_point(struct libinput_device *device,
+					     double a, double fa);
+
+/**
+ * @ingroup config
  */
 enum libinput_config_accel_profile {
 	/**
@@ -4565,6 +4609,11 @@ enum libinput_config_accel_profile {
 	 * on the input speed. This is the default profile for most devices.
 	 */
 	LIBINPUT_CONFIG_ACCEL_PROFILE_ADAPTIVE = (1 << 1),
+	/**
+	 * A custom user-provided profile. See
+	 * libinput_acceleration_profile_set_curve_point() for details.
+	 */
+	LIBINPUT_CONFIG_ACCEL_PROFILE_DEVICE_SPEED_CURVE = (1 << 2),
 };
 
 /**
@@ -4586,6 +4635,13 @@ libinput_device_config_accel_get_profiles(struct libinput_device *device);
  * Set the pointer acceleration profile of this pointer device to the given
  * mode.
  *
+ * If the given profile is
+ * @ref LIBINPUT_CONFIG_ACCEL_PROFILE_DEVICE_SPEED_CURVE and it is
+ * different to the current profile, the acceleration curve is reset to an
+ * implementation-defined curve. The caller should call
+ * libinput_device_config_accel_set_curve_point() to
+ * define the curve points of the acceleration profile.
+ *
  * @param device The device to configure
  * @param mode The mode to set the device to.
  *