expose option cursor_trail_distance_threshold

kitty/cursor_trail.c

@@ -52,11 +52,10 @@ should_skip_cursor_trail_update(CursorTrail *ct, Window *w, OSWindow *os_window)
         return true;
     }
 
-    int distance_threshold = 2;  // make it option
-    if (distance_threshold > 0 && !ct->needs_render) {
+    if (OPT(cursor_trail_distance_threshold) > 0 && !ct->needs_render) {
         int dx = (int)round((ct->corner_x[0] - EDGE(x, 1)) / WD.dx);
         int dy = (int)round((ct->corner_y[0] - EDGE(y, 0)) / WD.dy);
-        if (abs(dx) + abs(dy) <= distance_threshold) {
+        if (abs(dx) + abs(dy) <= OPT(cursor_trail_distance_threshold)) {
             return true;
         }
     }

kitty/options/definition.py

@@ -379,8 +379,18 @@
 ''',
     )
 
-egr()  # }}}
+opt('cursor_trail_distance_threshold', '2',
+    option_type='positive_int', ctype='int',
+    long_text='''
+Set the distance threshold for updating the cursor trail. This option accepts a
+positive integer value that represents the minimum distance (in cell units) the
+cursor must move before the trail is updated. When the cursor moves less than
+this threshold, the trail update is skipped, reducing unnecessary cursor trail
+animation.
+'''
+    )
 
+egr()  # }}}
 
 # scrollback {{{
 agr('scrollback', 'Scrollback')

kitty/options/parse.py

@@ -937,6 +937,9 @@ def cursor_trail(self, val: str, ans: typing.Dict[str, typing.Any]) -> None:
     def cursor_trail_decay(self, val: str, ans: typing.Dict[str, typing.Any]) -> None:
         ans['cursor_trail_decay'] = cursor_trail_decay(val)
 
+    def cursor_trail_distance_threshold(self, val: str, ans: typing.Dict[str, typing.Any]) -> None:
+        ans['cursor_trail_distance_threshold'] = positive_int(val)
+
     def cursor_underline_thickness(self, val: str, ans: typing.Dict[str, typing.Any]) -> None:
         ans['cursor_underline_thickness'] = positive_float(val)
 

kitty/options/to-c-generated.h

@@ -187,6 +187,19 @@ convert_from_opts_cursor_trail_decay(PyObject *py_opts, Options *opts) {
     Py_DECREF(ret);
 }
 
+static void
+convert_from_python_cursor_trail_distance_threshold(PyObject *val, Options *opts) {
+    opts->cursor_trail_distance_threshold = PyLong_AsLong(val);
+}
+
+static void
+convert_from_opts_cursor_trail_distance_threshold(PyObject *py_opts, Options *opts) {
+    PyObject *ret = PyObject_GetAttrString(py_opts, "cursor_trail_distance_threshold");
+    if (ret == NULL) return;
+    convert_from_python_cursor_trail_distance_threshold(ret, opts);
+    Py_DECREF(ret);
+}
+
 static void
 convert_from_python_scrollback_indicator_opacity(PyObject *val, Options *opts) {
     opts->scrollback_indicator_opacity = PyFloat_AsFloat(val);
@@ -1153,6 +1166,8 @@ convert_opts_from_python_opts(PyObject *py_opts, Options *opts) {
     if (PyErr_Occurred()) return false;
     convert_from_opts_cursor_trail_decay(py_opts, opts);
     if (PyErr_Occurred()) return false;
+    convert_from_opts_cursor_trail_distance_threshold(py_opts, opts);
+    if (PyErr_Occurred()) return false;
     convert_from_opts_scrollback_indicator_opacity(py_opts, opts);
     if (PyErr_Occurred()) return false;
     convert_from_opts_scrollback_pager_history_size(py_opts, opts);

kitty/options/types.py

@@ -336,6 +336,7 @@
  'cursor_text_color',
  'cursor_trail',
  'cursor_trail_decay',
+ 'cursor_trail_distance_threshold',
  'cursor_underline_thickness',
  'default_pointer_shape',
  'detect_urls',
@@ -514,6 +515,7 @@ class Options:
     cursor_text_color: typing.Optional[kitty.fast_data_types.Color] = Color(17, 17, 17)
     cursor_trail: int = 0
     cursor_trail_decay: typing.Tuple[float, float] = (0.1, 0.3)
+    cursor_trail_distance_threshold: int = 2
     cursor_underline_thickness: float = 2.0
     default_pointer_shape: choices_for_default_pointer_shape = 'beam'
     detect_urls: bool = True

kitty/state.h

@@ -49,6 +49,7 @@ typedef struct {
     monotonic_t cursor_trail;
     float cursor_trail_decay_fast;
     float cursor_trail_decay_slow;
+    float cursor_trail_distance_threshold;
     unsigned int url_style;
     unsigned int scrollback_pager_history_size;
     bool scrollback_fill_enlarged_window;