diff --git a/docs/changelog.rst b/docs/changelog.rst index 7f6d491f9..3daaafca2 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -130,6 +130,10 @@ Detailed list of changes events and uniforms for whether a command is running and whether the alternate screen is in use in the active window +- :doc:`Custom shaders `: Add ``screen-shake`` and + ``screen-shake-random`` shaders that shake the window in which a bell occurs, + for example, to shake the window when a shell command fails + - :doc:`Custom shaders `: Fix the ``bell-in-window`` event only firing when :opt:`visual_bell_duration` is non-zero. Bells in hidden windows, such as those in inactive tabs, no longer trigger the event late, when the diff --git a/docs/custom-shaders.rst b/docs/custom-shaders.rst index 43251cc9c..4ee121a84 100644 --- a/docs/custom-shaders.rst +++ b/docs/custom-shaders.rst @@ -60,6 +60,51 @@ Navigation .. include:: generated/custom-shaders-navigation.rst +Bell effects +--------------- + +These shaders run when a bell (the BEL character) is received in a window. +The ``screen-shake`` shader shakes only the window in which the bell occurred, +other windows in the tab are left alone. Use ``screen-shake-random`` for a +jittery shake in random directions instead of side to side. The amount, speed +and style of the shake can be changed, as explained at the top of the +:repo_file:`shader file `. + +To shake the window whenever a shell command fails, have your shell print a +bell character when the last command exits with an error. + +.. highlight:: sh + +.. tab-set:: + + .. tab-item:: zsh + + Add the following to :file:`~/.zshrc`:: + + autoload -Uz add-zsh-hook + bell_on_error() { local s=$?; (( s )) && printf '\a'; return $s } + add-zsh-hook precmd bell_on_error + + .. tab-item:: bash + + Add the following to :file:`~/.bashrc`:: + + bell_on_error() { local s=$?; (( s )) && printf '\a'; return $s; } + PROMPT_COMMAND="bell_on_error${PROMPT_COMMAND:+; $PROMPT_COMMAND}" + + .. tab-item:: fish + + Add the following to :file:`~/.config/fish/config.fish`:: + + function bell_on_error --on-event fish_postexec + test $status -ne 0; and printf '\a' + end + + +.. highlight:: hlsl + +.. include:: generated/custom-shaders-bell.rst + Retro Terminals ----------------- diff --git a/kitty/options/definition.py b/kitty/options/definition.py index f82517150..d6d554040 100644 --- a/kitty/options/definition.py +++ b/kitty/options/definition.py @@ -1599,6 +1599,8 @@ if unspecified is to use :code:`ease-in-out` which fades slowly at the start, mi You can specify different easing functions for the fade-in and fade-out parts, like this: :code:`2.0 ease-in linear`. kitty supports all the :link:`CSS easing functions `. +For different effects, such as shaking the screen on a bell, you can instead use :opt:`custom_shaders`, for example, +:code:`custom_shaders screen-shake`. """, ) diff --git a/kitty/shaders/custom/demo.py b/kitty/shaders/custom/demo.py index 8397a5bff..f996782f1 100755 --- a/kitty/shaders/custom/demo.py +++ b/kitty/shaders/custom/demo.py @@ -143,6 +143,13 @@ def tab_change(window_id: str, geometry: tuple[int, int, int, int]) -> None: remote_control('focus-tab', '-m', 'id:1') +def screen_shake(window_id: str, geometry: tuple[int, int, int, int]) -> None: + # Ring the bell in different windows to show that only that window shakes + for wid in (1, 2, 3, 1): + time.sleep(0.6) + remote_control('send-text', '-m', f'id:{wid}', "printf '\\\\a'\r") + + metadata: dict[str, dict[str, Any]] = { # Background 'inside-the-matrix': {'category': 'background', 'tagline': 'See the bones of reality.'}, @@ -184,6 +191,19 @@ metadata: dict[str, dict[str, Any]] = { 'tagline': 'Briefly highlight the active window on focus change.', 'session': 'launch kitten run-shell ls -l\nlaunch kitten run-shell bat -P setup.py\nlaunch kitten run-shell echo Hello World', }, + # Bell + 'screen-shake': { + 'animate': screen_shake, + 'category': 'bell', + 'tagline': 'Shake the window that rang the bell, for example, when a command fails.', + 'session': 'launch kitten run-shell ls -l\nlaunch kitten run-shell bat -P setup.py\nlaunch kitten run-shell echo Hello World', + }, + 'screen-shake-random': { + 'animate': screen_shake, + 'category': 'bell', + 'tagline': 'Shake the window that rang the bell in random directions.', + 'session': 'launch kitten run-shell ls -l\nlaunch kitten run-shell bat -P setup.py\nlaunch kitten run-shell echo Hello World', + }, # Retro terminals 'crt': {'category': 'retro', 'title': 'Cathode Ray Tube', 'tagline': 'Your terminal deserves to have curves.', 'duration': 2}, 'crt-blue': {'category': 'retro', 'title': 'CRT Blue', 'tagline': 'Do you have the blues?', 'duration': 2}, diff --git a/kitty/shaders/custom/screen-shake-random.pipeline b/kitty/shaders/custom/screen-shake-random.pipeline new file mode 100644 index 000000000..eca2180b3 --- /dev/null +++ b/kitty/shaders/custom/screen-shake-random.pipeline @@ -0,0 +1,12 @@ +# Shake the window in which a bell occurs in random directions +startgroup + animation_start bell-in-window + animation_stop 400 + # the shader computes the decay of the shake itself + animation_curve linear + animation_step 16 + var int SHAKE_MODE = 1 + var float AMPLITUDE_PIXELS = 10 + var float SHAKES = 6 + shaders screen-shake +endgroup diff --git a/kitty/shaders/custom/screen-shake.pipeline b/kitty/shaders/custom/screen-shake.pipeline new file mode 100644 index 000000000..af8ce7d80 --- /dev/null +++ b/kitty/shaders/custom/screen-shake.pipeline @@ -0,0 +1,9 @@ +# Shake the window in which a bell occurs from side to side +startgroup + animation_start bell-in-window + animation_stop 300 + # the shader computes the decay of the shake itself + animation_curve linear + animation_step 16 + shaders screen-shake +endgroup diff --git a/kitty/shaders/custom/screen-shake.slang b/kitty/shaders/custom/screen-shake.slang new file mode 100644 index 000000000..32b730751 --- /dev/null +++ b/kitty/shaders/custom/screen-shake.slang @@ -0,0 +1,98 @@ +#language slang 2026 +// Copyright (C) 2026 Kovid Goyal +// Distributed under terms of the GPLv3 license. +// +// Screen shake effect +// Shakes the window in which a bell (BEL character) occurred, leaving all +// other windows in the tab untouched. Uses d.bell_window_geometry to locate the +// window. If that window is no longer visible, the whole tab area is shaken. +// The shake decays to nothing over the animation, which should use a linear +// animation_curve, as the decay is computed here. +// +// A handy use for this is to shake the window when a shell command fails, by +// having the shell print a BEL character when that happens. Set +// visual_bell_duration to zero in kitty.conf to disable the builtin visual +// bell flash, the shake is triggered regardless. + +import kitty_custom_shader_types; + +// 0 = HORIZONTAL — a side to side shake, like a head shaking "no" +// 1 = RANDOM — a jittery shake in random directions, both horizontally and vertically +static const int SHAKE_MODE = 0; +// Maximum displacement of the window contents in pixels, at the start of the shake. +static const float AMPLITUDE_PIXELS = 12.0; +// Number of back and forth movements over the duration of the animation. Keep +// this low enough that each movement lasts at least a few frames, otherwise +// the shake becomes a flicker. +static const float SHAKES = 4.0; +// How quickly the shake dies down, higher values die down faster. 1 is linear. +static const float DECAY_POWER = 2.0; +// What to show in the strip uncovered at the edge of the window as its contents move: +// false = the window background color +// true = repeat the pixels at the edge of the window +static const bool REPEAT_EDGE = false; +// Shake the whole tab area rather than just the window that belled. +static const bool SHAKE_ENTIRE_TAB = false; + +static const float TAU = 6.28318530718; + +// Pseudo-random value in [0, 1) for each integer n +float +hash(float n) { + return fract(sin(n * 12.9898 + 78.233) * 43758.5453); +} + +// Smooth noise in [-1, 1] +float +noise(float x) { + float i = floor(x); + float f = fract(x); + float u = f * f * (3.0 - 2.0 * f); + return lerp(hash(i), hash(i + 1.0), u) * 2.0 - 1.0; +} + +// Two octaves of noise in [-1, 1] +float +fractal_noise(float x) { + return (noise(x) + 0.5 * noise(2.0 * x + 31.7)) / 1.5; +} + +// Displacement of the window contents as a fraction of the amplitude, for animation progress p +float2 +shake_offset(float p) { + float strength = pow(1.0 - p, DECAY_POWER); + if (SHAKE_MODE == 1) { + // Each noise lattice point is a new random target position, so use + // two of them per shake + float x = p * SHAKES * 2.0; + return strength * float2(fractal_noise(x), fractal_noise(x + 113.0)); + } + return float2(strength * sin(TAU * SHAKES * p), 0.0); +} + +public float4 +fragment_main(float4 color, KittyTextures t, KittyCustomShaderData d) { + float4 g = SHAKE_ENTIRE_TAB ? d.central_area : d.bell_window_geometry; + // Nothing to shake before the first bell + if (g.z <= 0.0 || g.w <= 0.0) return color; + float2 win_min = g.xy; + float2 win_max = g.xy + g.zw; + if (any(t.pos < win_min) || any(t.pos > win_max)) return color; + + float2 px = float2(d.viewport_size_pixels) * t.viewport.zw; + if (px.x <= 0.0 || px.y <= 0.0) return color; + float2 offset = shake_offset(t.animation_progress) * AMPLITUDE_PIXELS / px; + float2 src = t.pos - offset; + + if (REPEAT_EDGE) { + float2 half_pixel = 0.5 / px; + return t.backbuffer.Sample(clamp(src, win_min + half_pixel, win_max - half_pixel)); + } + if (all(src >= win_min) && all(src <= win_max)) return t.backbuffer.Sample(src); + // The pixel is uncovered, fill it with the window background. The + // background of the active window is known, for other windows use the + // global background. + bool is_active = all(abs(g - d.active_window_geometry) < 0.5 / float4(px, px)); + float3 bg = is_active ? d.active_window_background.rgb : d.background.rgb; + return float4(bg, color.a); +}