[release] B8-rc1

After many months of hard work from our team, I am pleased to announce
Beta 8 Release Candidate 1.

B8 is a major update that introduces the Looking Glass Indirect Display
Driver, direct input and clipboard transport, a new USB audio path,
end-to-end HDR support, and extensive latency and reliability
improvements.

As this is a release candidate, please report any regressions or other
issues encountered during testing.

If you like this project, find it useful, and would like to help support
its continued development, you can do so using the following platforms:

* [GitHub][github]
* [Ko-Fi][kofi]
* [Patreon][patreon]
* [PayPal][paypal]
* BTC: `14ZFcYjsKPiVreHqcaekvHGL846u3ZuT13`
* ETH: `0x6f8aEe454384122bF9ed28f025FBCe2Bce98db85`
* XMR: `47xM4zG7b2tEj4mnSywHve4ydZzn3wzhf22snDRB7aSEcXrgUBpoT2Z4phTnyFMi1sMyQtHbdufMYRQ2PzMn3PGUJAE1dpc`

[github]: https://github.com/sponsors/gnif
[kofi]: https://ko-fi.com/lookingglass
[patreon]: https://www.patreon.com/gnif
[paypal]: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick& hosted_button_id=ESQ72XUPGKXRY

B8 introduces protocol changes that are not compatible with B7. The
Looking Glass client, IDD, and OBS plugin must use matching versions.

The legacy Host Application remains available as a B7 workflow. Users
who require it should retain the complete B7 client, Host Application,
and OBS stack rather than mixing B7 and B8 components.

B8 requires Windows 10 version 1903 or newer. HDR and wide-color support
normally require compatible Windows 11 IddCx interfaces. Windows 10
continues to use the SDR-compatible path.

The Looking Glass Indirect Display Driver is now the recommended Windows
server. It creates its own virtual monitor, eliminating the need for a
physical display or dummy plug.

The IDD uses Direct3D 12 for accelerated capture and processing when a
suitable GPU is available. An SDR software fallback supports systems
without a usable render GPU.

A new installer includes the display driver, direct-input driver, tray
helper, and optional IVSHMEM driver installation. It can also disable
the legacy Host Application during migration.

The configuration interface supports custom resolutions, fractional
refresh rates up to 1000 Hz, preferred and default modes, dynamic guest
resolution, configuration reload and rollback, processing status, and
workarounds for problematic GPU drivers.

Keyboard and mouse input can now travel directly over LGMP using the
Looking Glass virtual HID device. This supports absolute desktop input,
relative captured input, media keys, up to 32 mouse buttons, and
keyboard lock-state synchronization.

Clipboard synchronization also runs directly over LGMP and supports
bidirectional text, images, and file transfers on both X11 and Wayland.
Transfers are streamed and pipelined to keep clipboard control
responsive while large files are being copied.

SPICE remains available as a fallback, but is no longer required for
primary IDD input or clipboard operation.

Looking Glass can now present an emulated USB Audio Class 2 device to
Windows through a SPICE USB-redirection channel.

It supports stereo, quadraphonic, 5.1, and 7.1 playback using 24-bit PCM
at up to 192 kHz, along with microphone recording and asynchronous clock
feedback. Classic SPICE audio remains available as a compatibility
fallback.

Audio buffering, synchronization, underrun recovery, and microphone
privacy handling have also been substantially improved.

B8 adds end-to-end HDR and wide-color support. The IDD transports HDR
metadata and the Windows display color transform, while the EGL renderer
can either present native HDR or tone-map it for an SDR display.

Native Linux HDR requires Wayland, an HDR-capable output, and compositor
support for `color-management-v1`. The OBS plugin can also capture the
HDR stream directly.

The IDD, client, and OBS plugin now coordinate frame delivery around
presentation deadlines. Superseded frames can be discarded before
transport, static regions avoid unnecessary copies, and different
consumers can operate at independent cadences.

Expanded timing graphs expose capture, GPU processing, shared-memory
transport, rendering, and presentation latency.

* Added the Looking Glass IDD as the recommended Windows server.
* Added a virtual monitor that does not require a dummy plug.
* Added accelerated Direct3D 12 capture and processing.
* Added an SDR software fallback for guests without a suitable GPU.
* Added a unified IDD, input driver, helper, and IVSHMEM installer.
* Added a tray configuration interface for display modes and status.
* Added custom resolutions and fractional refresh rates up to 1000 Hz.
* Added preferred modes, default refresh rates, and dynamic resolution.
* Added selectable direct-copy and indirect-copy GPU workarounds.
* Added filtering and sizing guidance for modes too large for IVSHMEM.
* Added direct keyboard and mouse input over LGMP.
* Added absolute and captured-relative mouse input modes.
* Added media-key, extended mouse-button, and keyboard LED support.
* Improved automatic keyboard capture and X11/Wayland input parity.
* Completed evdev hotplug, capture, mouse, and LED handling.
* Added direct bidirectional clipboard synchronization over LGMP.
* Added clipboard support for text, images, and files.
* Added seamless clipboard file handling for X11 and Wayland.
* Improved Caja, MATE, and Nautilus clipboard interoperability.
* Added streamed and pipelined clipboard transfers.
* Added the emulated Looking Glass USB Audio Class 2 device.
* Added multichannel 24-bit playback at up to 192 kHz.
* Added USB microphone recording and asynchronous clock feedback.
* Improved audio synchronization, jitter handling, and underrun
  recovery.
* Added HDR metadata and Windows display color-transform transport.
* Added native Wayland HDR using `color-management-v1`.
* Improved HDR-to-SDR tone mapping and SDR white-level handling.
* Added HDR support to the OBS plugin.
* Added presentation-aware frame scheduling across IDD, client, and OBS.
* Added damage-aware GPU copies and software texture uploads.
* Added independent scheduling for multiple frame consumers.
* Added expanded capture, transport, rendering, and presentation graphs.
* Added automatic SPICE fallback and session recovery.
* Added forced display recovery using the configured escape key plus
  `Shift+R`—`Scroll Lock+Shift+R` by default.
* Added mpv-compatible custom GLSL shader loading.
* Improved Wayland fractional scaling, pointer confinement, and warping.
* Improved DMA-BUF ownership, import performance, and damage handling.
* Added layout-independent hotkeys with translated key labels.
* Added non-Latin text support to the client overlay.
* Hardened shared-memory frame, cursor, queue, and clipboard validation.
* Retained aliases for settings moved from `app:*` to `lgmp:*`.
* Made RGB24 packing opt-in due to regressions on some integrated GPUs.
* Reworked the documentation around the current IDD workflow.
* Set Windows 10 version 1903 as the minimum supported guest.

doc/audio.rst

@@ -4,7 +4,7 @@ Audio and microphone
 ####################
 
 The client selects audio independently from video and input. The current LGMP
-transport does not provide audio, so SPICE normally supplies it in an IDD
+transport does not provide audio, so SPICE is used to deliver audio in an IDD
 setup. Selecting SPICE as the primary video transport also uses its audio
 provider.
 
@@ -25,7 +25,7 @@ USB audio (recommended)
 
 Classic SPICE audio
    Uses a virtual guest sound card and SPICE playback and record channels.
-   QEMU limits it to stereo, 16-bit samples at 48 kHz. Use it as a compatibility
+   QEMU limits it to stereo, 16-bit samples at 48 kHz. Use as a compatibility
    fallback when the emulated USB audio device is not available.
 
 Set ``spice:audio=no`` to disable both paths.
@@ -37,19 +37,46 @@ USB audio setup
 
 USB audio requires:
 
-* a client built with ``libusbredirparser-0.5`` version 0.7.1 or newer;
-* at least one unused SPICE USB redirection channel in the VM; and
+* a client built with ``libusbredirparser-dev`` (see :ref:`Installing build dependencies -> Audio <client_deps_audio>`);
+* a SPICE server
+* at least one unused SPICE USB redirection channel; and
 * a working client playback backend.
 
-For libvirt, add a USB redirection device:
+For libvirt, add a SPICE server:
 
 .. code:: xml
 
-   <redirdev bus='usb' type='spicevmc'/>
+   <devices>
+      <graphics type='spice'/>
+   </devices>
 
-In virt-manager, this is a **USB Redirector** device using the SPICE channel.
-It is dedicated to the virtual Looking Glass audio device while USB audio is
-active.
+and a USB redirection device:
+
+.. code:: xml
+
+   <devices>
+      <redirdev bus='usb' type='spicevmc'/>
+   </devices>
+
+The USB redirection device is dedicated to the virtual Looking Glass audio
+device while USB audio is active.
+
+For QEMU:
+
+.. code:: bash
+
+   -chardev spicevmc,name=usbredir,id=usbredirchar1 \
+   -device usb-redir,chardev=usbredirchar1,id=usbredirdev1,bus=xhci.0
+
+.. note::
+
+   This redirection channel is dedicated to the virtual Looking Glass audio
+   device while USB audio is active. If you want to redirect another USB device
+   at the same time, you must create another channel.
+
+   When creating an extra USB redirection channel, you have to choose a new
+   ``port`` (for libvirt) or ``id`` (for QEMU), as they must be unique.
+   Incrementing the number to the lowest one available is enough.
 
 The emulated USB audio device is enabled by default. Its settings are:
 
@@ -66,10 +93,10 @@ Playback supports stereo, quadraphonic, 5.1 and 7.1 speaker layouts using
 After the device connects, select the Looking Glass USB Audio speakers as the
 Windows output device.
 
-If USB audio could not be created at startup, the client falls back to classic
-SPICE audio and logs the reason. A working USB audio device also requires the
-SPICE USB redirection channel to connect; if the channel is absent, add it to
-the VM rather than reinstalling the Windows endpoint.
+If USB audio cannot not be created at startup, the client will fall back to
+classic SPICE audio and log the reason. A working USB audio device also requires
+the SPICE USB redirection channel to connect; if there are not enough channels,
+add a new one rather than reinstalling the Windows endpoint.
 
 Classic SPICE setup
 -------------------

doc/build.rst

@@ -4,8 +4,9 @@ Build the Linux client
 ######################
 
 The Looking Glass Client is currently distributed as source code. Building it
-is a normal part of installation, not an optional developer step. These
-instructions require basic familiarity with a Linux shell.
+is a normal part of installation, as no packages are available during the
+development phase. These instructions require basic familiarity with a Linux
+shell.
 
 .. _download_source:
 
@@ -32,10 +33,10 @@ Developers can clone the source code repo with ``git``.
 
 .. note::
 
-   The current client, IDD and OBS plugin must come from the same Looking Glass
-   release. Bleeding-edge builds must be paired with their matching
-   bleeding-edge components. Legacy Host users must instead use the complete
-   matching B7 stack described in :ref:`legacy_host_policy`.
+   The Looking Glass client, IDD and OBS plugin (if used) must be of the same version.
+   Bleeding-edge builds must be paired with bleeding-edge components of the same
+   version. Legacy Host users must instead use the complete matching B7 stack
+   described in :ref:`legacy_host_policy`.
 
 .. _build_client_section:
 
@@ -68,13 +69,14 @@ Required dependencies
    Depends: or Recommends: from another listed package is not allowed.
    All required packages must be listed.
 
--  ``cmake``
 -  ``binutils``
+-  ``cmake``
 -  ``gcc``, ``g++`` \| ``clang``
 -  ``libegl-dev``
+-  ``libfontconfig-dev``
+-  ``libfuse3-dev``
 -  ``libgl-dev``
 -  ``libgles-dev``
--  ``libfontconfig-dev``
 -  ``libgmp-dev``
 -  ``libspice-protocol-dev``
 -  ``libxkbcommon-dev``
@@ -90,12 +92,12 @@ May be disabled
 These dependencies are required by default, but may be omitted if their
 feature is disabled when running :ref:`cmake <client_building>`.
 
--  Disable with ``cmake -DENABLE_BACKTRACE=no ..``
+-  Disable backtrace support with ``cmake -DENABLE_BACKTRACE=no ..``
 
    -  ``libdw-dev``
    -  ``libunwind-dev``
 
--  Disable with ``cmake -DENABLE_X11=no ..``
+-  Disable X11 support with ``cmake -DENABLE_X11=no ..``
 
    -  ``libx11-dev``
    -  ``libxfixes-dev``
@@ -106,39 +108,41 @@ feature is disabled when running :ref:`cmake <client_building>`.
    -  ``libxpresent-dev``
    -  ``libxrandr-dev``
 
--  Disable with ``cmake -DENABLE_WAYLAND=no ..``
+-  Disable Wayland support with ``cmake -DENABLE_WAYLAND=no ..``
 
    -  ``libwayland-bin``
    -  ``libwayland-dev``
 
--  Disable all audio support with ``cmake -DENABLE_AUDIO=no ..``
+.. _client_deps_audio:
+
+Audio
+/////
+
+-  Disable all audio with ``cmake -DENABLE_AUDIO=no ..```
+
+   - ``libsamplerate0-dev``
+
+-  Disable PipeWire support with ``cmake -DENABLE_PIPEWIRE=no ..``
 
    -  ``libpipewire-0.3-dev``
+
+-  Disable PulseAudio support with ``cmake -DENABLE_PULSEAUDIO=no ..``
+
    -  ``libpulse-dev``
-   -  ``libsamplerate0-dev``
+
+-  Disable USB audio support with ``cmake -DENABLE_USB_AUDIO=no ..``
+
    -  ``libusbredirparser-dev``
 
--  Disable with ``cmake -DENABLE_PIPEWIRE=no ..``
-
-   -  ``libpipewire-0.3-dev``
-
--  Disable with ``cmake -DENABLE_PULSEAUDIO=no ..``
-
-   -  ``libpulse-dev``
-
--  Disable USB audio with ``cmake -DENABLE_USB_AUDIO=no ..``
-
-   -  ``libusbredirparser-dev`` version 0.7.1 or newer
-
-``libsamplerate0-dev`` is required whenever audio support remains enabled.
-
 .. _client_deps_recommended:
 
 Recommended
 <<<<<<<<<<<
 
--  ``fonts-dejavu-core`` (This is the default UI font, but a random font will
-   be chosen if not available).
+-  ``fonts-dejavu-core``
+
+   -  This is the default UI font
+   - A random font will be chosen if not available
 
 .. _client_fetching_with_apt:
 
@@ -147,17 +151,10 @@ Fetching with APT
 
 You can fetch these dependencies with the following command:
 
-.. warning::
-
-   The command below builds both PipeWire and PulseAudio playback backends.
-   Omit one development package only when also disabling its backend in CMake.
-   Microphone recording requires PipeWire; the current PulseAudio backend is
-   playback-only.
-
 .. code:: bash
 
-   apt-get install binutils cmake make fonts-dejavu-core libdw-dev \
-   libfontconfig-dev libgmp-dev libunwind-dev gcc g++ pkg-config \
+   apt-get install binutils cmake make fonts-dejavu-core gcc g++ libdw-dev \
+   libfontconfig-dev libfuse3-dev libgmp-dev libunwind-dev pkg-config \
    libegl-dev libgl-dev libgles-dev libspice-protocol-dev nettle-dev \
    libx11-dev libxcursor-dev libxfixes-dev libxi-dev libxinerama-dev \
    libxpresent-dev libxrandr-dev libxss-dev libxkbcommon-dev \
@@ -176,7 +173,7 @@ Building
 
 If you've downloaded the source code as a zip file, simply unzip and ``cd``
 into the new directory. If you've cloned the repo with ``git``, then ``cd``
-into the *LookingGlass* directory.
+into the *LookingGlass* directory. Run these commands in a terminal:
 
 .. code:: bash
 

doc/build_host.rst

@@ -6,9 +6,7 @@ Legacy Host Application build
 .. warning::
 
    The Host Application is a legacy server application. New installations should
-   use the prebuilt :doc:`Looking Glass IDD <install_idd>`. These build
-   instructions are retained for the complete matching B7 stack described in
-   :ref:`legacy_host_policy`.
+   use the :doc:`Looking Glass IDD <install_idd>`.
 
 .. note::
 
@@ -29,10 +27,10 @@ These instructions help you build the host yourself from the
 .. warning::
    :name: dont-build-the-host
 
-   Building the host from source code is not recommended for most purposes,
-   and should only be attempted by users who are prepared to handle issues
-   on their own. Please download the pre-built binary installers from
-   https://looking-glass.io/downloads for stability, and increased support.
+   Building the legacy host from source code is not recommended for most
+   purposes, and should only be attempted by users who are prepared to handle
+   issues on their own. Please download the pre-built binary installers from
+   https://looking-glass.io/downloads for stability.
 
    .. note::
 

doc/conf.py

@@ -27,6 +27,7 @@ author = 'Geoffrey McRae and the Looking Glass team'
 
 rst_prolog = """
 .. |license| replace:: GPLv2
+.. |debian_stable| replace:: trixie
 """
 
 # -- General configuration ---------------------------------------------------

doc/display.rst

@@ -13,6 +13,8 @@ when ``WAYLAND_DISPLAY`` is set, then X11 when ``DISPLAY`` is set. To force X11
 from a Wayland session for diagnosis, preserve ``DISPLAY`` and unset
 ``WAYLAND_DISPLAY`` for the client process.
 
+.. _client_resolution:
+
 Window and guest resolution
 ---------------------------
 
@@ -38,12 +40,15 @@ Useful window options include:
 ``win:rotate``
    Rotate the image by 0, 90, 180 or 270 degrees.
 
+.. _client_scaling_filters:
+
 Scaling and filters
 -------------------
 
-The overlay's **EGL filters** page controls scaling, sharpening and custom
-processing. Filters run from top to bottom and can be reordered. Save useful
-combinations as named presets, then select one at startup with ``egl:preset``.
+The overlay (enabled with :kbd:`ScrLk` + :kbd:`O`) has an **EGL filters** page,
+which controls scaling, sharpening and custom processing. Filters run from top
+to bottom and can be reordered. Save useful combinations as named presets, then
+select one at startup with ``egl:preset``.
 
 The built-in filters include:
 
@@ -62,10 +67,10 @@ GLSL filters.
 HDR
 ---
 
-The IDD exposes HDR only when the Windows runtime provides the required IddCx
-interfaces and the IDD is using a hardware render adapter. This normally means
-a compatible Windows 11 guest. Windows 10 and IDD software processing remain
-on the SDR path.
+The IDD exposes HDR when the Windows runtime provides the required IddCx
+interfaces and the IDD is using a hardware render adapter. This normally means a
+compatible Windows 11 guest. Windows 10 and IDD software processing still use
+SDR.
 
 Native HDR output on Linux requires all of the following:
 
@@ -78,18 +83,23 @@ With ``egl:mapHDRtoSDR=yes`` the client tone-maps HDR frames for an SDR desktop.
 Use ``egl:peakLuminance`` to describe the SDR display target and
 ``egl:maxCLL`` to limit the assumed content light level.
 
-X11 presentation is SDR. The EGL renderer tone-maps HDR to SDR there by
+X11 presentation uses SDR, and the EGL renderer tone-maps HDR to SDR there by
 default. Native Wayland PQ output also requires compositor support for ST 2084
 and BT.2020, while scRGB requires compositor scRGB support.
 
+.. _client_display_latency:
+
 Presentation latency
 --------------------
 
-The defaults favor low latency rather than conventional buffered rendering.
-Do not enable ``egl:vsync`` or ``egl:doubleBuffer`` merely to chase a reported
-frame-rate number; either can add presentation delay. Use the timing graphs to
-confirm the result on the actual compositor and GPU.
+The Looking Glass client defaults favor low latency rather than conventional
+buffered rendering. ``egl:vsync`` and ``egl:doubleBuffer`` can add latency and
+should only be used when necessary.
 
 ``win:jitRender`` delays rendering toward the expected presentation deadline.
 It can reduce the age of a frame at display time, but depends on stable timing.
 Leave it disabled while diagnosing stalls or an unstable refresh cadence.
+
+.. seealso::
+
+   :ref:`client_performance`

doc/faq.rst

@@ -1,6 +1,10 @@
+.. _frequently_asked_questions:
+
 Frequently asked questions
 ##########################
 
+.. _faq_general:
+
 General
 -------
 
@@ -47,26 +51,28 @@ Is a passed-through GPU required?
 
 No. The IDD can create an SDR display using software processing when it cannot
 use a Windows render adapter. A hardware adapter is strongly recommended for
-lower latency, higher refresh rates, HDR, and cadence scheduling.
+lower latency, higher refresh rates, HDR, and cadence scheduling; however,
+software rendering is sufficient for less demanding applications, such as
+basic word processing or spreadsheets.
 
 The Linux client still needs an EGL-capable host graphics driver. Direct
 DMA-BUF import depends on the host GPU and driver; the client falls back to a
 copy when it is unavailable.
 
-.. _why_do_i_need_spice_if_i_dont_want_a_spice_display_device:
+.. _do_i_need_spice:
 
 Do I need SPICE?
 ~~~~~~~~~~~~~~~~
 
-SPICE is not required for the primary IDD video or direct input paths. It is
-still useful for clipboard, audio, input fallback and automatic video fallback.
-These services are selected independently.
+SPICE is not required for the primary IDD video, direct input paths, or IDD
+clipboard support. It is still useful for audio, input and clipboard fallback,
+and automatic video fallback. These services are selected independently.
 
 Set ``spice:enable=no`` or use ``-s`` to disable SPICE completely. Disable an
 individual service with ``spice:input``, ``spice:clipboard`` or
 ``spice:audio`` instead when the other services are still wanted.
 
-.. _where_is_the_host_application_for_linux:
+.. _which_app_runs_on_linux:
 
 Which application runs on Linux?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -75,6 +81,8 @@ The Looking Glass Client runs on the Linux host operating system. The IDD runs
 inside the Windows guest. The older product named the **Host Application** is a
 legacy Windows server; “Host” in that name does not mean the Linux host OS.
 
+.. _faq_input_and_window_system:
+
 Input and window system
 -----------------------
 
@@ -90,9 +98,8 @@ protocol. Build Looking Glass with libdecor support:
 
    cmake -DENABLE_LIBDECOR=ON ../
 
-Install ``libdecor-0-dev`` first on Debian-based systems. Alternatively, hold
-the Super key and right-click the window to use the compositor's move and
-resize menu.
+Install ``libdecor-0-dev`` first. Alternatively, hold the Super key and 
+right-click the window to use the compositor's move and resize menu.
 
 .. _the_mouse_is_jumpy_slow_laggy_when_using_spice:
 
@@ -106,7 +113,7 @@ mouse acceleration can change its feel or cause temporary position error.
 Use the direct IDD input path when available. For a game, use capture mode and
 consider ``input:rawMouse=yes``.
 
-.. _the_cursor_position_doesnt_update_until_i_click:
+.. _should_i_add_a_tablet_device:
 
 Should I add a virtual tablet?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -115,6 +122,8 @@ No. Looking Glass does not require an additional virtio tablet, mouse or
 keyboard. Direct IDD input provides its own absolute and relative devices, and
 SPICE fallback uses the VM's default PS/2 input devices.
 
+.. _faq_audio:
+
 Audio
 -----
 
@@ -124,8 +133,9 @@ Does Looking Glass support microphone input and surround sound?
 Yes. The recommended emulated USB Audio 2.0 device provides stereo,
 quadraphonic, 5.1 and 7.1 playback plus stereo recording at rates up to
 192 kHz. Classic SPICE audio also provides playback and recording. Client
-microphone recording currently requires the PipeWire backend. See
-:doc:`audio`.
+microphone recording currently requires the PipeWire backend. See :doc:`audio`.
+
+.. _faq_host:
 
 Legacy Host Application
 -----------------------
@@ -133,16 +143,16 @@ Legacy Host Application
 The sections below apply only to the legacy Windows Host Application. New
 installations should use the IDD. See :ref:`legacy_host_policy`.
 
-.. _faq_host:
+.. _faq_host_log:
 
-Where is the legacy Host log?
+Where is the legacy host log?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The application log is:
+The application log is found at:
 
 ``%ProgramData%\Looking Glass (host)\looking-glass-host.txt``
 
-The service log is:
+The service log is found at:
 
 ``%ProgramData%\Looking Glass (host)\looking-glass-host-service.txt``
 
@@ -153,7 +163,7 @@ Why does the legacy Host require administrator privileges?
 
 The legacy capture APIs use privileged functions for GPU scheduling, NvFBC
 setup and secure-desktop capture. The installer runs it as a Windows service
-under the SYSTEM account. This is not how the current IDD is configured.
+under the SYSTEM account. This is not how the IDD is configured.
 
 .. _nvfbc_nvidia_capture_api_doesnt_work:
 
@@ -161,7 +171,7 @@ Why does NvFBC not work?
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 NvFBC is a legacy Host capture method and requires supported NVIDIA hardware
-and SDK licensing. It is not part of the IDD path.
+and SDK licensing. The IDD does not support it.
 
 .. _the_screen_stops_updating_when_left_idle_for_a_time:
 
@@ -169,17 +179,17 @@ Why does a legacy captured display stop when idle?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Windows may turn off the physical or dummy display captured by the legacy
-Host. Disable display sleep for that monitor. The IDD virtual-monitor path does
-not require a physical display.
+Host. Disable display sleep for that monitor. The IDD virtual monitor does not
+require a physical display.
 
 .. _a_note_about_ivshmem_and_scream_audio:
 
-Can Scream and Looking Glass share IVSHMEM?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Can Scream and Looking Glass share an IVSHMEM device?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Do not use Scream with Looking Glass. Use the built-in classic SPICE or USB
-audio path instead. In particular, Scream's IVSHMEM transport can select or
-interfere with the shared device used for Looking Glass frames.
+Scream and Looking Glass should not be used at the same time, use the built-in
+classic SPICE or USB audio path instead. In particular, Scream's IVSHMEM
+transport can select or interfere with the shared device used by Looking Glass.
 
 Technical details
 -----------------

doc/host_usage.rst

@@ -6,17 +6,14 @@ Legacy Host Application configuration
 .. warning::
 
    This page applies only to the legacy Windows Host Application. New
-   installations should use the IDD. B7 is the last recommended complete stack
-   when non-capture mouse input through the Host Application is required.
+   installations should use the IDD. B7 is the last recommended version when
+   non-capture mouse input through the Host Application is required.
 
 The legacy Host normally selects a compatible frame path automatically. Its
 persistent configuration file is:
 
 ``C:\Program Files\Looking Glass (host)\looking-glass-host.ini``
 
-Use options from the same release as the Host binary. Do not copy a current
-Host configuration into B7 or combine a B7 Host with a current client.
-
 .. _host_capture:
 
 Capture interface
@@ -47,7 +44,6 @@ DXGI
 
 NvFBC
    An NVIDIA SDK path available only with supported hardware and licensing.
-   It is not required by the IDD or the normal legacy D12 path.
 
 The exact capture-interface options can change between releases. Consult the
 binary's help and the configuration comments supplied with that release.
@@ -57,7 +53,7 @@ binary's help and the configuration comments supplied with that release.
 Select an IVSHMEM device
 ------------------------
 
-The legacy Host selects the first IVSHMEM device by default. When the VM has
+The legacy host selects the first IVSHMEM device by default. When the VM has
 more than one, ``os:shmDevice`` selects by zero-based device order:
 
 .. code-block:: ini
@@ -66,14 +62,14 @@ more than one, ``os:shmDevice`` selects by zero-based device order:
    shmDevice=1
 
 Check the Host log after changing it; the selected device is marked with an
-asterisk. This option is for the legacy Host and is not an IDD helper setting.
+asterisk.
 
 .. _host_downsampling:
 
 Downsampling
 ------------
 
-The legacy Host can reduce a captured resolution before transport. Rules use
+The legacy host can reduce a captured resolution before transport. Rules use
 ``source:target`` syntax and may match resolutions greater than a threshold:
 
 .. code-block:: ini
@@ -85,5 +81,4 @@ The legacy Host can reduce a captured resolution before transport. Rules use
    downsample=>1920x1080:1920x1080
 
 This saves transport bandwidth but does not reduce the guest application's
-rendering work. IDD users should request the required virtual monitor
-resolution instead.
+rendering work.

doc/idd_configuration.rst

@@ -7,6 +7,8 @@ Right-click the **Looking Glass (IDD)** icon in the Windows notification area
 and select **Open configuration**. The icon and its tooltip also show whether
 the driver is using GPU acceleration or software processing.
 
+.. _idd_display_modes:
+
 Display modes
 -------------
 
@@ -22,15 +24,37 @@ for the Looking Glass monitor.
 * Enable **prefer** on the mode that Windows should prefer. Only one mode can
   be preferred.
 
-Refresh rates may contain up to three decimal places. For example, enter
+Refresh rates may contain up to three decimal places. For example, you can enter
 ``119.970`` rather than rounding it to 120 Hz. Accepted values range from
 23.900 Hz to 1000.000 Hz. Width may range from 640 to 16384 pixels and height
 from 480 to 16384 pixels.
 
-Edits to the mode list are not applied immediately. Select **Save & reload
-driver** when the list is ready. This saves the list, removes and recreates the
-virtual monitor, and can make the display blink briefly. **Revert** discards
-unsaved mode and default-refresh changes.
+Edits to the mode list are not applied immediately, you must select **Save &
+reload driver** when the list is ready. This saves the list, then removes and
+recreates the virtual monitor, and can make the display blink briefly.
+**Revert** discards unsaved mode and default-refresh changes.
+
+.. _idd_mode_culling:
+
+Modes that do not fit in shared memory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At startup, the IDD removes modes that cannot fit in the configured IVSHMEM
+region. If every suitable mode is filtered, the monitor cannot start. A
+dynamic resolution request that is too large is refused and the helper reports
+the minimum power-of-two IVSHMEM size needed.
+
+To allow for modes that do not currently fit, increase the IVSHMEM size in the
+VM configuration and restart the VM. The IDD reads the new capacity when it
+starts; another helper reload is not normally required. Allocating more shared
+memory than required does not improve performance; it only reserves additional
+host RAM.
+
+.. seealso::
+
+   :ref:`libvirt_determining_memory`
+
+.. _idd_refresh:
 
 Default refresh
 ---------------
@@ -39,14 +63,16 @@ Default refresh
 resolution. It also supplies the refresh rate when **Load default** rebuilds
 the standard mode list.
 
-Changing this value does not rewrite refresh rates already saved in the normal
+Changing this value does not update refresh rates already saved in the normal
 mode list. On reload, an existing dynamic mode keeps its resolution and adopts
 the new default refresh rate.
 
 The client option ``win:setGuestRes`` enables automatic dynamic resolution
 requests when the client window changes size. The default is enabled when the
-server in the guest supports it. Press the client's escape key together with
-``=`` to request the current window resolution manually.
+server in the guest supports it. Press :kbd:`ScrLk` + :kbd:`=` to request the
+current window resolution manually.
+
+.. _idd_preferences:
 
 Preferences
 -----------
@@ -60,8 +86,9 @@ Make LG the only monitor
 
 Disable no GPU warning
    Suppresses the notification shown when the IDD has fallen back to software
-   processing. It does not enable GPU acceleration or change the active
-   adapter.
+   processing. This is only intended to be used for virtual machines that do not
+   require 3D acceleration. It does not enable GPU acceleration or change the
+   active adapter.
 
 Force full direct frame copies
    Works around GPU drivers that corrupt partial D3D12 copies into the shared
@@ -78,7 +105,9 @@ Force indirect copy
    a CPU copy and significantly reduces throughput. It takes precedence over
    the direct-copy preference and requests a driver reload when changed.
 
-Unlike mode-list edits, preference checkboxes are saved when clicked.
+Unlike mode-list edits, preference checkboxes are automatically saved.
+
+.. _idd_software_processing:
 
 Software processing
 -------------------
@@ -87,16 +116,3 @@ If no suitable Windows render adapter is available, the IDD can use software
 processing. This provides a display but is slower, cannot provide predictable
 high-rate cadence and is limited to SDR. Check the IDD log to see which render
 adapter was selected and whether software processing is active.
-
-Modes that do not fit in shared memory
---------------------------------------
-
-At startup the IDD removes modes that cannot fit in the configured IVSHMEM
-region. If every suitable mode is filtered, the monitor cannot start. A
-dynamic resolution request that is too large is refused and the helper reports
-the minimum power-of-two IVSHMEM size needed.
-
-Increase the IVSHMEM size in the VM configuration and restart the VM. The IDD
-reads the new capacity when it starts; another helper reload is not normally
-required. Allocating more shared memory than required does not improve
-performance; it only reserves additional host RAM.

doc/idd_diagnostics.rst

@@ -7,9 +7,8 @@ The IDD helper in the Windows notification area is the first place to check
 when the virtual display is missing or slow. Its icon and tooltip report
 whether the driver is using GPU acceleration or software processing.
 
-Right-click the helper and open the log directory. The files are stored in:
-
-``C:\ProgramData\Looking Glass (IDD)``
+Right-click the helper and open the log directory. In case this is not
+available, manually navigate to ``C:\ProgramData\Looking Glass (IDD)``.
 
 Collect these files when reporting an IDD fault:
 
@@ -40,11 +39,11 @@ Filtered mode
 
 IddCx capabilities
    Shows whether the runtime HDR and wide-color-gamut interfaces are
-   available. Their absence on Windows 10 is expected and does not prevent SDR
-   use.
+   available. This will not be visible on Windows 10, and SDR will be used
+   instead.
 
 Frame schedule owner
-   Reports the fastest active client's requested rate, guest acquisition rate
+   Reports the fastest active client's requested rate, guest acquisition rate,
    and how many frames were published or skipped. Skipping excess guest frames
    is expected; it saves memory bandwidth while preserving the newest frame
    needed by the client.
@@ -52,20 +51,3 @@ Frame schedule owner
 Input owner
    Identifies the client currently allowed to send direct input. Only one
    client can own it at a time.
-
-Client information
-------------------
-
-Run the client from a terminal and retain its complete output. Include:
-
-* the client, IDD and OBS versions;
-* Linux distribution and kernel;
-* X11 or Wayland and the compositor name;
-* host and guest GPU models and drivers;
-* whether ``lgmp:allowDMA`` is enabled;
-* the guest resolution and refresh rate; and
-* exact steps that reproduce the fault.
-
-Do not copy only the final error line. Startup output records the selected
-transport, renderer, display server, audio backend and import method, which are
-often needed to explain it.

doc/index.rst

@@ -2,9 +2,8 @@ Looking Glass |release| documentation
 =====================================
 
 Looking Glass is an open-source, low-latency way to use a Windows virtual
-machine from Linux. The current setup uses a virtual display in the Windows
-guest, shared memory for frames, and a native Linux client for display and
-input.
+machine from Linux; it utilizes a virtual display in the Windows guest, shared
+memory for frames, and a native Linux client for display and input.
 
 .. toctree::
    :maxdepth: 2

doc/input.rst

@@ -7,28 +7,32 @@ 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.
+The client changes input provider automatically. If the displayed video falls
+back to SPICE, the client also uses SPICE input.
 
 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.
 
+.. _client_input_normal:
+
 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.
+Direct IDD input supports keyboard input, media keys, and up to 32 mouse
+buttons. SPICE fallback uses relative mouse input and supports fewer extra
+buttons.
+
+.. _client_capture_mode:
 
 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
+Press the escape key (:kbd:`ScrLk` by default) to capture the mouse. Capture
+mode confines the pointer and uses relative movement, which is appropriate for
 games and applications that lock the cursor. Press the escape key again to
 leave capture mode.
 
@@ -53,6 +57,8 @@ Common capture options are:
 ``input:hideCursor``
    Hide the host cursor while Looking Glass renders the guest cursor.
 
+.. _client_autocapture:
+
 Automatic keyboard capture
 --------------------------
 
@@ -74,6 +80,8 @@ mouse input.
 guest view is active. ``input:grabKeyboard`` controls whether full capture
 mode grabs the keyboard.
 
+.. _client_input_spice:
+
 SPICE fallback
 --------------
 
@@ -91,6 +99,8 @@ To disable all SPICE input while keeping SPICE audio or clipboard services:
 If direct input is also unavailable, the client will display video without
 being able to control the guest.
 
+.. _client_input_evdev:
+
 Evdev capture
 -------------
 

doc/install.rst

@@ -3,12 +3,16 @@
 Installation
 ############
 
-The Linux client must currently be built from source before it can be
-installed. Follow the pages below in order for a new setup:
+The Linux client must be built from source before it can be installed. Follow
+the instructions below for a new setup:
 
-Configure the VM and shared memory, install the IDD in Windows, then install
-the Linux client. The legacy Host page is an alternative for old workflows;
-do not install both Windows servers.
+1. Configure the VM and shared memory;
+2. Install the IDD in Windows; and
+3. Install the Linux client.
+
+.. tip::
+
+   The :doc:`legacy_host` page is an alternative for old workflows.
 
 .. toctree::
 

doc/install_client.rst

@@ -12,9 +12,9 @@ The Looking Glass Client receives frames from an implementation of the Looking
 Glass Server on Windows and displays them on Linux. It also handles input,
 audio, overlays and optional SPICE services.
 
-There are currently no Linux distribution packages for the client. First
-:ref:`build it from source <build_client_section>`, then run the following from
-the client build directory as root::
+There are no Linux distribution packages for the client during the development
+phase. First :ref:`build it from source <build_client_section>`, then run the
+following from the client build directory as root::
 
    make install
 
@@ -24,5 +24,5 @@ prefix before installing::
    cmake -DCMAKE_INSTALL_PREFIX="$HOME/.local" ..
    make install
 
-Ensure ``$HOME/.local/bin`` is in your ``PATH`` when using the user-local
-installation.
+Ensure ``$HOME/.local/bin`` is in your ``PATH`` when installing to a user-local
+prefix.

doc/install_host.rst

@@ -11,8 +11,8 @@ Legacy Host Application installation
    <install_idd>`.
 
    B7 is the last recommended release when non-capture mouse input through the
-   Host Application is required. Use the matching B7 client and documentation
-   for that workflow. Do not combine a B7 Host with current components.
+   Host Application is required. Mismatched versions will cause issues, please
+   make sure all components are using version B7.
 
 The legacy Looking Glass Host Application captures frames from the guest using a
 capture API, and sends them to the
@@ -21,7 +21,7 @@ Virtual Machine—through a low-latency transfer protocol over shared memory.
 
 You can get the host program in two ways:
 
--  Download a matching legacy binary from https://looking-glass.io/downloads
+-  Download from https://looking-glass.io/downloads
 
 -  Download the source code as described in :ref:`building`, then
    :ref:`build the host <host_building>`.
@@ -57,10 +57,8 @@ To begin, you must first run the Windows VM with the changes noted in the
 Installing the IVSHMEM driver
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Since B6 the host installer available on the official Looking Glass website
-comes with the IVSHMEM driver and will install this for you. If you are running
-an older version of Looking Glass please refer to the documentation for your
-version.
+The host installer available on the official Looking Glass website comes with
+the IVSHMEM driver and will install this for you.
 
 .. _host_install_service:
 
@@ -89,12 +87,3 @@ Command line users can run ``looking-glass-host-setup.exe /S`` to execute a
 silent install with default options selected. Further configuration from the
 command line can be done with flags. You can list all available flags by
 running ``looking-glass-host-setup.exe /?``.
-
-Legacy configuration
-~~~~~~~~~~~~~~~~~~~~
-
-.. toctree::
-   :maxdepth: 1
-
-   host_usage
-   build_host

doc/install_idd.rst

@@ -3,28 +3,29 @@
 Looking Glass IDD
 #################
 
-.. _install_idd:
-
 The Looking Glass IDD is the recommended Looking Glass server implementation for
 Windows guests. Download the ``looking-glass-idd-setup.exe`` installer that
-matches the client release, run it as an administrator inside the Windows guest
+matches the client release, run it as an administrator inside the Windows guest,
 and follow the installer.
 
 The installer includes the display driver, direct input driver and IDD helper.
-It can also install the IVSHMEM driver. If the legacy Host service is present,
-allow the installer to disable it so that only one Looking Glass server is
-active.
+It can also install the IVSHMEM driver. If the legacy host service is already
+installed, allow the installer to disable it so that only one Looking Glass
+server is active.
 
 The display may briefly disappear while Windows installs or reloads the
 driver. Restart Windows if the installer requests it.
 
+.. _install_idd:
+
 Install
 -------
 
-1. Download the IDD installer from the same release as the client source.
-2. Run ``looking-glass-idd-setup.exe`` as an administrator in Windows.
+1. `Download the IDD installer <https://looking-glass.io/downloads>`__ from the
+   same release as the client.
+2. Run ``looking-glass-idd-setup.exe`` as an administrator in the guest.
 3. Select **IVSHMEM Driver** if a suitable IVSHMEM driver is not already
-   installed in the guest.
+   installed.
 4. Leave **Indirect Display Driver (IDD)** selected.
 5. If offered, leave **Disable old host app** selected. Running two servers
    against the same shared-memory device is not supported.
@@ -34,38 +35,48 @@ After installation, Windows should show a display named Looking Glass and the
 IDD helper should appear in the notification area. The helper icon reports
 whether the IDD is using GPU acceleration or software processing.
 
-The IDD installer also installs its direct input driver. There is no separate
+The IDD installer also installs its direct input driver, there is no separate
 input package to install.
 
+.. _upgrade_idd:
+
 Upgrade
 -------
 
-Close active clients and OBS sources, then run the new matching IDD installer
-over the existing installation. Upgrade the Linux client and OBS plugin to the
-same release before using them again.
+1. Download the desired version of the IDD installer and run it over the
+   existing installation.
+2. Close all active clients and OBS sources.
+3. Upgrade the Looking Glass client and OBS plugin to the same version as the
+   IDD.
 
 Windows may briefly remove and recreate the virtual display. Restart Windows
 when the installer reports that a restart is required.
 
+.. _uninstall_idd:
+
 Uninstall
 ---------
 
-Remove **Looking Glass (IDD)** from Windows **Installed apps** or **Programs
-and Features**. This removes both the display and input drivers and deletes
+ - Remove **Looking Glass (IDD)** from Windows' **Installed apps** or **Programs
+   and Features**.
+
+This removes both the display and input drivers and deletes
 custom IDD modes and preferences. The optional IVSHMEM files are removed from
 the Looking Glass installation directory, but an IVSHMEM driver package that
 was already installed in Windows is not uninstalled.
 
-If you are returning to the legacy Host Application, re-enable or reinstall
-its service only after the IDD has been removed.
+If you are installing the legacy host application, re-enable or reinstall the
+host service only after the IDD has been removed.
+
+.. _silent_install_idd:
 
 Silent installation
 -------------------
 
-The installer accepts these options for managed installations:
+The installer accepts these (case-sensitive) options for managed installations:
 
 ``/S``
-   Install silently. The uppercase spelling is required.
+   Install silently.
 
 ``/ivshmem``
    Install the bundled IVSHMEM driver when it is present in the installer.
@@ -74,6 +85,8 @@ The installer accepts these options for managed installations:
    Change the installation directory. This must be the final option and must
    not be quoted.
 
+.. _configure_idd:
+
 Configuration and diagnostics
 -----------------------------
 

doc/install_libvirt.rst

@@ -4,38 +4,56 @@ libvirt/QEMU Installation
 #########################
 
 This article assumes you already have a working `libvirt` Windows virtual
-machine. If you use `virt-manager`, this guide also applies because
-`virt-manager` uses `libvirt` as its back end. A passed-through or virtual GPU
-is strongly recommended, but the IDD can start in software mode without one.
+machine. It also applies to users of `virt-manager`, because `virt-manager` uses
+`libvirt` as its back end. A passed-through or virtual GPU is strongly
+recommended, but the IDD can start in software mode without one.
 
 .. _libvirt_determining_memory:
 
 Determining memory
 ^^^^^^^^^^^^^^^^^^
 
-Calculate the IVSHMEM requirement as:
+The IVSHMEM size is calculated as:
 
 .. math::
 
-  \text{REQUIRED BYTES} =
-  \left(\left\lceil\frac{\text{WIDTH} \times 4}{256}\right\rceil
-  \times 256\right) \times \text{HEIGHT} \times 3
-  + (4 \times 1024 \times 1024)
+  B &= 3h\left(256\left\lceil\frac{4w}{256}\right\rceil\right)
+     + (4 \cdot {1024}^2) \\
+  M &= 2^{\left\lceil\log_2 B\right\rceil - 20}
 
-Convert the result to MiB and round it up to the next power of two. The common
-values below have already been rounded.
+where
+
+* :math:`w` is the desired resolution width;
+* :math:`h` is the desired resolution height;
+* :math:`B` is the required amount of bytes; and
+* :math:`M` is the required amount of bytes in MiB, rounded up to a power of
+  two.
+
+You may use the following Python script as a substitute:
+
+.. code-block:: python
+
+  import math
+
+  w = int(input("Width: "))
+  h = int(input("Height: "))
+
+  B = 3 * h * (256 * math.ceil(4 * w / 256)) + 4 * 1024**2
+  M = 2 ** (math.ceil(math.log2(B)) - 20)
+
+  print(f"IVSHMEM size should be set to {M} MiB")
 
 If a configured mode does not fit, the IDD omits it from the Windows mode list.
 If a client-requested dynamic resolution does not fit, the helper refuses it
-and reports the minimum power-of-two size to configure. The current IDD does
-not publish a truncated frame.
+and reports the minimum power-of-two size to configure. The IDD will not serve a
+truncated frame.
 
 .. note::
-   Increasing this value beyond what you need does not improve performance. It
+   Increasing this value beyond what you need does not improve performance, it
    only reserves more host RAM for the VM.
 
-.. list-table:: Common IDD values
-   :widths: 60 40
+.. list-table:: Common IDD values (already rounded)
+   :widths: 50 50
    :header-rows: 1
 
    * - Maximum resolution
@@ -59,9 +77,11 @@ not publish a truncated frame.
 
 .. _libvirt_determining_memory_hdr:
 
-HDR uses the same 32-bit IDD transport allocation as SDR, so it does not double
-the IVSHMEM requirement. Native Linux HDR presentation has separate compositor
-and display requirements; see :ref:`client_hdr`.
+.. admonition:: HDR Requirements
+
+   HDR uses the same 32-bit IDD transport allocation as SDR, so it does not
+   double the IVSHMEM requirement. Native Linux HDR presentation has separate
+   compositor and display requirements; see :ref:`client_hdr`.
 
 .. _libvirt_ivshmem:
 
@@ -86,88 +106,46 @@ Looking Glass to use your GPUs DMA engine to transfer the frame data.
 
 .. _libvirt_spice_server:
 
-Keyboard/mouse/display/audio
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+SPICE server
+^^^^^^^^^^^^
 
-The IDD provides the primary video, keyboard and mouse paths directly over
-LGMP. SPICE is optional, but is recommended for display fallback, clipboard
-and audio services.
+The Looking Glass client presents a USB audio device to the guest through SPICE
+USB redirection, and SPICE is therefore required. See :ref:`client_usb_audio`
+for more information.
 
-.. note::
-  The current client owns its SPICE connection and service settings. The
-  canonical options are ``spice:enable``, ``spice:input``,
-  ``spice:clipboard``, ``spice:audio`` and ``spice:usbAudio``.
+The Looking Glass client also supports SPICE for video, audio, and input if
+there is a problem with the Looking Glass IDD. However, this is no faster than
+other SPICE clients like virt-viewer, and should only be used as a fallback when
+troubleshooting, not daily use.
 
-Keep a ``<graphics type='spice'>`` device if you want these services. For a
-usable display fallback, set the VM's ``<video>`` model to ``vga``.
-
-The direct IDD input path supports absolute desktop positioning, relative
-capture-mode input, keyboards, media keys and extended mouse buttons. SPICE
-fallback uses the VM's default PS/2 keyboard and mouse. Looking Glass does not
-require additional virtio keyboard, mouse or tablet devices for either path.
-
-For classic SPICE audio, add a standard Intel HDA audio device:
+To enable SPICE support, add a SPICE graphics server to your virtual machine:
 
 .. code:: xml
 
-  <sound model='ich9'>
-    <audio id='1'/>
-  </sound>
-  <audio id='1' type='spice'/>
+   <devices>
+     <graphics type='spice'/>
+   </devices>
 
-The recommended emulated USB audio path does not need this HDA device. It
-requires a SPICE USB channel and is covered in :ref:`client_usb_audio`. For
-clipboard synchronization, continue with
-:ref:`libvirt_clipboard_synchronization`.
-
-.. _libvirt_clipboard_synchronization:
-
-Clipboard synchronization
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Looking Glass can synchronize the clipboard between the host and guest using
-the SPICE guest agent.
-
-1. Install the SPICE guest tools from
-https://www.spice-space.org/download.html#windows-binaries.
-
-2. Configure your VM to enable the SPICE guest agent:
-
--  QEMU
-
-.. code:: bash
-
-   -device virtio-serial-pci \
-   -chardev spicevmc,id=vdagent,name=vdagent \
-   -device virtserialport,chardev=vdagent,name=com.redhat.spice.0
-
--  libvirt
+For a fallback display, set up your video device to use VGA:
 
 .. code:: xml
 
-     <channel type="spicevmc">
-       <target type="virtio" name="com.redhat.spice.0"/>
-       <address type="virtio-serial" controller="0" bus="0" port="1"/>
-     </channel>
-     <!-- No need to add a VirtIO Serial device, it will be added automatically -->
+   <devices>
+     <video>
+       <model type="vga"/>
+     </video>
+   </devices>
 
-.. _libvirt_apparmor:
+For fallback audio support, add a standard Intel HDA audio device:
 
-AppArmor
-^^^^^^^^
+.. code:: xml
 
-For libvirt versions before **5.10.0**, if you are using AppArmor, you
-need to add permissions for QEMU to access the shared memory file. This
-can be done by adding the following to
-``/etc/apparmor.d/local/abstractions/libvirt-qemu``::
-
-   /dev/shm/looking-glass rw,
-
-then, restart AppArmor.
-
-.. code:: bash
-
-   sudo systemctl restart apparmor
+   <devices>
+     <sound model='ich9'>
+        <audio id='1'/>
+     </sound>
+     <audio id='1' type='spice'/>
+   </devices>
 
 .. _libvirt_memballoon_tweak:
 
@@ -185,7 +163,9 @@ Find the ``<memballoon>`` tag and set its type to ``none``:
 
 .. code:: xml
 
-   <memballoon model="none"/>
+   <devices>
+     <memballoon model="none"/>
+   </devices>
 
 .. _libvirt_additional_tuning:
 
@@ -193,10 +173,10 @@ Additional tuning
 ^^^^^^^^^^^^^^^^^
 
 Looking Glass is latency sensitive and as such it may suffer microstutters if
-you have not properly tuned your virtual machine. The physical display output
-of your GPU will usually not show such issues due to the nature of the hardware
-but be sure that if you are experiencing issues the following tuning is
-required to obtain optimal performance.
+you have not properly tuned your virtual machine. The physical display output of
+your GPU will usually not show such issues due to the nature of the hardware.
+However, if you are experiencing issues, the following tuning is required to
+obtain optimal performance.
 
 1. Do not assign all your CPU cores to your guest VM, you must at minimum
    reserve two CPU cores (4 threads) for your host system to use. For example,
@@ -208,16 +188,13 @@ required to obtain optimal performance.
 3. If you are on a NUMA architecture (dual CPU, or early Threadripper) be sure
    that you pin the vCPU threads to the physical CPU/die attached to your GPU.
 
-4. Just because your GPU is in a slot that is physically x16 in size, does not
-   mean your GPU is running at x16, this is dependent on how your motherboard
-   is physically wired and the physical slot may be limited to x4 or x8.
+4. Get familiar with your specific motherboard's PCIe slots. Larger physical
+   slots (for example x16) may only operate at a slower speed (like x8),
+   depending on your motherboard's layout.
 
 5. Be sure to set your CPU model type to `host-passthrough` so that your guest
    operating system is aware of the acceleration features of your CPU and can
    make full use of them.
 
-6. AMD users be sure that you have the CPU feature flag `topoext` enabled or
-   your guest operating system will not be aware of which CPU cores are
-   hyper-thread pairs.
-
-How to perform these changes is left as an exercise to the reader.
+6. For users of AMD CPUs, enable the `topoext` feature flag to inform the guest
+   operating system of your CPU's hyper-threading core pairs.

doc/ivshmem_kvmfr.rst

@@ -1,4 +1,3 @@
-:orphan:
 .. _ivshmem_kvmfr:
 
 IVSHMEM with the KVMFR module (Recommended)
@@ -28,7 +27,7 @@ Then switch to the ``module/`` directory
 .. _ivshmem_kvmfr_dkms:
 
 Installing
-~~~~~~~~~~
+----------
 
 To install the module into DKMS, run
 
@@ -39,11 +38,11 @@ To install the module into DKMS, run
 .. _ivshmem_kvmfr_loading:
 
 Loading
-~~~~~~~
+-------
 
-Using the value you should have already calculated as per
-:ref:`Determining Memory <libvirt_determining_memory>`, simply use
-``modprobe`` with the parameter ``static_size_mb``, for example:
+Using the IVSHMEM size from :ref:`Determining Memory
+<libvirt_determining_memory>`, simply use ``modprobe`` with the parameter
+``static_size_mb``, for example:
 
 .. code:: bash
 
@@ -68,8 +67,8 @@ required.
 systemd-modules-load
 ~~~~~~~~~~~~~~~~~~~~
 
-For convenience, you may load the KVMFR module when starting your computer.
-We can use the ``systemd-modules-load.service(8)`` service for this task.
+You can use the ``systemd-modules-load.service(8)`` service to load KVMFR when
+you start your computer.
 
 Create the file ``/etc/modules-load.d/kvmfr.conf`` with the following
 contents::
@@ -82,7 +81,7 @@ This will now run the next time you start your machine.
 .. _ivshmem_kvmfr_verification:
 
 Verification
-~~~~~~~~~~~~
+------------
 
 If everything has been done correctly you should see the following output in
 dmesg:
@@ -101,17 +100,21 @@ You should now also have the character device ``/dev/kvmfr0``
 .. warning::
 
    If you start the VM prior to loading the module, QEMU will create the file
-   ``/dev/kvmfr0`` as a regular file. You can confirm if this has happened by
-   running ``ls -l /dev/kvmfr0`` and checking if the file size is greater than
-   zero, or the permissions do not start with ``c``. If this has occurred, you
-   must stop the VM before deleting the regular file. Load the KVMFR module,
-   confirm that it recreated ``/dev/kvmfr0`` as a character device whose
-   permissions start with ``c``, then start the VM again.
+   ``/dev/kvmfr0`` as a regular file rather than as a character device. You can
+   see if this has happened by running ``ls -l /dev/kvmfr0`` and checking if the
+   file size is greater than zero, or the permissions do not start with ``c``.
+   If this has occurred:
+
+   1. stop the VM
+   2. delete ``/dev/kvmfr0``
+   3. load the KVMFR module
+   4. confirm that ``/dev/kvmfr0`` is character device
+   5. start the VM again
 
 .. _ivhsmem_kvmfr_permissions:
 
 Permissions
-~~~~~~~~~~~
+-----------
 
 The module will create the ``/dev/kvmfr0`` node, which represents the KVMFR
 interface. To use the interface, you need permission to access it by either
@@ -137,7 +140,7 @@ with the following contents::
 .. _ivshmem_kvmfr_libvirt:
 
 libvirt
-~~~~~~~
+-------
 
 Using the module in libvirt requires adding a ``<qemu:commandline>`` block to
 your libvirt XML configuration. That block, in turn, requires modifying the
@@ -148,18 +151,13 @@ the top of your XML config to:
 
    <domain type='kvm' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>
 
-then add one of the ``<qemu:commandline>`` blocks below based on your
-QEMU/libvirt versions.
-
 .. note::
 
    Make sure to add both the block and the domain namespace change in a
    single editing session prior to saving it. Failure to do so will cause
    libvirt to reject the changes.
 
-Starting with QEMU 6.2 and libvirt 7.9, JSON style QEMU configuration is the
-default syntax. Users running QEMU 6.2 or later **and** libvirt 7.9 or later,
-should use this XML block to configure their VM for kvmfr:
+then the ``<qemu:commandline>`` block below to your domain XML:
 
 .. code:: xml
 
@@ -179,24 +177,6 @@ should use this XML block to configure their VM for kvmfr:
 
      ``size_in_MB x 1024 x 1024 = size_in_bytes``
 
-If you are running QEMU older than 6.2 or libvirt older than 7.9, please use
-legacy syntax for IVSHMEM setup:
-
-.. code:: xml
-
-   <qemu:commandline>
-     <qemu:arg value="-device"/>
-     <qemu:arg value="ivshmem-plain,id=shmem0,memdev=looking-glass"/>
-     <qemu:arg value="-object"/>
-     <qemu:arg value="memory-backend-file,id=looking-glass,mem-path=/dev/kvmfr0,size=64M,share=yes"/>
-   </qemu:commandline>
-
-.. note::
-
-   Using the legacy syntax on QEMU 6.2/libvirt 7.9 may cause QEMU to
-   abort with the following error message:
-   "``error: internal error: ... PCI: slot 1 function 0 not available for pcie-root-port, in use by ivshmem-plain``"
-
 Running libvirt this way violates AppArmor and cgroups policies, which will
 block the VM from running. These policies must be amended to allow the VM
 to start.
@@ -207,7 +187,7 @@ to start.
    and configured by default by most distributions when you install libvirt.
 
 AppArmor
-^^^^^^^^
+~~~~~~~~
 
 Create ``/etc/apparmor.d/local/abstractions/libvirt-qemu`` if it doesn't exist
 and add the following:
@@ -218,7 +198,7 @@ and add the following:
    /dev/kvmfr0 rw,
 
 cgroups
-^^^^^^^
+~~~~~~~
 
 Edit the file ``/etc/libvirt/qemu.conf`` and uncomment the
 ``cgroup_device_acl`` block, adding ``/dev/kvmfr0`` to the list. Restart
@@ -231,7 +211,7 @@ Edit the file ``/etc/libvirt/qemu.conf`` and uncomment the
 .. _ivshmem_kvmfr_qemu:
 
 QEMU
-~~~~
+----
 
 If you are using QEMU directly without libvirt, add the following arguments to your
 ``qemu`` command line::

doc/ivshmem_shm.rst

@@ -14,10 +14,12 @@ your virtual machine.
 
 .. code:: xml
 
-   <shmem name='looking-glass'>
-     <model type='ivshmem-plain'/>
-     <size unit='M'>64</size>
-   </shmem>
+   <devices>
+     <shmem name='looking-glass'>
+       <model type='ivshmem-plain'/>
+       <size unit='M'>64</size>
+     </shmem>
+   </devices>
 
 .. note::
   If you are using QEMU directly without libvirt the following arguments are

doc/legacy_host.rst

@@ -6,17 +6,19 @@ Legacy Host Application
 .. warning::
 
    The Host Application is a legacy server application. New installations should
-   use the prebuilt :doc:`Looking Glass IDD <install_idd>`. These build
-   instructions are retained for the complete matching B7 stack described in
+   use the :doc:`Looking Glass IDD <install_idd>`. The IDD and legacy host
+   should not be installed together on the same virtual machine. These build
+   instructions are retained for the B7 stack described in
    :ref:`legacy_host_policy`.
 
 .. note::
 
-   `Host` in this context refers to the `Looking Glass (LG) host server application`,
-   to which the LG client connects to, it thus does not refer to the `host OS`!
+   `Host` in this context refers to the `Looking Glass (LG) host server
+   application`, which the LG client connects to, it thus does not refer to the
+   `host OS`.
 
    A common setup is to have a `host OS` running a `guest VM`. In such a setup
-   the `client application` runs on the `host OS`; and the `host application`
+   the `client application` runs on the `host OS`, and the `host application`
    on the `guest VM`.
 
    The term `Host application` was chosen over `Guest application`, because LG
@@ -33,8 +35,8 @@ It is missing many of the features available in the Looking Glass IDD, such as:
 * Usage in virtual machines without GPU acceleration.
 
 B7 is the last recommended version of the legacy host application for users who
-require its non-capture mouse input workflow. Use the complete matching B7 stack
-for that workflow rather than mixing B7 and current components.
+require its non-capture mouse input workflow. Mismatched versions will cause
+issues, please make sure all components are using version B7.
 
 The documentation is included here for completeness.
 

doc/obs.rst

@@ -7,7 +7,7 @@ OBS plugin
 The Looking Glass OBS plugin reads video from LGMP directly instead of
 capturing the client window. The client can stay hidden or show overlays
 without adding them to the OBS source. This source does not provide audio or
-input; add the required audio source separately in OBS.
+input, so add any required audio source separately in OBS.
 
 Use an OBS plugin from the same Looking Glass release as the IDD and client.
 The shared-memory protocol is versioned and mismatched components will not
@@ -18,7 +18,7 @@ connect.
 Build and install
 -----------------
 
-On Debian-based systems, install the OBS headers and the small set of build
+Install the OBS headers and the small set of build
 dependencies used by the plugin:
 
 .. code:: bash
@@ -26,7 +26,7 @@ dependencies used by the plugin:
    apt-get install cmake gcc libobs-dev libdw-dev libunwind-dev make pkg-config
 
 Use ``-DENABLE_BACKTRACE=no`` when configuring if ``libdw-dev`` and
-``libunwind-dev`` are intentionally omitted.
+``libunwind-dev`` are left out.
 
 From the Looking Glass source directory, build the plugin for the current
 user:
@@ -42,6 +42,8 @@ user:
 For a system-wide installation, omit ``-DUSER_INSTALL=1`` and run
 ``sudo make install``.
 
+.. _obs_add_source:
+
 Add the source
 --------------
 
@@ -49,7 +51,8 @@ Add the source
 2. In **Sources**, select **Add** and then **Looking Glass Client**.
 3. Set **SHM File** to the same KVMFR device or shared-memory file used by the
    VM.
-4. Enable **Hide mouse cursor** if OBS should omit the guest pointer.
+4. Enable **Hide mouse cursor** if OBS should hide the guest pointer from the
+   video.
 5. Leave **Use DMABUF import** enabled with KVMFR unless the OBS log reports
    that the host graphics driver cannot import it.
 
@@ -61,26 +64,32 @@ udev rule as the Looking Glass client; see :ref:`ivhsmem_kvmfr_permissions`.
 
    Adding the Looking Glass source
 
+.. _obs_dmabuf:
+
 DMA-BUF and CPU copy
 --------------------
 
-DMA-BUF import is available with OBS 27 or newer and is enabled by default.
-It imports KVMFR into the GPU and makes a full-frame GPU snapshot into
-OBS-owned storage before releasing the shared frame. It avoids the CPU upload,
-but it is not a zero-copy path to the final OBS texture. If import or the
-snapshot fails, the plugin falls back to a CPU copy and records the failure in
-the OBS log. A plain POSIX shared-memory file always uses the CPU path.
+DMA-BUF import is available and is enabled by default. It imports KVMFR into the
+GPU and makes a full-frame GPU snapshot into OBS-owned storage before releasing
+the shared frame. It avoids the CPU upload, but is not a zero-copy path to
+the final OBS texture. If import or the snapshot fails, the plugin falls back to
+a CPU copy and records the failure in the OBS log. A plain POSIX shared-memory
+file always uses the CPU path.
 
 Disabling DMA-BUF is useful for diagnosis, but it increases CPU and memory
 bandwidth use at high resolutions.
 
+.. _obs_hdr:
+
 HDR
 ---
 
-HDR-aware OBS color-space support requires OBS 28 or newer. The plugin reports
-the source color space from the IDD frame, but OBS must also be configured with
-an HDR canvas and a suitable recording or streaming output. An SDR OBS project
-will not become HDR merely because the guest frame is HDR.
+HDR-aware OBS color-space support is also available. The plugin reports the
+source color space from the IDD frame, but OBS must also be configured with an
+HDR canvas and a suitable recording or streaming output. An SDR OBS project will
+not become HDR merely because the guest frame is HDR.
+
+.. _obs_framerate_many_clients:
 
 Frame rate and multiple clients
 -------------------------------
@@ -96,6 +105,8 @@ IDD log lines that report acquired, skipped and published frames are expected:
 frames newer than the previous publication may be acquired and superseded
 without copying all of them through IVSHMEM.
 
+.. _obs_troubleshooting:
+
 Troubleshooting
 ---------------
 
@@ -104,17 +115,16 @@ No source image
    OBS log reports both expected protocol versions when they do not match.
 
 High CPU use
-   Confirm that DMA-BUF stayed enabled and that import succeeded. Also check
-   whether OBS and the client are both performing expensive scaling.
+   Confirm that DMA-BUF remains enabled and that import succeeded. Also check
+   whether OBS and the client are both performing expensive image scaling.
 
 Jitter when another client starts
-   Confirm OBS is using a current matching plugin. Current cadence support
-   allows consumers with different refresh rates without forcing OBS to
-   display every frame requested by the fastest client.
+   Confirm the plugin and the IDD are using the same version. LGMP allows
+   consumers to have different refresh rates without forcing OBS to display
+   every frame requested by the fastest client.
 
 HDR looks washed out
    Check the OBS canvas color space, output format and the guest HDR state. Do
    not apply the client's HDR-to-SDR settings to the independent OBS source.
 
-OBS is available from https://obsproject.com/ and is packaged by most Linux
-distributions as ``obs-studio`` or ``obs``.
+OBS is available from https://obsproject.com/ and is packaged as ``obs-studio``.

doc/options.rst

@@ -127,7 +127,7 @@ Common options
      - Purpose
    * - ``input:escapeKey``
      - ``KEY_SCROLLLOCK``
-     - Set the capture/menu key; use ``help`` to list accepted names
+     - Set the capture/menu key; set to ``help`` to list accepted names
    * - ``input:autoCapture``
      - ``no``
      - Grab the keyboard inside the guest view and release it before exit
@@ -179,6 +179,5 @@ Advanced options
 
 Polling intervals, renderer damage handling, display-server protocol choices
 and audio-device selectors are intentionally omitted here. They are useful for
-diagnosis but can make latency or reliability worse when changed without a
-specific reason. Consult ``--help`` and record the original value before
-experimenting.
+diagnosis, but can make latency or reliability worse. Consult ``--help`` and
+record the original value before experimenting.

doc/overview.rst

@@ -3,13 +3,35 @@
 Overview
 ########
 
-Looking Glass displays a Windows virtual machine in a low-latency Linux
-window. It transfers completed frames through shared memory instead of sending
-compressed video over a network. The current IDD provides video and direct
-input through LGMP, while SPICE normally provides audio, clipboard and fallback
-services.
+Looking Glass displays a Windows virtual machine in a low-latency Linux window.
+It transfers completed frames through shared memory instead of sending
+compressed video over a network. The IDD provides video, direct input, and
+clipboard through LGMP, while SPICE provides audio and fallback services.
 
-The names used throughout this guide are:
+.. _documentation:
+
+Documentation
+-------------
+
+.. _docs_distro:
+
+Linux distribution
+~~~~~~~~~~~~~~~~~~
+
+The documentation is targeted at Debian users on the stable release channel
+(currently |debian_stable|). Newer unstable release channels and
+Debian-derivative distributions should also be well served, but some specifics
+may be different. Looking Glass is supported on any distribution that provides
+the :ref:`required dependencies <client_dependencies>` and meets the
+:ref:`minimum requirements <requirements>`, but specific package names within
+the documentation may not apply.
+
+.. _docs_terms:
+
+Terms
+~~~~~
+
+The terms used throughout the documentation are:
 
 Linux host
    The physical machine running KVM/QEMU and the Looking Glass Client.
@@ -18,9 +40,8 @@ Windows guest
    The Windows virtual machine shown by Looking Glass.
 
 Looking Glass Client
-   The Linux application that displays the guest and sends user input. There
-   are currently no distribution packages for it, so it must be built from
-   source before installation.
+   The Linux application that displays video from the guest, relays audio, and
+   sends user input.
 
 Looking Glass Server
    The Windows guest application that generates the video feed for the Looking
@@ -30,25 +51,28 @@ Looking Glass Server
 Looking Glass IDD
    The recommended Windows Indirect Display Driver. It creates a virtual
    monitor, sends its frames to the client and provides direct keyboard and
-   mouse input. The installer also includes the IDD helper and input driver.
+   mouse input, as well as clipboard synchronization.
 
 Legacy Host Application
    The older Windows capture application. It captures an existing display
    rather than creating a virtual one. It is documented for existing B7
-   workflows, but is no longer recommended for current installations.
+   workflows, but is no longer recommended for current installations, and does
+   not provide services like clipboard synchronization, which uses SPICE.
 
 KVMFR and IVSHMEM
    The shared-memory path between the Windows guest and Linux host. KVMFR is
-   the recommended Linux kernel module because it permits direct GPU imports
-   where supported.
+   the recommended Linux kernel module, as it permits direct GPU imports where
+   supported.
 
 LGMP
    The protocol used by Looking Glass components over shared memory.
 
 SPICE
-   An optional fallback transport for video, input, audio and clipboard
-   services. With the IDD active, Looking Glass normally uses its direct input
-   path and uses SPICE only for services that are enabled and available.
+   Remote communications protocol for virtual machines. Used by Looking Glass
+   for its emulated USB audio device. Also serves as an optional fallback
+   transport for video, input, audio, and clipboard services.
+
+.. _recommended_setup:
 
 Recommended setup
 -----------------
@@ -57,27 +81,27 @@ For a new installation, use:
 
 * the current Looking Glass Client on the Linux host;
 * KVMFR shared memory attached to the Windows guest;
-* the matching Looking Glass IDD in the Windows guest; and
-* SPICE only for the fallback or convenience services you need.
+* the current Looking Glass IDD in the Windows guest; and
+* SPICE server configured in QEMU or a wrapper, e.g. libvirt.
 
-Use matching Looking Glass releases for the current client, IDD, and OBS plugin.
-The shared-memory protocol changes between releases and incompatible components
-will not connect. Users of the legacy host application must use the complete
-matching B7 stack described below.
+Make sure to use the same version of Looking Glass for the client, IDD, and OBS
+plugin. The shared-memory protocol changes between releases and incompatible
+components are unable to connect. Users of the Legacy Host Application must use
+the complete B7 stack described below.
 
 .. _legacy_host_policy:
 
 Legacy Host Application
 -----------------------
 
-The Host Application is the legacy implementation of the Looking Glass server.
-The IDD is recommended because it does not require a physical monitor or dummy
-plug and supports current display, input and scheduling features.
+The Legacy Host Application is the legacy implementation of the Looking Glass
+server. The IDD is recommended, because it does not require a physical monitor
+or dummy plug, and supports current display, input, and scheduling features.
 
 If your workflow specifically requires non-capture mouse input with the Host
-Application, B7 is the last recommended release. Use the matching B7 client,
-Host Application and B7 documentation together; do not mix B7 components with
-current releases.
+Application, B7 is the last recommended release. Use the B7 client, Host
+Application and B7 documentation together; do not mix B7 components with current
+releases.
 
 Download the complete B7 release from https://looking-glass.io/downloads and see
 the :ref:`legacy_host` section.

doc/performance.rst

@@ -3,8 +3,11 @@
 Measure performance and latency
 ###############################
 
-Press :kbd:`ScrLk` + :kbd:`D` for the compact FPS and UPS display. Press
-:kbd:`ScrLk` + :kbd:`T` for the timing graphs.
+Press :kbd:`ScrLk` + :kbd:`D` to show the FPS and UPS display.
+
+Press :kbd:`ScrLk` + :kbd:`T` for the timing graphs.
+
+.. _client_performance_fps:
 
 FPS and UPS
 -----------
@@ -15,13 +18,15 @@ FPS
 
 UPS
    How often this client consumed a new guest frame. It can be lower than the
-   guest render rate because cadence deliberately skips frames that were
-   superseded before the client's next deadline.
+   guest render rate, as frames will be skipped if they are not displayed before
+   a new frame is received.
 
-A higher number is not automatically lower latency. Use the stage graph to
+A higher number is not automatically lower latency. Use the **stage** graph to
 find where time is spent and confirm that the displayed rate meets the output
 you are actually using.
 
+.. _client_latency_graph:
+
 Frame latency graphs
 --------------------
 
@@ -101,6 +106,8 @@ for each band are calculated independently, so the top of a minimum or maximum
 stack can combine stages from different frames. Use those panels to locate
 stage spikes, not as the measured total of one specific frame.
 
+.. _client_clock_sync:
+
 Cadence and Hold
 ----------------
 
@@ -122,6 +129,8 @@ Investigate when Hold repeatedly exceeds roughly one guest frame period, or
 when jumps occur with large Post, Copy or Ready spikes. Those patterns can
 indicate server work or scheduling delays rather than normal phase drift.
 
+.. _client_frame_graph:
+
 Frame and photon summaries
 --------------------------
 

doc/quickstart.rst

@@ -6,12 +6,12 @@ Quick start
 This is the shortest path to a current Looking Glass installation. It assumes
 that KVM/QEMU and the Windows guest are already working.
 
-1. :doc:`Check the requirements <requirements>`.
-2. :ref:`Download and build the Linux client <build_client_section>`. Current
+1. :doc:`Check the requirements </requirements>`.
+2. :doc:`Download and build the Linux client </build>`. Current
    releases are not provided as Linux distribution packages.
 3. :doc:`Configure KVMFR and IVSHMEM <install_libvirt>` for the largest guest
-   resolution you intend to use.
-4. :doc:`Install the matching Looking Glass IDD <install_idd>` inside the
+   resolution and framerate you intend to use.
+4. :doc:`Install the Looking Glass IDD <install_idd>` inside the
    Windows guest. Install the bundled IVSHMEM driver when required.
 5. :doc:`Install the client <install_client>` from its build directory.
 6. Start the Windows guest, then run:
@@ -25,8 +25,8 @@ otherwise uses ``/dev/shm/looking-glass``. If your path differs, select it with
 ``-f`` or ``lgmp:shmDevice``.
 
 The first connection should show the virtual Looking Glass display created by
-the IDD. If it does not, follow :doc:`the no-display checks
-<troubleshooting>` before changing performance settings.
+the IDD. If it does not, follow :doc:`the no-display checks <troubleshooting>`
+before changing performance settings.
 
 .. note::
 

doc/requirements.rst

@@ -11,28 +11,33 @@ Required
 Linux host
    A Linux system capable of running KVM/QEMU and building the Looking Glass
    Client. The client requires an EGL-capable graphics driver. X11 and Wayland
-   are supported. For a responsive passthrough setup, use at least six CPU
-   cores with twelve hardware threads.
+   are supported. For a responsive passthrough setup, at least six CPU cores
+   with twelve hardware threads are required.
 
 Windows guest
-   A Windows 10 version 1803 or newer, or Windows 11, virtual machine. The
-   recommended IDD path can create its own virtual monitor and does not require
-   a physical monitor or dummy plug.
+   A Windows 10 version 1903 or newer, or Windows 11, virtual machine. Looking
+   Glass can create its own virtual monitor and does not require a physical
+   monitor or dummy plug.
 
 Shared memory
-   An IVSHMEM device large enough for the maximum guest resolution. The KVMFR
-   kernel module is recommended and is required for direct GPU imports.
+   An IVSHMEM device large enough for the maximum guest resolution and refresh
+   rate. The KVMFR kernel module is recommended and is required for direct GPU
+   imports.
 
 Matching components
-   Use the current client, IDD and OBS plugin from the same Looking Glass
-   release. A protocol version mismatch is not supported. Legacy Host users
-   must use the complete matching B7 stack described below.
+   The Looking Glass client, IDD, and OBS plugin (if used) must be of the same
+   version. Legacy Host users must use the B7 stack described below.
 
 The IDD can fall back to software processing if the Windows guest has no
-suitable render GPU. This is useful for compatibility, but hardware processing
-is strongly recommended for lower latency and higher frame rates. Software
+suitable render GPU. This is useful for compatibility and basic applications,
+such as word processing and spreadsheets, but hardware processing is strongly
+recommended for lower latency and higher frame rates, especially games. Software
 mode is SDR-only and does not provide the same performance as the GPU path.
 
+.. seealso::
+
+   :ref:`libvirt_determining_memory`
+
 .. _recommended:
 
 Recommended
@@ -42,15 +47,13 @@ For a responsive high-resolution setup, use:
 
 * a host CPU with eight cores and sixteen threads or better, with full
   performance cores around 3 GHz or faster;
-* KVMFR rather than a plain shared-memory file;
-* a host GPU and driver that support direct DMA imports;
-* a hardware render adapter in the Windows guest; and
-* enough memory bandwidth for the chosen resolution and refresh rate.
+* the KVMFR kernel module rather than a plain shared-memory file;
+* a host GPU and driver that support direct DMA imports; and
+* a hardware render adapter in the Windows guest.
 
-Do not assign every CPU core to the guest. Reserve at least two physical CPU
-cores, or four threads, for Linux. Looking Glass, QEMU, the Linux desktop and
-audio server all need host CPU time. High refresh rates also raise
-shared-memory and GPU bandwidth requirements.
+Reserve at least two physical CPU cores, or four threads, for Linux. Looking
+Glass, QEMU, the Linux desktop and audio server all need host CPU time. High
+refresh rates also raise shared-memory and GPU bandwidth requirements.
 
 For a passed-through GPU, PCIe bandwidth can also limit performance. Use at
 least eight PCIe 3.0 lanes or four PCIe 4.0 lanes where practical.
@@ -60,12 +63,11 @@ least eight PCIe 3.0 lanes or four PCIe 4.0 lanes where practical.
 Physical display and dummy plugs
 --------------------------------
 
-The recommended IDD does not require a physical display or dummy plug. It
-creates a virtual Windows monitor, including on systems without a
-passed-through display output.
+The IDD does not require a physical display or dummy plug: it creates a virtual
+Windows monitor, including on systems without a passed-through display output.
 
 A physical display, dummy plug or another virtual monitor is only required
-when using the :doc:`legacy Host Application <install_host>`, because that
+when using the :doc:`Legacy Host Application </legacy_host>`, because that
 application captures an existing Windows display.
 
 .. _igpu_kvmfr_recommended:
@@ -85,10 +87,11 @@ Looking Glass still works, but uses more CPU and memory bandwidth.
 Windows and HDR
 ---------------
 
-Windows 10 remains supported. Current HDR and wide-color-gamut display features
-depend on newer IddCx interfaces that the driver checks at runtime, so they are
-normally available only on a compatible Windows 11 installation. The IDD
-continues to use its SDR-compatible path when those interfaces are unavailable.
+Windows 10 (version 1903 or newer) remains supported. Current HDR and
+wide-color-gamut display features depend on newer IddCx interfaces that the
+driver checks at runtime, so they are normally available only on a compatible
+Windows 11 installation. The IDD continues to use its SDR-compatible path when
+those interfaces are unavailable.
 
 Native HDR presentation on Linux requires the EGL renderer, Wayland
 ``color-management-v1`` support in the compositor, and an HDR-capable output.

doc/tech_faq.rst

@@ -1,3 +1,5 @@
+.. _technical_faq:
+
 Technical notes
 ###############
 
@@ -54,6 +56,8 @@ interrupts, especially for high-rate pointer updates. The polling intervals
 are configurable for diagnosis, but lowering them without evidence increases
 CPU usage and does not guarantee lower latency.
 
+.. _cadence_bandwidth:
+
 How does cadence reduce bandwidth?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/troubleshooting.rst

@@ -1,52 +1,78 @@
 Troubleshooting
 ###############
 
-Start with the symptom below. Avoid changing polling, synchronization or
-renderer options until the basic server, shared-memory and version checks
-pass.
+When diagnosing issues, start with the guide below. Avoid changing polling,
+synchronization or renderer options until the basic server, shared-memory and
+version checks pass.
 
 .. toctree::
    :maxdepth: 1
 
    idd_diagnostics
 
-.. _when_launching_looking_glass_the_desktop_doesnt_appear:
+.. _client_help_information:
+
+Client information when asking for help
+---------------------------------------
+
+The Looking Glass client outputs a lot of useful information during normal
+operation, which helps a lot with debugging and support when issues arise.
+
+This information is available when running the client in a terminal.
+
+When asking for help, it is important to include the following:
+
+* version information about the client, and IDD;
+* Linux distribution and kernel;
+* X11 or Wayland and the compositor name;
+* host and guest GPU models and drivers;
+* whether ``lgmp:allowDMA`` is enabled;
+* the guest resolution and refresh rate; and
+* accurate reproduction steps that lead to your issue.
+
+All of this information is helpful, and should not be excluded.
+
+.. _issue_monitor_missing:
 
 The Looking Glass monitor is missing in Windows
 -----------------------------------------------
 
-1. Confirm that the guest runs Windows 10 version 1803 or newer, or Windows 11.
+1. Confirm that the guest runs Windows 10 version 1903 or newer, or Windows 11.
 2. Confirm that the IDD installer completed and restart Windows if requested.
 3. Open the IDD helper and its log directory. See :ref:`idd_diagnostics`.
 4. In ``looking-glass-idd.txt``, confirm that IVSHMEM opened with the expected
    size and that at least one configured display mode fits.
-5. Increase IVSHMEM if every suitable mode was filtered. Restart the VM after
-   changing its size.
-6. Ensure the legacy Host service is disabled. Only one Looking Glass Server
-   implementation should use the Looking Glass IVSHMEM device.
+5. Increase the IVSHMEM size and restart the VM if every suitable mode was
+   filtered.
+   - See :ref:`libvirt_determining_memory`
+6. Ensure the legacy host service is disabled. Only one Looking Glass Server
+   implementation should use the IVSHMEM device.
 
 A missing passed-through GPU does not by itself prevent the IDD display from
 appearing. The IDD can start in software mode, although that mode is slower and
 SDR-only.
 
+.. _issue_stuck_on_loading:
+
 The client remains on the waiting screen
 ----------------------------------------
 
-* Confirm that the Windows Looking Glass monitor is active and producing a
-  desktop.
-* Check that the client selected the same KVMFR device or shared-memory file as
-  the VM.
+* Confirm that the Windows Looking Glass monitor is active.
+* Check that the client has selected the same KVMFR device or shared-memory file
+  as the VM, if you have more than one.
 * Confirm that the Linux user has read and write access to that device.
-* Use matching client and IDD releases. A KVMFR or LGMP protocol mismatch is a
-  hard incompatibility.
+* Make sure you are using the same Looking Glass client version as the IDD.
 * If ``/dev/kvmfr0`` is a regular file instead of a character device, stop the
   VM, remove that accidental file and load KVMFR before starting the VM again.
+  See :ref:`KVMFR device verification <ivshmem_kvmfr_verification>`
+
+.. _issue_image_slow:
 
 The image is slow or stutters
 -----------------------------
 
 Open the timing graphs with :kbd:`ScrLk` + :kbd:`T` and follow
-:ref:`client_performance`. Also check:
+:ref:`client_performance`. Also check that:
 
 * the IDD helper reports GPU acceleration rather than software processing;
 * ``lgmp:allowDMA=yes`` is using a direct import when the host driver supports
@@ -56,10 +82,12 @@ Open the timing graphs with :kbd:`ScrLk` + :kbd:`T` and follow
 * the compositor is not adding an unexpected frame queue; and
 * the fastest active client or OBS source is requesting the intended cadence.
 
-Do not set the guest to an extreme refresh rate merely to raise UPS. The IDD
+Do not set the guest to an extreme refresh rate attempting to raise UPS. The IDD
 can acquire newer frames and skip superseded ones before transport, but the
 guest still pays the cost of rendering them.
 
+.. _issue_keyboard_mouse_input:
+
 Keyboard or mouse input does not work
 -------------------------------------
 
@@ -68,8 +96,8 @@ Keyboard or mouse input does not work
 * Only one LGMP client owns direct input. Close another controlling client if
   necessary.
 * If SPICE video fallback is active, keep ``spice:input=yes``. The client uses
-  the VM's default PS/2 keyboard and mouse and intentionally switches input
-  with the video source.
+  the VM's default PS/2 keyboard and mouse, and switches input to follow the
+  video source.
 * If ``input:captureOnly=yes``, press :kbd:`ScrLk` to enter capture mode.
 
 See :ref:`client_input` for normal, automatic keyboard and capture modes.
@@ -82,27 +110,9 @@ The clipboard is not working
 -  **Is clipboard synchronization enabled?**
 
    -  Before you can copy or paste content between the guest and host,
-      :ref:`clipboard
-      synchronization <libvirt_clipboard_synchronization>`
-      must be enabled.
-
--  **Did you install the Spice Guest Tools?**
-
-   -  The `SPICE Guest Tools
-      driver <https://www.spice-space.org/download.html>`_ must be installed
-      inside the Windows guest to synchronize the clipboard.
-      The download is labeled "spice-guest-tools".
-
-      .. warning::
-
-         Do **NOT** install the QEMU Guest Tools driver.
-         These are not the same.
-
-   -  **Is it installed twice?**
-
-      -  The Spice VDAgent is available in both Spice Guest Tools, and
-         standalone as a separate installer. Check your installed programs
-         and uninstall the VDAgent if it's installed separately.
+      clipboard synchronization must be enabled through the ``clipboard:toVM``
+      and ``clipboard:fromVM`` options. These default to on, but check that
+      you haven't disabled them.
 
 .. _keyboard_shortcuts_not_captured_on_gnome_wayland:
 
@@ -110,7 +120,8 @@ Keyboard shortcuts are not captured on GNOME Wayland
 -----------------------------------------------------
 
 Capture mode may fail to capture compositor shortcuts like
-ALT+Tab or ALT+Middle Mouse - they go to GNOME instead of the guest VM.
+:kbd:`Alt` + :kbd:`Tab` or :kbd:`Alt` + :kbd:`Mouse3`—they go to GNOME instead of
+the guest VM.
 
 When Looking Glass first requests to inhibit shortcuts, GNOME shows a
 dialog asking for permission. If you clicked "Deny" (or dismissed the dialog),
@@ -130,11 +141,11 @@ To verify the permission was set:
 
    flatpak permissions gnome shortcuts-inhibitor
 
+.. _issue_usb_audio_not_playing:
+
 USB audio does not appear or play
 ---------------------------------
 
-* Confirm that the client was built with ``libusbredirparser-0.5`` version
-  0.7.1 or newer.
 * Add an unused SPICE **USB Redirector** device to the VM.
 * Keep ``spice:enable=yes``, ``spice:audio=yes`` and
   ``spice:usbAudio=yes``.
@@ -143,10 +154,17 @@ USB audio does not appear or play
 * Check the client startup log. If USB audio creation failed before
   connection, Looking Glass falls back to classic SPICE audio and reports why.
 
+.. seealso::
+
+   :ref:`client_usb_audio`
+
+.. _issue_microphone_missing:
+
 The microphone is unavailable
 ------------------------------
 
-The current PipeWire backend supports recording; the PulseAudio backend does
-not. Ensure the client selected PipeWire, then check ``audio:micDefault`` and
-the microphone indicator. Press :kbd:`ScrLk` + :kbd:`C` to change the default
-permission and :kbd:`ScrLk` + :kbd:`E` to toggle recording.
+The PipeWire audio backend supports recording from the microphone, but the
+PulseAudio backend does not. Ensure the client has selected the PipeWire
+backend, then check ``audio:micDefault`` and the microphone indicator. Press
+:kbd:`ScrLk` + :kbd:`C` to change the default permission and :kbd:`ScrLk` +
+:kbd:`E` to toggle recording.

doc/usage.rst

@@ -1,7 +1,7 @@
 .. _client_usage:
 
-Use the client
-##############
+Using the client
+################
 
 Start the client after the Windows guest and IDD are running:
 
@@ -17,18 +17,17 @@ with ``-f`` or the canonical ``lgmp:shmDevice`` option:
 
    looking-glass-client -f /dev/kvmfr1
 
-Use ``looking-glass-client --help`` to see the options supported by the
-installed build. Command-line options override configuration files.
+Use ``looking-glass-client --help`` to see the options supported by the client.
+Command-line options override configuration files.
 
 .. _client_key_bindings:
 
 Default key bindings
 --------------------
 
-Looking Glass uses :kbd:`ScrLk` as its escape key by default. Press it by
-itself to enter or leave capture mode. Hold it to display the available
-commands. Change it with ``input:escapeKey`` or ``-m`` if the keyboard does
-not have :kbd:`ScrLk`.
+Looking Glass uses :kbd:`ScrLk` as its escape key by default. Press it to enter
+or leave capture mode. Hold it to display the available commands. Change it with
+``input:escapeKey`` or ``-m`` if your keyboard does not have :kbd:`ScrLk`.
 
 .. list-table:: Default client commands
    :widths: 35 65
@@ -75,7 +74,7 @@ not have :kbd:`ScrLk`.
    * - :kbd:`ScrLk` + :kbd:`F1` through :kbd:`F12`
      - Send :kbd:`Ctrl` + :kbd:`Alt` + that function key to a Linux guest
 
-The microphone commands are registered only when the client was built with
+The microphone commands are registered only when the client is built with
 audio recording support. Night vision is an EGL feature. The virtual-console
 bindings are registered only when the selected guest type is Linux.
 
@@ -84,7 +83,7 @@ bindings are registered only when the selected guest type is Linux.
 Configuration files
 -------------------
 
-The client loads these files in order when they exist:
+The client loads these files in order if they exist:
 
 * ``/etc/looking-glass-client.ini``
 * ``~/.looking-glass-client.ini``
@@ -109,7 +108,10 @@ Later files override earlier files. The usual per-user path is
    [egl]
    preset=my-preset
 
-Boolean values accept ``yes`` or ``no``. Long command-line options use
+Boolean values accept ``yes`` or ``no``, as well as ``1`` or ``0``,
+``true`` or ``false``, and ``on`` or ``off``.
+
+Long command-line options use
 ``section:name=value``, for example:
 
 .. code:: bash

doc/words.txt

@@ -27,11 +27,13 @@ downsample
 downsampling
 downscaler
 downscaling
+durations
 EGL
 evdev
 ExtraMode
 Flatpak
 framebuffer
+framerate
 fullscreen
 gcc
 globalFullScreen
@@ -44,6 +46,7 @@ IddCx
 ie
 imgui
 ini
+jitter
 kvmfr
 laggy
 lexically
@@ -89,6 +92,7 @@ repo
 resampler
 Rubenstein
 runtime
+sawtooth
 scanout
 Scream
 scRGB
@@ -104,6 +108,7 @@ Threadripper
 toolchain
 tooltip
 tritanope
+trixie
 tunable
 uaccess
 udev
@@ -119,6 +124,7 @@ upscaler
 upscales
 upscaling
 viewport
+virt
 VirtIO
 virtio
 VM

idd/installer.nsi

@@ -25,6 +25,10 @@
 !include "FileFunc.nsh"
 !include "LogicLib.nsh"
 !include "Sections.nsh"
+!include "WinVer.nsh"
+
+!define LGIDD_MIN_WINDOWS_RELEASE 1903
+!define LGIDD_MIN_WINDOWS_BUILD   18362
 
 ;Settings
 Name "Looking Glass (IDD)"
@@ -34,6 +38,7 @@ RequestExecutionLevel admin
 ShowInstDetails "show"
 ShowUninstDetails "show"
 ManifestDPIAware true
+ManifestSupportedOS all
 
 !ifndef BUILD_32BIT
 Target AMD64-Unicode
@@ -104,6 +109,14 @@ Function .onInit
 
   Pop $R0
 
+  ${IfNot} ${AtLeastBuild} ${LGIDD_MIN_WINDOWS_BUILD}
+    MessageBox MB_OK|MB_ICONSTOP \
+      "$(^Name) requires Windows 10 version ${LGIDD_MIN_WINDOWS_RELEASE} or newer." \
+      /SD IDOK
+    SetErrorLevel 1
+    Abort
+  ${EndIf}
+
 !ifdef IVSHMEM
   Var /GlOBAL option_ivshmem
   StrCpy $option_ivshmem 0