Custom shaders: Add screen-shake shaders for the bell

Shake only the window in which a bell occurred, using
d.bell_window_geometry, either side to side or in random directions.
Useful for shaking the window when a shell command fails. Add docs with
shell snippets to ring the bell on command failure and demo entries.
This commit is contained in:
Kovid Goyal 2026-11-05 14:21:07 +05:30
parent 8a3dace409
commit fe5ac530e5
No known key found for this signature in database
GPG key ID: 06BC317B515ACE7C
7 changed files with 190 additions and 0 deletions

View file

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

View file

@ -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 <kitty/shaders/custom/screen-shake.slang>`.
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
-----------------

View file

@ -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 <https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function>`.
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`.
""",
)

View file

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

View file

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

View file

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

View file

@ -0,0 +1,98 @@
#language slang 2026
// Copyright (C) 2026 Kovid Goyal <kovid at kovidgoyal.net>
// 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);
}