[docs] guide: document current Looking Glass features

doc/input.rst

@@ -0,0 +1,101 @@
+.. _client_input:
+
+Keyboard and mouse input
+########################
+
+The current IDD provides keyboard and mouse input directly over LGMP. It uses
+absolute positioning for normal desktop use and relative movement in capture
+mode. SPICE remains available as a fallback when direct input is unavailable.
+
+The client changes input provider automatically. If the displayed video has
+fallen back to SPICE, the client also uses SPICE input so that the picture and
+pointer always refer to the same guest.
+
+Only one LGMP client controls direct input at a time. Starting another client
+does not give both clients simultaneous control. Disconnecting or restarting
+the IDD releases held keys and buttons before ownership changes.
+
+Normal input
+------------
+
+Move the pointer into the guest view to use absolute desktop input. This keeps
+the guest pointer aligned without requiring capture.
+
+Direct IDD input supports the keyboard, media keys and up to 32 mouse buttons.
+SPICE fallback uses relative mouse input and supports fewer extra buttons.
+
+Capture mode
+------------
+
+Press the escape key, :kbd:`ScrLk` by default, to capture the mouse. Capture
+mode confines the pointer and sends relative motion, which is appropriate for
+games and applications that lock the cursor. Press the escape key again to
+leave capture mode.
+
+Common capture options are:
+
+``input:captureOnFocus``
+   Enter capture mode whenever the client receives focus.
+
+``input:captureOnStart``
+   Start captured.
+
+``input:captureOnly``
+   Disable guest input outside capture mode.
+
+``input:rawMouse``
+   Use raw relative mouse input in capture mode. This is usually best for
+   games.
+
+``input:mouseSens``
+   Adjust relative sensitivity from -9 to 9. The default is 0.
+
+``input:hideCursor``
+   Hide the host cursor while Looking Glass renders the guest cursor.
+
+Automatic keyboard capture
+--------------------------
+
+Set ``input:autoCapture=yes`` to grab the keyboard when the pointer enters the
+guest view. Looking Glass predicts when the next mouse movement would leave
+the guest area and releases the keyboard before that movement. This makes it
+possible to move naturally between Looking Glass and the Linux desktop without
+using the escape key for the keyboard.
+
+Automatic keyboard capture is disabled by ``input:captureOnly=yes``. It also
+keeps the keyboard grabbed while a mouse button is held so that dragging does
+not unexpectedly leave the guest.
+
+This is separate from full mouse capture: the pointer remains in normal
+absolute mode. Use regular capture mode when an application requires relative
+mouse input.
+
+``input:grabKeyboardOnFocus`` instead keeps the keyboard grabbed while the
+guest view is active. ``input:grabKeyboard`` controls whether full capture
+mode grabs the keyboard.
+
+SPICE fallback
+--------------
+
+Keep ``spice:input=yes`` when SPICE input fallback is wanted. It uses the VM's
+default PS/2 keyboard and mouse, so no additional virtio input devices or
+tablet are required.
+
+To disable all SPICE input while keeping SPICE audio or clipboard services:
+
+.. code-block:: ini
+
+   [spice]
+   input=no
+
+If direct input is also unavailable, the client will display video without
+being able to control the guest.
+
+Evdev capture
+-------------
+
+Advanced users may list Linux evdev devices in ``input:evdev``. They become
+active whenever Looking Glass grabs the keyboard, including capture mode and
+automatic keyboard capture. The client user must be allowed to read those
+devices. Keep ``input:evdevExclusive=yes`` unless duplicate input from the
+window system is specifically required.