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.
This commit is contained in:
Kovid Goyal 2026-11-05 08:43:37 +05:30
parent 7670f895a6
commit bc9d0b87e3
No known key found for this signature in database
GPG key ID: 06BC317B515ACE7C
12 changed files with 188 additions and 1 deletions

View file

@ -222,6 +222,11 @@ Detailed list of changes
0.50.1 [unreleased]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- :doc:`Custom shaders <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 <kittens/choose-files>`: Fix concurrent custom preview
commands occasionally receiving the path of a different file.

View file

@ -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 <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 <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:<name>``
- Sent by the :ac:`shader_event` action, typically from a mapping, see
:ref:`custom_shader_mappings`. ``<name>`` 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.

View file

@ -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;

View file

@ -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

View file

@ -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"},

View file

@ -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

View file

@ -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;

View file

@ -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

View file

@ -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',
}
)

View file

@ -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 {

View file

@ -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

View file

@ -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]