From f3de97f6d0c9165bc5368a15f69dba23fe78e83f Mon Sep 17 00:00:00 2001
From: Rick Choi <jinhwanlazy@gmail.com>
Date: Sun, 27 Oct 2024 13:02:35 +0900
Subject: [PATCH] expose option cursor_trail_distance_threshold

---
 kitty/cursor_trail.c           |  5 ++---
 kitty/options/definition.py    | 12 +++++++++++-
 kitty/options/parse.py         |  3 +++
 kitty/options/to-c-generated.h | 15 +++++++++++++++
 kitty/options/types.py         |  2 ++
 kitty/state.h                  |  1 +
 6 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/kitty/cursor_trail.c b/kitty/cursor_trail.c
index 9b1a2dd42..62da6ee84 100644
--- a/kitty/cursor_trail.c
+++ b/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;
         }
     }
diff --git a/kitty/options/definition.py b/kitty/options/definition.py
index bcf93f8cd..4193094f1 100644
--- a/kitty/options/definition.py
+++ b/kitty/options/definition.py
@@ -379,8 +379,18 @@ Adjust these values to control how quickly the cursor trail fades away.
 ''',
     )
 
-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')
diff --git a/kitty/options/parse.py b/kitty/options/parse.py
index 3953912b5..754f6997e 100644
--- a/kitty/options/parse.py
+++ b/kitty/options/parse.py
@@ -937,6 +937,9 @@ class Parser:
     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)
 
diff --git a/kitty/options/to-c-generated.h b/kitty/options/to-c-generated.h
index 0dd7f7345..92c46677f 100644
--- a/kitty/options/to-c-generated.h
+++ b/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);
diff --git a/kitty/options/types.py b/kitty/options/types.py
index 0b35668c0..81bc04f4d 100644
--- a/kitty/options/types.py
+++ b/kitty/options/types.py
@@ -336,6 +336,7 @@ option_names = (  # {{{
  '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
diff --git a/kitty/state.h b/kitty/state.h
index 6e9619796..4c5a6d6c1 100644
--- a/kitty/state.h
+++ b/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;