Custom shaders: Use pointer_map() of groups turned on and off by events

Groups that are active until an event turns them off, such as those
using animation_toggle, now also move pointer events, while they are
active. The pointer map is recomputed only when the set of active such
groups changes, and pointer events are left alone once all of them have
been turned off.
This commit is contained in:
Kovid Goyal 2026-10-15 21:01:05 +05:30
parent 28aad4345e
commit 7dbfb0e1ce
No known key found for this signature in database
GPG key ID: 06BC317B515ACE7C
8 changed files with 135 additions and 35 deletions

View file

@ -268,6 +268,10 @@ Detailed list of changes
:ac:`shader_event` action, :code:`user:` animation events and the
:code:`animation_toggle` pipeline directive, see :ref:`custom_shader_mappings` (:iss:`10667`)
- Custom shaders: The :code:`pointer_map()` function of shaders that move
content is now also used for groups that are turned on and off by events,
while they are active
- Add English and Spanish subtitles to the intro video shown at the top of the
documentation

View file

@ -232,10 +232,15 @@ The function must be ``public`` and return ``float2``. kitty evaluates it on a
grid only when the pipeline is loaded and when the OS Window is resized, and
uses it to move all pointer events, so the only field of ``d`` it may use is
``d.viewport_size_pixels``. Only shaders in groups that draw to the whole
screen and are always active, that is, without ``animation_start``,
``attach``, ``output_texture``, ``viewport_pos`` or ``viewport_size``, are
used, since only they move content permanently. When several shaders define
it, they are applied starting from the last one to run.
screen, that is, without ``attach``, ``output_texture``, ``viewport_pos`` or
``viewport_size``, and that are either always active or active until an event
turns them off, that is, without an ``animation_stop`` duration, are used,
since only they move content for any length of time. For a group that is
turned on and off by events, such as one using ``animation_toggle``, the
function is used only while the group is active, so a shader that moves
content can be turned on and off with a :ref:`key press
<custom_shader_mappings>`. When several shaders define it, they are applied
starting from the last one to run.
Note that :code:`d.mouse_pos` then contains the mapped position, that is, the
position of the content under the mouse before it was moved. Effects that draw

View file

@ -2833,7 +2833,7 @@ class Boss:
@ac(
'misc',
'''
"""
Send an event to the :doc:`custom shaders <custom-shaders>`
Groups in the custom shader pipeline that use the event as
@ -2846,7 +2846,7 @@ class Boss:
map f1 shader_event find-cursor
# Toggle groups that have: animation_toggle user:notch in all OS windows
map f2 shader_event notch all
''',
""",
)
def shader_event(self, name: str, scope: str = 'active') -> None:
os_window_id = 0

View file

@ -462,11 +462,11 @@ typedef struct CustomShaderGroup {
ShaderAnimEventMask animation_start_events; // events that start the animation; 0 = none
ShaderAnimEventMask animation_toggle_events; // events that start the animation when stopped and vice versa; 0 = none
ShaderAnimEventMask animation_end_events; // events that stop the animation; 0 = none
monotonic_t animation_end_duration; // nanoseconds; 0 = no time limit, < 0 = use cursor_stop_blinking_after
monotonic_t animation_step; // nanoseconds between animation samples
Animation *animation_curve; // parsed easing curve; NULL = no animation
bool animation_curve_is_shared; // true if animation_curve is owned by an earlier group
bool attached; // true = always active when the preceding group is active
monotonic_t animation_end_duration; // nanoseconds; 0 = no time limit, < 0 = use cursor_stop_blinking_after
monotonic_t animation_step; // nanoseconds between animation samples
Animation *animation_curve; // parsed easing curve; NULL = no animation
bool animation_curve_is_shared; // true if animation_curve is owned by an earlier group
bool attached; // true = always active when the preceding group is active
} CustomShaderGroup;
typedef struct CustomShaderPipeline {
@ -474,9 +474,10 @@ typedef struct CustomShaderPipeline {
CustomShaderGroup groups[MAX_CUSTOM_SHADER_GROUPS];
size_t num_groups;
bool active;
bool bypass_builtin_trail; // true when any group subscribes to cursor-trail-move
bool bypass_builtin_trail; // true when any group subscribes to cursor-trail-move
ShaderAnimEventMask all_animation_start_events; // union of the start and toggle events of all groups
bool has_pointer_map; // true when a shader defines pointer_map() to move pointer events
uint32_t pointer_map_groups; // bitmask of the groups with shaders whose pointer_map() is used
// Names (without the user: prefix) of the user events the pipeline uses,
// user event i is bit SHADER_ANIM_FIRST_USER_EVENT + i
char user_events[MAX_SHADER_ANIM_USER_EVENTS][MAX_SHADER_ANIM_USER_EVENT_NAME_LEN + 1];
@ -2734,6 +2735,18 @@ sample_pointer_map(const float *data, double *u, double *v) {
#undef P
}
// The groups whose pointer_map() functions currently apply: those that are
// always active and those turned on by events that are active right now
static uint32_t
active_pointer_map_groups(const OSWindow *os_window) {
uint32_t ans = 0;
for (size_t g = 0; g < custom_shaders.end.num_groups; g++) {
if (!(custom_shaders.end.pointer_map_groups & (1u << g))) continue;
if (!group_is_animated(custom_shaders.end.groups + g) || os_window->shader_group_anim[g].active) ans |= 1u << g;
}
return ans;
}
// Moves a pointer position, in viewport pixels with the origin at the top left,
// to the position of the content that custom shaders such as crt actually show
// there, so that clicks and selections land on what the user sees.
@ -2741,6 +2754,11 @@ void
map_pointer_position(const OSWindow *os_window, double *x, double *y) {
const float *data = os_window->pointer_map.data;
if (!data || !custom_shaders.end.has_pointer_map || os_window->pointer_map.pipeline_generation != custom_shaders.generation) return;
// The map is updated only when the custom shaders are drawn, which they
// are not once every group has been turned off, so check that it is
// still for the groups that are active
const uint32_t groups = active_pointer_map_groups(os_window);
if (!groups || groups != os_window->pointer_map.groups) return;
const double width = os_window->viewport_width, height = os_window->viewport_height;
if (width <= 0 || height <= 0) return;
const double u = *x / width, v = 1. - *y / height;
@ -2755,14 +2773,22 @@ map_pointer_position(const OSWindow *os_window, double *x, double *y) {
// Renders the pointer_map() functions of the pipeline into a small texture
// and reads it back so that pointer events can be mapped without the GPU. A
// pointer map can depend only on the pipeline and the viewport size, so this
// is done only when those change.
// pointer map can depend only on the pipeline, the viewport size and which
// groups are active, so this is done only when those change.
static void
update_pointer_map(OSWindow *os_window, GLint group_loc) {
if (os_window->pointer_map.data && os_window->pointer_map.pipeline_generation == custom_shaders.generation) {
const uint32_t groups = active_pointer_map_groups(os_window);
if (os_window->pointer_map.pipeline_generation == custom_shaders.generation && os_window->pointer_map.groups == groups &&
(os_window->pointer_map.data || !groups)) {
if (os_window->live_resize.in_progress) return; // avoid a GPU sync on every frame of a live resize
if (os_window->pointer_map.viewport_width == os_window->viewport_width && os_window->pointer_map.viewport_height == os_window->viewport_height) return;
}
os_window->pointer_map.viewport_width = os_window->viewport_width;
os_window->pointer_map.viewport_height = os_window->viewport_height;
os_window->pointer_map.pipeline_generation = custom_shaders.generation;
os_window->pointer_map.groups = 0;
// No pointer_map() applies, such as when content moving groups are toggled off, so pointer events are not moved
if (!groups) return;
if (!os_window->pointer_map.data && !(os_window->pointer_map.data = malloc(sizeof(float) * 2 * POINTER_MAP_SIZE * POINTER_MAP_SIZE))) return;
if (!pointer_map_target.framebuffer_id)
setup_texture_as_render_target(POINTER_MAP_SIZE, POINTER_MAP_SIZE, &pointer_map_target.texture_id, &pointer_map_target.framebuffer_id);
@ -2775,6 +2801,9 @@ update_pointer_map(OSWindow *os_window, GLint group_loc) {
bind_framebuffer_for_output(pointer_map_target.framebuffer_id);
glViewport(0, 0, POINTER_MAP_SIZE, POINTER_MAP_SIZE);
glUniform1i(group_loc, -1);
// Absent when no group with a pointer_map() is turned on and off by events
GLint active_groups_loc = try_program_uniform_location(CUSTOM_END_PROGRAM, "active_groups");
if (active_groups_loc >= 0) glUniform1ui(active_groups_loc, groups);
draw_quad(false, 0);
static uint8_t pixels[POINTER_MAP_SIZE * POINTER_MAP_SIZE * 4];
glReadPixels(0, 0, POINTER_MAP_SIZE, POINTER_MAP_SIZE, GL_RGBA, GL_UNSIGNED_BYTE, pixels);
@ -2784,9 +2813,7 @@ update_pointer_map(OSWindow *os_window, GLint group_loc) {
os_window->pointer_map.data[2 * i] = (float)(p[0] * 256 + p[2]) / 65535.f;
os_window->pointer_map.data[2 * i + 1] = (float)(p[1] * 256 + p[3]) / 65535.f;
}
os_window->pointer_map.viewport_width = os_window->viewport_width;
os_window->pointer_map.viewport_height = os_window->viewport_height;
os_window->pointer_map.pipeline_generation = custom_shaders.generation;
os_window->pointer_map.groups = groups;
}
static void
@ -3555,6 +3582,17 @@ compile_program(PyObject UNUSED *self, PyObject *args) {
custom_shaders.end.active = true;
PyObject *has_pointer_map = PyDict_GetItemString(metadata, "has_pointer_map");
custom_shaders.end.has_pointer_map = has_pointer_map && PyObject_IsTrue(has_pointer_map) == 1;
PyObject *pointer_map_groups = PyDict_GetItemString(metadata, "pointer_map_groups");
if (pointer_map_groups && (PyList_Check(pointer_map_groups) || PyTuple_Check(pointer_map_groups))) {
for (Py_ssize_t i = 0; i < PySequence_Fast_GET_SIZE(pointer_map_groups); i++) {
long g = PyLong_AsLong(PySequence_Fast_GET_ITEM(pointer_map_groups, i));
if (g >= 0 && (size_t)g < custom_shaders.end.num_groups) custom_shaders.end.pointer_map_groups |= 1u << g;
}
if (PyErr_Occurred()) {
glDeleteProgram(program->id);
return NULL;
}
}
custom_shaders.generation++;
}
init_uniforms(which);

View file

@ -65,9 +65,11 @@ uniform Sampler2D backbuffer, a, b, persist;
static const float pointer_map_size = POINTER_MAP_SIZE;
// Where the content visible at pos actually is, as decided by the pointer_map()
// functions of the shaders that move content around
// functions of the shaders that move content around. Shaders in groups that
// are turned on and off by events apply only when the bit for their group is
// set in active_groups.
float2
pipeline_pointer_map(float2 pos) {
pipeline_pointer_map(float2 pos, uint active_groups) {
// POINTER_MAP
return pos;
}
@ -76,16 +78,16 @@ pipeline_pointer_map(float2 pos) {
// is split over two 8 bit channels so that it is precise even on GPU drivers
// that cannot render to 16 bit textures.
float4
encode_pointer_map(float2 texel_pos) {
encode_pointer_map(float2 texel_pos, uint active_groups) {
// Spread the texels so that the first and last ones land exactly on the edges
float2 pos = (texel_pos * pointer_map_size - 0.5f) / (pointer_map_size - 1.f);
float2 q = round(saturate(pipeline_pointer_map(pos)) * 65535.f);
float2 q = round(saturate(pipeline_pointer_map(pos, active_groups)) * 65535.f);
float2 hi = floor(q / 256.f);
return float4(hi / 255.f, (q - hi * 256.f) / 255.f);
}
public float4
pipeline_fragment_main(float2 backbuffer_pos, int group, float4 viewport, float animation_progress, bool convert_to_srgb) {
pipeline_fragment_main(float2 backbuffer_pos, int group, float4 viewport, float animation_progress, bool convert_to_srgb, uint active_groups) {
float4 color = backbuffer.Sample(backbuffer_pos); // pre multiplied linear RGB
color = float4(color.rgb / color.a, color.a); // un pre multiplied color passed through pipeline
// src_rect encodes (0, sy, sx, 0) — the fraction of the shared texture occupied by the current
@ -95,7 +97,7 @@ pipeline_fragment_main(float2 backbuffer_pos, int group, float4 viewport, float
// shaders can address them in that same space, regardless of the size of the shared texture.
float2 src_scale = float2(max(1e-6, csd.src_rect[right]), max(1e-6, csd.src_rect[top]));
float2 viewport_pos = backbuffer_pos / src_scale;
if (group < 0) return encode_pointer_map(viewport_pos);
if (group < 0) return encode_pointer_map(viewport_pos, active_groups);
// Half a texel inset, in viewport UV, so that clamped samples do not bilinearly blend in the
// stale texels that lie just outside the viewport region of the shared texture.
float2 max_pos = 1.f - 0.5f / max(float2(csd.viewport_size_pixels), float2(1.f));

View file

@ -1810,23 +1810,31 @@ def merge_pipelines(pipelines: list[Pipeline]) -> Pipeline:
}
def group_has_own_animation(group: Group) -> bool:
"Whether the group is turned on and off by events of its own"
return bool(group['animation_start'] or group['animation_toggle'])
def group_moves_content(group: Group) -> bool:
"Whether whatever the shaders in a group do to the content is visible on the whole screen at all times"
"""Whether whatever the shaders in a group do to the content is visible on
the whole screen for as long as the group is active, which is either always
or until an event turns the group off, as opposed to a transient effect that
lasts for a fixed duration"""
return (
not group['animation_start']
and not group['animation_toggle']
and not group['attached']
not group['attached']
and group['output_texture'] is NamedTexture.default
and group['viewport_pos'] == (0, 0)
and group['viewport_size'] == (1, 1)
and (not group_has_own_animation(group) or group['animation_end_duration'] == 0)
)
def pointer_map_shaders(pipeline: Pipeline, defines_pointer_map: Callable[[int, int], bool]) -> tuple[tuple[int, int], ...]:
"""The (group, shader) indices of the shaders whose pointer_map() decides
where pointer events land, in the order they must be applied. Only groups
that draw to the whole screen and are always active move content
permanently, so only they count. The last shader to run decides what is
that draw to the whole screen and are active either always or until an
event turns them off move content for any length of time, so only they
count. The last shader to run decides what is
visible at a given position, so it is applied first. defines_pointer_map()
is called with the (group, shader) indices of the shaders that count."""
ans: list[tuple[int, int]] = []
@ -1948,7 +1956,15 @@ def build_custom_shader_pipeline_ir(pipeline: Pipeline, cache_dir: str, invocati
mod_src = mod_src.replace('// IMPORTS', '\n'.join(f'import {imp};' for imp in imports), 1)
mod_src = mod_src.replace('// PIPELINE', pipeline_code, 1)
pm = pointer_map_shaders(pipeline, lambda g, s: defines_pointer_map(queries[(g, s)]))
pointer_map_code = '\n '.join(f'pos = {entry_point(g, s, "pointer_map")}(pos, csd);' for g, s in pm)
def pointer_map_call(g: int, s: int) -> str:
call = f'pos = {entry_point(g, s, "pointer_map")}(pos, csd);'
if group_has_own_animation(pipeline['groups'][g]):
# Applies only while the group is active
call = f'if ((active_groups & {1 << g}u) != 0u) {call}'
return call
pointer_map_code = '\n '.join(pointer_map_call(g, s) for g, s in pm)
mod_src = mod_src.replace('// POINTER_MAP', pointer_map_code, 1)
# subprocess.run(['bat', '-P', '-l', 'cpp'], input=mod_src.encode())
@ -1990,9 +2006,10 @@ float4 fmain_wrap(
uniform int group,
uniform float4 viewport,
uniform float animation_progress,
uniform bool convert_to_srgb
uniform bool convert_to_srgb,
uniform uint active_groups
) : SV_Target {
return pipeline_fragment_main(texcoord, group, viewport, animation_progress, convert_to_srgb);
return pipeline_fragment_main(texcoord, group, viewport, animation_progress, convert_to_srgb, active_groups);
}
""".replace('MODULE', slot.replace('-', '_')).encode()
@ -2063,6 +2080,7 @@ def build_custom_shader_pipeline_glsl(
m = glsl_metadata_for_shader(metadata)
m['pipeline'] = pipeline
m['has_pointer_map'] = bool(pipeline_ir.pointer_map_shaders)
m['pointer_map_groups'] = sorted({g for g, _ in pipeline_ir.pointer_map_shaders})
return vf.read(), ff.read(), m

View file

@ -633,6 +633,9 @@ typedef struct OSWindow {
float *data;
int viewport_width, viewport_height;
unsigned pipeline_generation;
// Bitmask of the groups whose pointer_map() functions data was computed
// from, zero when there are none and so pointer events are not moved
uint32_t groups;
} pointer_map;
} OSWindow;

View file

@ -127,8 +127,6 @@ class TestSlang(BaseTest):
many = '|'.join(f'user:e{i}' for i in range(MAX_SHADER_ANIM_USER_EVENTS + 1))
self.assertRaises(ValueError, pipeline, f'animation_start {many}')
pipeline(f'animation_start {many.rpartition("|")[0]}')
# Toggled groups do not move content permanently
self.ae(pointer_map_shaders(pipeline('animation_toggle user:t'), lambda g, s: True), ())
# The action
self.ae(parse_key_action('shader_event find-cursor'), KeyAction('shader_event', ('find-cursor', 'active')))
@ -474,6 +472,12 @@ fsMain(VertexOutput vo) : SV_Target { return float4(0); }
self.ae(pms('startgroup\nshaders crt sample crt\nendgroup\nstartgroup\nshaders crt\nendgroup'), ((1, 0), (0, 2), (0, 0)))
# Transient effects and passes that do not draw to the screen do not move pointer events
self.ae(pms('startgroup\nanimation_start tab-change\nshaders crt\nendgroup'), ())
self.ae(pms('startgroup\nanimation_start user:s\nanimation_stop 100\nshaders crt\nendgroup'), ())
self.ae(pms('startgroup\nanimation_toggle user:t\nanimation_stop 100\nshaders crt\nendgroup'), ())
# Effects that last until an event turns them off do
self.ae(pms('startgroup\nanimation_toggle user:t\nshaders crt\nendgroup'), ((0, 0),))
self.ae(pms('startgroup\nanimation_start user:s\nanimation_stop never\nshaders crt\nendgroup'), ((0, 0),))
self.ae(pms('startgroup\nanimation_start user:s\nanimation_stop user:e\nshaders crt\nendgroup'), ((0, 0),))
self.ae(pms('startgroup\nshaders sample\nendgroup\nstartgroup\nattach\nshaders crt\nendgroup'), ())
self.ae(pms('textures a\nstartgroup\nshaders crt\noutput_texture a\nendgroup\nstartgroup\nshaders sample\nendgroup'), ())
# Groups that draw only part of the screen do not move pointer events everywhere
@ -671,6 +675,32 @@ float f() { static const float SCAN = 2; return SCAN; }
self.assertFalse(metadata['has_pointer_map'])
self.assertFalse(invocation_tracker)
with tempfile.TemporaryDirectory() as cache_dir:
clear_caches()
# pointer_map() of a group turned on and off by events applies only while it is active
p = parse_pipeline_definition(
[
'startgroup',
'shaders crt',
'endgroup',
'startgroup',
'shaders sample',
'endgroup',
'startgroup',
'animation_toggle user:t',
'shaders crt',
'endgroup',
],
'test',
)
try:
_, pm_frag_src, pm_metadata = build_custom_shader_pipeline_glsl(p, cache_dir=cache_dir)
finally:
clear_caches()
self.assertTrue(pm_metadata['has_pointer_map'])
self.ae(pm_metadata['pointer_map_groups'], [0, 2])
self.assertIn('active_groups', pm_frag_src)
if not shutil.which('glslangValidator'):
return