From 5bd7f93c1604f10081902dff3cf1fa100eb23532 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Wed, 10 Dec 2025 09:54:20 +1000 Subject: [PATCH] doc/user: add a graph of how different contexts work Part-of: --- doc/user/dot/libinput-contexts.gv | 36 +++++++++++++++++++++++++++++++ doc/user/faqs.rst | 20 +++++++++++++---- doc/user/meson.build | 1 + 3 files changed, 53 insertions(+), 4 deletions(-) create mode 100644 doc/user/dot/libinput-contexts.gv diff --git a/doc/user/dot/libinput-contexts.gv b/doc/user/dot/libinput-contexts.gv new file mode 100644 index 00000000..ff43c192 --- /dev/null +++ b/doc/user/dot/libinput-contexts.gv @@ -0,0 +1,36 @@ +digraph stack +{ + compound=true; + splines=line; + rankdir="LR"; + node [ + shape="box"; + ] + + subgraph cluster_2 { + label="Kernel"; + event0 [label="/dev/input/event0"]; + event1 [label="/dev/input/event1"]; + } + + subgraph cluster_0 { + label="Compositor process"; + libinput [label="libinput context 1"]; + } + + subgraph cluster_1 { + label="libinput debug-events"; + libinput2 [label="libinput context 2"]; + } + + stdout; + + client [label="Wayland client"]; + + event0:e -> libinput:w; + event1:e -> libinput:w; + event0:e -> libinput2:w; + event1:e -> libinput2:w; + libinput -> client [ltail=cluster_0 label="Wayland protocol"]; + libinput2 -> stdout [ltail=cluster_1]; +} diff --git a/doc/user/faqs.rst b/doc/user/faqs.rst index 88d326c9..18260d2c 100644 --- a/doc/user/faqs.rst +++ b/doc/user/faqs.rst @@ -348,10 +348,14 @@ compositor. This indicates a misunderstanding of how libinput works: libinput is a library that converts kernel events into libinput events, much like ``sed`` reads data in, modifies it, and provides it to stdout. -If ``sed`` is used by a shell-script, that script has full control over how -``sed`` processes data. In this analogy, ``sed`` is libinput and the -shell script is the compositor. It is not possible to write a program -to modify the behavior of the ``sed`` instance used inside that shell script +.. graphviz:: libinput-contexts.gv + +A libinput context is private to the process and cannot be modified from the +outside. To use the ``sed`` analogy again: if ``sed`` is used by a +shell-script, that script has full control over how ``sed`` processes data. In +this analogy, ``sed`` is libinput and the shell script is the compositor. It is +not possible to write a program to modify the behavior of the ``sed`` instance +used inside that shell script. Writing a program that uses libinput is akin to writing a new script that invoke ``sed``. It will not have any effect on the original ``sed`` instance. @@ -360,6 +364,14 @@ The only way to modify libinput's behavior is to use the configuration options exposed by the respective compositor. Those affect the libinput context inside the compositor and thus have an effect on the input device behavior. +.. _faq_debug_events_not_showing_configuration: + +------------------------------------------------------------------------------ +Why doesn't libinput debug-events show my configuration +------------------------------------------------------------------------------ + +See :ref:`faq_separate_contexts`. + ------------------------------------------------------------------------------ Can I configure scroll speed? ------------------------------------------------------------------------------ diff --git a/doc/user/meson.build b/doc/user/meson.build index 397392dc..94384492 100644 --- a/doc/user/meson.build +++ b/doc/user/meson.build @@ -95,6 +95,7 @@ src_rst = files( # dot drawings 'dot/seats-sketch.gv', 'dot/seats-sketch-libinput.gv', + 'dot/libinput-contexts.gv', 'dot/libinput-stack-wayland.gv', 'dot/libinput-stack-xorg.gv', 'dot/libinput-stack-gnome.gv',