From bc9d0b87e33fd5d3cf91d242f521fc265d276fe0 Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Thu, 5 Nov 2026 08:43:37 +0530 Subject: [PATCH] Custom shaders: Add command and alternate screen events and uniforms Add the command-start, command-finish, alternate-screen-enter and alternate-screen-exit events, which fire for changes in the active window, and the active_window_command_running, active_window_alternate_screen, active_window_command_state_age and active_window_alternate_screen_age fields to KittyCustomShaderData, so shaders can show effects while commands run and hide them in full screen programs. --- docs/changelog.rst | 5 +++++ docs/custom-shaders.rst | 38 ++++++++++++++++++++++++++++++++ kitty/child-monitor.c | 20 +++++++++++++++++ kitty/fast_data_types.pyi | 5 +++++ kitty/screen.c | 23 ++++++++++++++++++- kitty/screen.h | 9 ++++++++ kitty/shaders.c | 20 +++++++++++++++++ kitty/shaders/custom/types.slang | 17 ++++++++++++++ kitty/shaders/slang.py | 4 ++++ kitty/state.h | 7 ++++++ kitty_tests/screen.py | 38 ++++++++++++++++++++++++++++++++ kitty_tests/slang.py | 3 +++ 12 files changed, 188 insertions(+), 1 deletion(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index ca85c3b5d..4d3f7601a 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -222,6 +222,11 @@ Detailed list of changes 0.50.1 [unreleased] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- :doc:`Custom shaders `: Add the ``command-start``, + ``command-finish``, ``alternate-screen-enter`` and ``alternate-screen-exit`` + events and uniforms for whether a command is running and whether the + alternate screen is in use in the active window + - :doc:`choose-files `: Fix concurrent custom preview commands occasionally receiving the path of a different file. diff --git a/docs/custom-shaders.rst b/docs/custom-shaders.rst index 1f26229c6..46739da2a 100644 --- a/docs/custom-shaders.rst +++ b/docs/custom-shaders.rst @@ -612,12 +612,50 @@ be combined with ``|`` — any one of them will trigger the action. - The cursor trail stops moving. Typically used as an ``animation_stop`` event paired with ``cursor-trail-move`` as the start event. + * - ``command-start`` + - A command starts running in the active window. Requires + :ref:`shell integration `. Whether a command is + running is available in ``d.active_window_command_running`` and the + time since it started in ``d.active_window_command_state_age``. + + * - ``command-finish`` + - A command finishes running in the active window. Requires + :ref:`shell integration `. + + * - ``alternate-screen-enter`` + - The active window switches to the alternate screen, which is used by + full screen programs such as editors and pagers. Whether the + alternate screen is in use is available in + ``d.active_window_alternate_screen``. + + * - ``alternate-screen-exit`` + - The active window switches back to the main screen. + * - ``user:`` - Sent by the :ac:`shader_event` action, typically from a mapping, see :ref:`custom_shader_mappings`. ```` can be any combination of letters, digits, underscores, hyphens and periods, up to 63 characters. A pipeline can use up to 48 different user events. +The command and alternate screen events only fire for changes in the active +window. Switching to another window fires ``window-focus-in`` instead, after +which ``d.active_window_command_running`` and +``d.active_window_alternate_screen`` describe the new window. For example, to +fade in an effect while a command runs and fade it out when the command +finishes:: + + startgroup + animation_start command-start + animation_stop command-finish + animation_duration 300 + animation_reverse yes + shaders my-command-running-effect + endgroup + +The shader can multiply its effect by ``1 - d.active_window_alternate_screen`` +to hide it while a full screen program such as an editor or a pager, even one +started by another program as with ``git log``, is running. + Note that if both a start event and a focus-out event fire in the same frame (for example, a mouse click that simultaneously moves focus away), the focus-out takes priority and the animation is not (re-)started. diff --git a/kitty/child-monitor.c b/kitty/child-monitor.c index 858c57b5b..a6664efa6 100644 --- a/kitty/child-monitor.c +++ b/kitty/child-monitor.c @@ -962,6 +962,26 @@ prepare_to_render_os_window( if (global_state.ime_used && os_window->is_focused) sync_ime_position_with_cursor(os_window, w); set_os_window_title_from_window(w, os_window); *active_window_bg = window_bg; + { + // Fire events for shell integration command and alternate screen changes + // in the active window that happened since the last check. This is just + // a few integer comparisons per frame. The check time includes the + // change times seen, as input can be parsed after now was captured. + const Screen *scr = WD.screen; + const monotonic_t since = os_window->screen_state_checked_at; + monotonic_t latest = now; +#define CHECK(field, event) \ + if (scr->field > since) { \ + os_window->shader_anim_event_registry |= (1u << SHADER_ANIM_EVENT_##event); \ + latest = MAX(latest, scr->field); \ + } + CHECK(command_state.started_at, COMMAND_START); + CHECK(command_state.finished_at, COMMAND_FINISH); + CHECK(alternate_screen.entered_at, ALTERNATE_SCREEN_ENTER); + CHECK(alternate_screen.exited_at, ALTERNATE_SCREEN_EXIT); +#undef CHECK + os_window->screen_state_checked_at = MAX(since, latest); + } if (OPT(cursor_trail)) { if (os_window->last_active_tab != os_window->active_tab && os_window->last_active_tab < os_window->num_tabs) { tab->cursor_trail = os_window->tabs[os_window->last_active_tab].cursor_trail; diff --git a/kitty/fast_data_types.pyi b/kitty/fast_data_types.pyi index b3ffe994f..c727e6510 100644 --- a/kitty/fast_data_types.pyi +++ b/kitty/fast_data_types.pyi @@ -1137,6 +1137,11 @@ class Screen: cursor_visible: bool scrolled_by: int pixel_scroll_offset_y: int + command_running: bool + command_started_at: int + command_finished_at: int + alternate_screen_entered_at: int + alternate_screen_exited_at: int cursor: Cursor disable_ligatures: int cursor_key_mode: bool diff --git a/kitty/screen.c b/kitty/screen.c index fa3fc8e54..7b4f41dbf 100644 --- a/kitty/screen.c +++ b/kitty/screen.c @@ -1982,7 +1982,9 @@ screen_toggle_screen_buffer(Screen *self, bool save_cursor, bool clear_alt_scree self->grman = self->alt_grman; screen_cursor_position(self, 1, 1); cursor_reset(self->cursor); + self->alternate_screen.entered_at = monotonic(); } else { + self->alternate_screen.exited_at = monotonic(); self->linebuf = self->main_linebuf; self->tabstops = self->main_tabstops; self->key_encoding_flags = self->main_key_encoding_flags; @@ -3634,6 +3636,14 @@ parse_prompt_mark(Screen *self, char *buf, PromptKind *pk) { } } +static void +mark_command_finished(Screen *self) { + if (self->command_state.running) { + self->command_state.running = false; + self->command_state.finished_at = monotonic(); + } +} + void shell_prompt_marking(Screen *self, char *buf) { if (self->cursor->y < self->lines) { @@ -3645,10 +3655,15 @@ shell_prompt_marking(Screen *self, char *buf) { self->prompt_settings.redraws_prompts_at_all = 1; parse_prompt_mark(self, buf + 1, &pk); self->linebuf->line_attrs[self->cursor->y].prompt_kind = pk; - if (pk == PROMPT_START) CALLBACK("cmd_output_marking", "O", Py_False); + if (pk == PROMPT_START) { + mark_command_finished(self); + CALLBACK("cmd_output_marking", "O", Py_False); + } } break; case 'C': { self->linebuf->line_attrs[self->cursor->y].prompt_kind = OUTPUT_START; + self->command_state.running = true; + self->command_state.started_at = monotonic(); const char *cmdline = ""; if (strstr(buf + 1, ";cmdline") == buf + 1) { cmdline = buf + 2; } RAII_PyObject(c, PyUnicode_DecodeUTF8(cmdline, strlen(cmdline), "replace")); @@ -3658,6 +3673,7 @@ shell_prompt_marking(Screen *self, char *buf) { } break; case 'D': { const char *exit_status = buf[1] == ';' ? buf + 2 : ""; + mark_command_finished(self); CALLBACK("cmd_output_marking", "Os", Py_None, exit_status); } break; } @@ -7407,6 +7423,11 @@ static PyMemberDef members[] = { {"linebuf", T_OBJECT_EX, offsetof(Screen, linebuf), READONLY, "linebuf"}, {"main_linebuf", T_OBJECT_EX, offsetof(Screen, main_linebuf), READONLY, "main_linebuf"}, {"historybuf", T_OBJECT_EX, offsetof(Screen, historybuf), READONLY, "historybuf"}, + {"command_running", T_BOOL, offsetof(Screen, command_state.running), READONLY, "command_running"}, + {"command_started_at", T_LONGLONG, offsetof(Screen, command_state.started_at), READONLY, "command_started_at"}, + {"command_finished_at", T_LONGLONG, offsetof(Screen, command_state.finished_at), READONLY, "command_finished_at"}, + {"alternate_screen_entered_at", T_LONGLONG, offsetof(Screen, alternate_screen.entered_at), READONLY, "alternate_screen_entered_at"}, + {"alternate_screen_exited_at", T_LONGLONG, offsetof(Screen, alternate_screen.exited_at), READONLY, "alternate_screen_exited_at"}, {"scrolled_by", T_UINT, offsetof(Screen, scrolled_by), READONLY, "scrolled_by"}, {"pixel_scroll_offset_y", T_UINT, offsetof(Screen, pixel_scroll_offset_y), READONLY, "pixel_scroll_offset_y"}, {"lines", T_UINT, offsetof(Screen, lines), READONLY, "lines"}, diff --git a/kitty/screen.h b/kitty/screen.h index 7f32450b8..5797129c1 100644 --- a/kitty/screen.h +++ b/kitty/screen.h @@ -153,6 +153,15 @@ typedef struct { ScreenModes modes, saved_modes; ColorProfile *color_profile; monotonic_t start_visual_bell_at; + // Shell integration (OSC 133) command state and alternate screen + // changes, used by custom shaders. Times are zero until the first change. + struct { + monotonic_t started_at, finished_at; + bool running; + } command_state; + struct { + monotonic_t entered_at, exited_at; + } alternate_screen; monotonic_t start_drag_overlay_at; // 0 = inactive uint8_t drag_overlay_quadrant; // 1=left 2=right 3=top 4=bottom 0=none diff --git a/kitty/shaders.c b/kitty/shaders.c index 9f1e52830..f56da38f1 100644 --- a/kitty/shaders.c +++ b/kitty/shaders.c @@ -860,6 +860,10 @@ shader_anim_event_mask_str(ShaderAnimEventMask mask) { {1u << SHADER_ANIM_EVENT_USER_IDLE, "user-idle"}, {1u << SHADER_ANIM_EVENT_CURSOR_TRAIL_MOVE, "cursor-trail-move"}, {1u << SHADER_ANIM_EVENT_CURSOR_TRAIL_STOP, "cursor-trail-stop"}, + {1u << SHADER_ANIM_EVENT_COMMAND_START, "command-start"}, + {1u << SHADER_ANIM_EVENT_COMMAND_FINISH, "command-finish"}, + {1u << SHADER_ANIM_EVENT_ALTERNATE_SCREEN_ENTER, "alternate-screen-enter"}, + {1u << SHADER_ANIM_EVENT_ALTERNATE_SCREEN_EXIT, "alternate-screen-exit"}, }; bool first = true; for (size_t i = 0; i < sizeof(events) / sizeof(events[0]); i++) { @@ -3125,6 +3129,10 @@ run_custom_end_shader(OSWindow *os_window, float sx, float sy, monotonic_t now) float timestamp_fraction; float time_since_last_render; float cursor_trail_age; + float active_window_alternate_screen; + float active_window_command_running; + float active_window_alternate_screen_age; + float active_window_command_state_age; }; // This struct is a hand written mirror of the std140 layout of // KittyCustomShaderData in types.slang, so check that they match once. @@ -3159,6 +3167,8 @@ run_custom_end_shader(OSWindow *os_window, float sx, float sy, monotonic_t now) color_type cursor_color = OPT(foreground); float cursor_opacity = 0.f; WindowGeometry active_win_geom = {0}; + d->active_window_alternate_screen_age = -1.f; + d->active_window_command_state_age = -1.f; if (os_window->num_tabs > 0) { Tab *t = os_window->tabs + os_window->active_tab; if (t->num_windows) { @@ -3189,6 +3199,12 @@ run_custom_end_shader(OSWindow *os_window, float sx, float sy, monotonic_t now) active_bg = colorprofile_to_color(s->color_profile, s->color_profile->overridden.default_bg, s->color_profile->configured.default_bg).rgb; cursor_color = s->last_rendered.cursor_bg; cursor_opacity = MAX(0.f, MIN(s->cursor_render_info.cursor_opacity, 1.f)); + d->active_window_alternate_screen = s->linebuf == s->alt_linebuf ? 1.f : 0.f; + d->active_window_command_running = s->command_state.running ? 1.f : 0.f; + const monotonic_t alt_changed_at = MAX(s->alternate_screen.entered_at, s->alternate_screen.exited_at); + if (alt_changed_at) d->active_window_alternate_screen_age = (float)monotonic_t_to_s_double(now - alt_changed_at); + const monotonic_t cmd_changed_at = MAX(s->command_state.started_at, s->command_state.finished_at); + if (cmd_changed_at) d->active_window_command_state_age = (float)monotonic_t_to_s_double(now - cmd_changed_at); } } } @@ -3627,6 +3643,10 @@ shader_anim_event_bit(const char *s, CustomShaderPipeline *p) { if (strcmp(s, "user-idle") == 0) return 1u << SHADER_ANIM_EVENT_USER_IDLE; if (strcmp(s, "cursor-trail-move") == 0) return 1u << SHADER_ANIM_EVENT_CURSOR_TRAIL_MOVE; if (strcmp(s, "cursor-trail-stop") == 0) return 1u << SHADER_ANIM_EVENT_CURSOR_TRAIL_STOP; + if (strcmp(s, "command-start") == 0) return 1u << SHADER_ANIM_EVENT_COMMAND_START; + if (strcmp(s, "command-finish") == 0) return 1u << SHADER_ANIM_EVENT_COMMAND_FINISH; + if (strcmp(s, "alternate-screen-enter") == 0) return 1u << SHADER_ANIM_EVENT_ALTERNATE_SCREEN_ENTER; + if (strcmp(s, "alternate-screen-exit") == 0) return 1u << SHADER_ANIM_EVENT_ALTERNATE_SCREEN_EXIT; static const char user_prefix[] = "user:"; if (strncmp(s, user_prefix, sizeof(user_prefix) - 1) == 0) { const char *name = s + sizeof(user_prefix) - 1; diff --git a/kitty/shaders/custom/types.slang b/kitty/shaders/custom/types.slang index 27374f8f4..1be4f1ef5 100644 --- a/kitty/shaders/custom/types.slang +++ b/kitty/shaders/custom/types.slang @@ -104,6 +104,23 @@ public struct KittyCustomShaderData { // Seconds since cursor_trail_change_time, negative when cursor_trail_change_time is zero. public float cursor_trail_age; + // State of the active window in the active tab. All are zero when there is no active window. + // 1.0 when the active window is showing the alternate screen, as used by + // full screen programs such as editors and pagers, 0.0 otherwise. + public float active_window_alternate_screen; + // 1.0 while a command is running in the active window, 0.0 otherwise. + // Requires shell integration, see https://sw.kovidgoyal.net/kitty/shell-integration/ + // A command starts when its output starts (OSC 133;C) and finishes when the + // shell reports it finished (OSC 133;D) or draws the next prompt. + public float active_window_command_running; + // Seconds since the active window last entered or left the alternate screen, + // negative if it never has. Use with the alternate-screen-enter and + // alternate-screen-exit events to fade effects in and out. + public float active_window_alternate_screen_age; + // Seconds since a command last started or finished in the active window, + // negative if none has. Use with the command-start and command-finish events. + public float active_window_command_state_age; + // Seconds since kitty was started, wrapped to [0, period_seconds). Unlike // timestamp, this keeps sub-millisecond precision however long kitty runs, // as long as period_seconds is at most an hour or so. The value jumps back diff --git a/kitty/shaders/slang.py b/kitty/shaders/slang.py index 0201dd161..38b3ba19d 100644 --- a/kitty/shaders/slang.py +++ b/kitty/shaders/slang.py @@ -1537,6 +1537,10 @@ SHADER_ANIMATION_EVENTS: frozenset[str] = frozenset( 'user-idle', 'cursor-trail-move', 'cursor-trail-stop', + 'command-start', + 'command-finish', + 'alternate-screen-enter', + 'alternate-screen-exit', } ) diff --git a/kitty/state.h b/kitty/state.h index 40c5de236..f9b4ad040 100644 --- a/kitty/state.h +++ b/kitty/state.h @@ -560,11 +560,16 @@ typedef enum { SHADER_ANIM_EVENT_USER_IDLE, SHADER_ANIM_EVENT_CURSOR_TRAIL_MOVE, SHADER_ANIM_EVENT_CURSOR_TRAIL_STOP, + SHADER_ANIM_EVENT_COMMAND_START, + SHADER_ANIM_EVENT_COMMAND_FINISH, + SHADER_ANIM_EVENT_ALTERNATE_SCREEN_ENTER, + SHADER_ANIM_EVENT_ALTERNATE_SCREEN_EXIT, NUM_SHADER_ANIM_EVENTS } ShaderAnimationEvent; // Events named by the pipeline itself, with the user: prefix, and fired by the // shader_event action occupy the bits above the builtin events #define SHADER_ANIM_FIRST_USER_EVENT 16 +_Static_assert(NUM_SHADER_ANIM_EVENTS <= SHADER_ANIM_FIRST_USER_EVENT, "Too many builtin shader animation events"); #define MAX_SHADER_ANIM_USER_EVENTS (64 - SHADER_ANIM_FIRST_USER_EVENT) #define MAX_SHADER_ANIM_USER_EVENT_NAME_LEN 63 // Bitmask of ShaderAnimationEvent values and user events @@ -652,6 +657,8 @@ typedef struct OSWindow { } scroll; ShaderAnimEventMask shader_anim_event_registry; id_type last_bell_window_id; // ID of the most recent window that received a bell event + // Time up to which command and alternate screen changes in the active window have been turned into shader events + monotonic_t screen_state_checked_at; ShaderGroupAnimState shader_group_anim[MAX_CUSTOM_SHADER_GROUPS]; ShaderAnimState shader_anim; struct { diff --git a/kitty_tests/screen.py b/kitty_tests/screen.py index eb9fbec46..b2c12ad27 100644 --- a/kitty_tests/screen.py +++ b/kitty_tests/screen.py @@ -2336,6 +2336,44 @@ class TestScreen(BaseTest): s.erase_last_command() self.ae('before\nl1\npartial', at().rstrip()) + def test_command_and_alternate_screen_state(self): + # Used by custom shaders + s = self.create_screen() + self.assertFalse(s.command_running) + self.ae((s.command_started_at, s.command_finished_at), (0, 0)) + parse_bytes(s, b'\033]133;A\007') # a prompt with no running command finishes nothing + self.ae(s.command_finished_at, 0) + parse_bytes(s, b'\033]133;C\007') + self.assertTrue(s.command_running) + started = s.command_started_at + self.assertGreater(started, 0) + self.ae(s.command_finished_at, 0) + parse_bytes(s, b'\033]133;A;k=s\007') # a secondary prompt does not finish the command + self.assertTrue(s.command_running) + parse_bytes(s, b'\033]133;D;0\007') + self.assertFalse(s.command_running) + finished = s.command_finished_at + self.assertGreaterEqual(finished, started) + parse_bytes(s, b'\033]133;A\007') # the prompt after D does not finish it again + self.ae(s.command_finished_at, finished) + parse_bytes(s, b'\033]133;C\007') + self.assertTrue(s.command_running) + parse_bytes(s, b'\033]133;A\007') # a shell that does not send D + self.assertFalse(s.command_running) + self.assertGreaterEqual(s.command_finished_at, s.command_started_at) + + self.ae((s.alternate_screen_entered_at, s.alternate_screen_exited_at), (0, 0)) + parse_bytes(s, b'\033[?1049h') + self.assertTrue(s.is_using_alternate_linebuf()) + entered = s.alternate_screen_entered_at + self.assertGreater(entered, 0) + self.ae(s.alternate_screen_exited_at, 0) + parse_bytes(s, b'\033[?1049h') # already on the alternate screen + self.ae(s.alternate_screen_entered_at, entered) + parse_bytes(s, b'\033[?1049l') + self.assertFalse(s.is_using_alternate_linebuf()) + self.assertGreaterEqual(s.alternate_screen_exited_at, entered) + def test_pointer_shapes(self): from kitty.window import set_pointer_shape diff --git a/kitty_tests/slang.py b/kitty_tests/slang.py index 85ebd8147..34c96e92d 100644 --- a/kitty_tests/slang.py +++ b/kitty_tests/slang.py @@ -118,6 +118,9 @@ class TestSlang(BaseTest): g = pipeline('animation_start user:find-cursor|tab-change\nanimation_stop user:x.y_z')['groups'][0] self.ae(g['animation_start'], ('user:find-cursor', 'tab-change')) self.ae(g['animation_end_events'], ('user:x.y_z',)) + g = pipeline('animation_start command-start|alternate-screen-exit\nanimation_stop command-finish|alternate-screen-enter')['groups'][0] + self.ae(g['animation_start'], ('command-start', 'alternate-screen-exit')) + self.ae(g['animation_end_events'], ('command-finish', 'alternate-screen-enter')) # Trailing comments, including empty ones for comment in ('# ', '#', '# some comment', '\t#x'): g = pipeline(f'animation_toggle user:toggle-notch {comment}\nanimation_duration 600 {comment}')['groups'][0]