From b4a7cc9655a09bf49cd2e35113360fe0c4510ea5 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Tue, 7 Jun 2022 10:29:58 +1000 Subject: [PATCH] README: update with info about sender/receiver modes And make a note about the protocol eventually maybe becoming an actual protocol. --- README.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 67131cd..426c219 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,8 @@ stack. It provides three parts: The communication between these parts is an implementation detail, neither client nor server need to care about the details. Let's call it the BRidge -for EI, or 🥣 brei. +for EI, or 🥣 brei. In the future, 🥣 brei may become a stable protocol. For +now, this C library is it. For the purpose of this document, **libei** refers to the project, `libei`/`libeis`/`libreis` to the libraries provided. @@ -40,7 +41,8 @@ compositor, the EI client component is part of the Wayland client. The use-cases **libei** attempts to solve are: - on-demand input device emulation, e.g. `xdotool` or more generically the XTEST extension -- input forwarding, e.g. `synergy` +- input forwarding, e.g. `synergy`, for both client-emulated input as well as + the forwarding of physical or logical devices. **libei** provides three benefits: - separation @@ -62,6 +64,25 @@ discard at will. For example, if the current focus window is a password prompt, the server can simply discard any emulated input. If the screen is locked, the server can pause all emulated input devices. +Sender vs receiver contexts +--------------------------- + +As of version 0.3, libei allows a ``libei`` context to be either a sender or a +receiver. In the "sender" mode, the ``libei`` context gets a list of devices +from the EIS implementation and can emulate events on these devices. The +devices usually represent virtual devices, e.g. a generic relative pointer +corresponding to the cursor or per-screen absolute input devices. + +In the "receiver" mode, the ``libei`` context gets a list of devices from the +EIS implementation and *receives* events from those. This allows for input +capture, provided the EIS implementation supports it. The devices can +correspond to virtual devices, e.g. a generic relative pointer corresponding +to the cursor. Or they may be representations of physical devices, e.g. a +tablet device getting forwarded. + +A ``libei`` context may only be in one mode. It is up to the EIS +implementation to accept a sender or receiver ``libei`` context. + Why not $foo? ------------- @@ -138,7 +159,9 @@ For a `synergy` use-case, the setup requires: forwards those to the remote `synergy-server` which sends them via `libei` to the compositor B. -**libei** does not provide a method for capturing events. +**libei** does not provide a method for deciding when events should be +captured, it merely provides the transport layer for events once that decision +has been made. Using REIS ----------