From d04d0c19dd9425f3394e9b4205f983a7939b6039 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Mon, 22 Dec 2014 10:33:55 +1000 Subject: [PATCH] doc: improve seat documentation Signed-off-by: Peter Hutterer --- doc/Makefile.am | 3 +- doc/dot/seats-sketch-libinput.gv | 29 ++++++++++++++ doc/dot/seats-sketch.gv | 18 +++++++-- doc/seats.dox | 67 ++++++++++++++++++++++++++++++-- src/libinput.h | 25 ++---------- 5 files changed, 113 insertions(+), 29 deletions(-) create mode 100644 doc/dot/seats-sketch-libinput.gv diff --git a/doc/Makefile.am b/doc/Makefile.am index ccb790da..28933384 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -15,7 +15,8 @@ header_files = \ $(srcdir)/t440-support.dox diagram_files = \ - $(srcdir)/dot/seats-sketch.gv + $(srcdir)/dot/seats-sketch.gv \ + $(srcdir)/dot/seats-sketch-libinput.gv html/index.html: libinput.doxygen $(header_files) $(diagram_files) $(AM_V_GEN)(cat $<; \ diff --git a/doc/dot/seats-sketch-libinput.gv b/doc/dot/seats-sketch-libinput.gv new file mode 100644 index 00000000..b0216563 --- /dev/null +++ b/doc/dot/seats-sketch-libinput.gv @@ -0,0 +1,29 @@ +digraph seats_libinput +{ + rankdir="BT"; + node [ + shape="box"; + ] + + ctx1 [label="libinput context 1"; URL="\ref libinput"]; + ctx2 [label="libinput context 2"; URL="\ref libinput"]; + + seat0 [ label="seat phys 0 logical A"]; + seat1 [ label="seat phys 0 logical B"]; + seat2 [ label="seat phys 1 logical C"]; + + dev1 [label="device 'Foo'"]; + dev2 [label="device 'Bar'"]; + dev3 [label="device 'Spam'"]; + dev4 [label="device 'Egg'"]; + + ctx1 -> dev1 + ctx1 -> dev2 + ctx1 -> dev3 + ctx2 -> dev4 + + dev1 -> seat0 + dev2 -> seat0 + dev3 -> seat1 + dev4 -> seat2 +} diff --git a/doc/dot/seats-sketch.gv b/doc/dot/seats-sketch.gv index f537df1a..3647cef8 100644 --- a/doc/dot/seats-sketch.gv +++ b/doc/dot/seats-sketch.gv @@ -15,13 +15,18 @@ digraph seats pseat0 [label="phys seat0"; URL="\ref libinput_seat_get_physical_name"]; pseat1 [label="phys seat1"; URL="\ref libinput_seat_get_physical_name"]; - lseatA [label="log seat A"; URL="\ref libinput_seat_get_logical_name"]; - lseatB [label="log seat B"; URL="\ref libinput_seat_get_logical_name"]; - lseatC [label="log seat C"; URL="\ref libinput_seat_get_logical_name"]; + lseatA [label="logical seat A"; URL="\ref libinput_seat_get_logical_name"]; + lseatB [label="logical seat B"; URL="\ref libinput_seat_get_logical_name"]; + lseatC [label="logical seat C"; URL="\ref libinput_seat_get_logical_name"]; ctx1 [label="libinput context 1"; URL="\ref libinput"]; ctx2 [label="libinput context 2"; URL="\ref libinput"]; + dev1 [label="device 'Foo'"]; + dev2 [label="device 'Bar'"]; + dev3 [label="device 'Spam'"]; + dev4 [label="device 'Egg'"]; + kernel -> event0 kernel -> event1 kernel -> event2 @@ -38,4 +43,9 @@ digraph seats ctx1 -> lseatA ctx1 -> lseatB ctx2 -> lseatC -} \ No newline at end of file + + lseatA -> dev1 + lseatA -> dev2 + lseatB -> dev3 + lseatC -> dev4 +} diff --git a/doc/seats.dox b/doc/seats.dox index 09094508..5eec5ded 100644 --- a/doc/seats.dox +++ b/doc/seats.dox @@ -1,12 +1,73 @@ /** @page seats Seats -Each device in libinput is associated with one physical seat and one logical seat. +Each device in libinput is assigned to one seat. +A seat has two identifiers, the physical name and the logical name. The +physical name is summarized as the list of devices a process on the same +physical seat has access to. The logical seat name is the seat name for a +logical group of devices. A compositor may use that to create additonal +seats as independent device sets. Alternatively, a compositor may limit +itself to a single logical seat, leaving a second compositor to manage +devices on the other logical seats. -@section seats_overview Overview +@section Overview + +Below is an illustration of how physical seats and logical seats interact: @dotfile seats-sketch.gv -Details pending. +The devices "Foo", "Bar" and "Spam" share the same physical seat and are +thus available in the same libinput context. Only "Foo" and "Bar" share the +same logical seat. The device "Egg" is not available in the libinput context +associated with the physical seat 0. + +The above graph is for illustration purposes only. In libinput, a struct +@ref libinput_seat comprises both physical seat and logical seat. From a +caller's point-of-view the above device layout is presented as: + +@dotfile seats-sketch-libinput.gv + +Thus, devices "Foo" and "Bar" both reference the same struct @ref +libinput_seat, all other devices reference their own respective seats. + +@section seats_and_features The effect of seat assignment + +A logical set is interprested as a group of devices that usually belong to a +single user that interacts with a computer. Thus, the devices are +semantically related. This means for devices within the same logical seat: + +- if the same button is pressed on different devices, the button should only + be considered logically pressed once. +- if the same button is released on one device, the button should be + considered logically down if still down on another device. +- if two different buttons or keys are pressed on different devices, the + logical state is that of both buttons/keys down. +- if a button is pressed on one device and another device moves, this should + count as dragging. +- if two touches are down on different devices, the logical state is that of + two touches down. + +libinput provides functions to aid with the above: +libinput_event_pointer_get_seat_button_count(), +libinput_event_keyboard_get_seat_key_count(), and +libinput_event_touch_get_seat_slot(). + +Internally, libinput counts devices within the same logical seat as related. +Cross-device features only activate if all required devices are in the same +logical seat. For example, libinput will only activate the top software +buttons (see @ref t440_support) if both trackstick and touchpad are assigned +to the same logical seat. + + +@section changing_seats Changing seats + +A device may change the logical seat it is assigned to at runtime with +libinput_device_set_seat_logical_name(). The physical seat is immutable and +may not be changed. + +Changing the logical seat for a device is equivalent to unplugging the +device and plugging it back in with the new logical seat. No device state +carries over across a logical seat change. + */ diff --git a/src/libinput.h b/src/libinput.h index a6eddae9..e156a3a0 100644 --- a/src/libinput.h +++ b/src/libinput.h @@ -1139,27 +1139,10 @@ libinput_log_set_handler(struct libinput *libinput, /** * @defgroup seat Initialization and manipulation of seats * - * A seat has two identifiers, the physical name and the logical name. The - * physical name is summarized as the list of devices a process on the same - * physical seat has access to. - * - * The logical seat name is the seat name for a logical group of devices. A - * compositor may use that to create additonal seats as independent device - * sets. Alternatively, a compositor may limit itself to a single logical - * seat, leaving a second compositor to manage devices on the other logical - * seats. - * - * @code - * +---+--------+------------+------------------------+------------+ - * | | event0 | | | log seat A | - * | K +--------+ | +------------+ - * | e | event1 | phys seat0 | libinput context 1 | | - * | r +--------+ | | log seat B | - * | n | event2 | | | | - * | e +--------+------------+------------------------+------------+ - * | l | event3 | phys seat1 | libinput context 2 | log seat C | - * +---+--------+------------+------------------------+------------+ - * @endcode + * A seat has two identifiers, the physical name and the logical name. A + * device is always assigned to exactly one seat. It may change to a + * different logical seat but it cannot change physical seats. See @ref + * seats for details. */ /** -- 2.34.1