### Doc/Audio .. _client_audio: 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 setup. Selecting SPICE as the primary video transport also uses its audio provider. .. warning:: Do not use Scream for a Looking Glass setup. Use the built-in classic SPICE or USB audio path. Scream over IVSHMEM can also conflict with the shared device used for Looking Glass frames. Looking Glass offers two SPICE audio paths: USB audio (recommended) Presents an emulated Looking Glass USB Audio Class 2 device to Windows over a SPICE USB channel. It supports stereo, quadraphonic, 5.1 and 7.1 playback using 24-bit PCM at up to 192 kHz. It also provides asynchronous playback feedback and a lower-latency clock relationship with supported Linux audio backends. This path is enabled by default when it is available. 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 fallback when the emulated USB audio device is not available. Set ``spice:audio=no`` to disable both paths. .. _client_usb_audio: 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 working client playback backend. For libvirt, add a USB redirection device: .. code:: xml 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. The emulated USB audio device is enabled by default. Its settings are: .. code-block:: ini [spice] audio=yes usbAudio=yes Playback supports stereo, quadraphonic, 5.1 and 7.1 speaker layouts using 24-bit PCM at sample rates up to 192 kHz. Recording supports stereo at up to 192 kHz. 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. Classic SPICE setup ------------------- Add an Intel HDA sound device and a SPICE audio backend to the VM as shown in :ref:`libvirt_spice_server`, then select the classic path: .. code-block:: ini [spice] audio=yes usbAudio=no QEMU's classic SPICE audio implementation exposes a fixed stereo format: two channels, 16-bit samples at 48 kHz. Use the emulated USB audio device when other sample rates, sample formats or channel layouts are required. Microphone access ----------------- PipeWire supports playback and recording. The current PulseAudio backend does not provide microphone recording. Press :kbd:`ScrLk` + :kbd:`E` to toggle recording when it is available. When a guest application opens the microphone, ``audio:micDefault`` controls the response: ``prompt`` Ask before sending microphone audio. This is the default. ``allow`` Allow requests automatically. ``deny`` Refuse requests automatically. Press :kbd:`ScrLk` + :kbd:`C` to cycle this policy. Keep ``audio:micShowIndicator=yes`` to show when recording is active. Latency settings ---------------- ``audio:periodSize`` requests the audio backend period in samples. The default is 512; 0 requests a 10 ms period. Smaller values may reduce latency but also make underruns more likely. ``audio:latencyOffset`` applies only to classic SPICE audio. It adds safety margin to the calculated minimum buffer; the default is 6 ms. Reduce it only after confirming that classic SPICE playback remains free of dropouts under load. ``audio:resampler`` also applies only to classic SPICE audio. The default ``auto`` setting chooses the appropriate path; the other choices are ``libsamplerate`` and ``backend``. The emulated USB audio device instead uses feedback to adjust the Windows packet rate. Set ``audio:debug=yes`` to log ring-buffer level, backend delay, clock feedback and underrun or overrun counts. Disable it after diagnosis to keep the normal log concise. --- ### Doc/Build .. _building: 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. .. _download_source: Downloading ----------- Visit the Looking Glass `Download Page `__, and download the stable version (**Recommended**). You can also download a *bleeding-edge version*, or the latest RC version during a Release Candidate cycle. Developers can clone the source code repo with ``git``. .. code:: bash git clone --recursive https://github.com/gnif/LookingGlass.git .. warning:: Please only clone from Git if you're a developer, and know what you're doing. Looking Glass requires git submodules that must be setup and updated when building. Source code downloads from the website come bundled with the necessary submodules. .. 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`. .. _build_client_section: Client Application ------------------ .. _installing_build_dependencies: Installing build dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These required libraries and tools should be installed first. .. note:: The below list of dependencies is for Debian. A community maintained list of dependencies for other distributions for the current **stable** version of Looking Glass is maintained on the wiki at: https://looking-glass.io/wiki/Installation_on_other_distributions .. _client_dependencies: Required dependencies ^^^^^^^^^^^^^^^^^^^^^ .. Editor note: Listed dependencies are Debian packages containing the required resources. All dependencies must be explicitly defined. Omitting required dependencies that happen to be pulled in via Depends: or Recommends: from another listed package is not allowed. All required packages must be listed. - ``cmake`` - ``binutils`` - ``gcc``, ``g++`` \| ``clang`` - ``libegl-dev`` - ``libgl-dev`` - ``libgles-dev`` - ``libfontconfig-dev`` - ``libgmp-dev`` - ``libspice-protocol-dev`` - ``libxkbcommon-dev`` - ``make`` - ``nettle-dev`` - ``pkg-config`` .. _client_deps_may_be_disabled: May be disabled <<<<<<<<<<<<<<< These dependencies are required by default, but may be omitted if their feature is disabled when running :ref:`cmake `. - Disable with ``cmake -DENABLE_BACKTRACE=no ..`` - ``libdw-dev`` - ``libunwind-dev`` - Disable with ``cmake -DENABLE_X11=no ..`` - ``libx11-dev`` - ``libxfixes-dev`` - ``libxi-dev`` - ``libxinerama-dev`` - ``libxss-dev`` - ``libxcursor-dev`` - ``libxpresent-dev`` - ``libxrandr-dev`` - Disable with ``cmake -DENABLE_WAYLAND=no ..`` - ``libwayland-bin`` - ``libwayland-dev`` - Disable all audio support with ``cmake -DENABLE_AUDIO=no ..`` - ``libpipewire-0.3-dev`` - ``libpulse-dev`` - ``libsamplerate0-dev`` - ``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). .. _client_fetching_with_apt: 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 \ 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 \ libwayland-bin libwayland-dev \ libpipewire-0.3-dev libpulse-dev libsamplerate0-dev \ libusbredirparser-dev You may omit some dependencies if you disable the feature which requires them when running :ref:`cmake `. (See :ref:`client_deps_may_be_disabled`) .. _client_building: 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. .. code:: bash mkdir client/build cd client/build cmake ../ make This will build the ``looking-glass-client`` binary, which is used to display frames from the guest. It also produces ``looking-glass-client.debug``. Keep this file with the matching binary to obtain source locations in crash stack traces. The install target places it in the standard ``bin/.debug`` location automatically. You can then :ref:`continue installing Looking Glass `, or run it directly from the build directory: .. code:: bash ./looking-glass-client .. seealso:: - :ref:`Client installation ` - :ref:`Client usage ` .. note:: For users running GNOME on Wayland, you may want to enable ``libdecor`` when building. .. code:: bash cmake -DENABLE_LIBDECOR=ON ../ For details, see :ref:`the FAQ `. .. note:: The most common compile error is related to backtrace support. Try disabling this when building: .. code:: bash cmake -DENABLE_BACKTRACE=0 ../ If you disable this and need support for a crash, use ``gdb`` to obtain a backtrace manually. --- ### Doc/Build Host .. _host_building: Legacy Host Application build ############################# .. warning:: The Host Application is a legacy server application. New installations should use the prebuilt :doc:`Looking Glass IDD `. These build instructions are retained for the complete matching 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`! 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` on the `guest VM`. The term `Host application` was chosen over `Guest application`, because LG can be run in a VM to VM configuration, in which case both Host Application and Client Application are run inside VM Guests. These instructions help you build the host yourself from the :ref:`downloaded source code `. .. 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. .. note:: The pre-built binaries also include NvFBC support built in, which is only available to current Nvidia SDK license holders, and cannot be enabled when building the host without also having a license. (`link <#dont-build-the-host>`_) .. _host_win_on_win: For Windows on Windows ~~~~~~~~~~~~~~~~~~~~~~ 1. Download and install msys2 x86_64 from `http://www.msys2.org/ `__ following the setup instructions provided 2. Run the MSYS2 shell 3. Download build dependencies with pacman .. code:: bash pacman -Fy pacman -Sy git make mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake 4. Change directory to the source tree with ``cd`` 5. Configure the project and build it .. code:: bash mkdir host/build cd host/build cmake -G "MSYS Makefiles" .. make .. _host_linux_on_linux: For Linux on Linux ~~~~~~~~~~~~~~~~~~ Make a ``host/build`` directory, then run ``cmake`` .. code:: bash mkdir host/build cd host/build cmake .. make .. _host_win_cross_on_linux: For Windows cross compiling on Linux ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Like :ref:`host_linux_on_linux`, but using the mingw64 toolchain to cross-compile a Windows ``.exe`` file. .. code:: bash mkdir host/build cd host/build cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain-mingw64.cmake .. make .. _host_build_installer: Building the Windows installer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. :ref:`Build ` the host on Linux. 2. Install ``nsis`` .. code:: bash apt-get install nsis 3. Use ``makensis`` to build the installer. .. code:: bash cd host/build/platform/Windows makensis installer.nsi .. _host_questions: This will build ``looking-glass-host-setup.exe`` under ``host/build/platform/Windows/looking-glass-host-setup.exe`` .. seealso:: :ref:`Installing the Host ` --- ### Doc/Credits .. _looking_glass_team: Looking Glass team ################## A list of the wonderful people who make this possible. .. _lg_devs: Developers ------------------ * gnif (Geoffrey McRae) * quantum (Guanzhong Chen) * xyene (Tudor Brindus) * spencercw (Chris Spencer) .. _lg_documentation_guys: Documentation ------------- * JJRcop (Jonathan Rubenstein) --- ### Doc/Display .. _client_display: Display and image quality ######################### The EGL renderer is the supported client renderer and is selected automatically. The older OpenGL renderer is deprecated, does not provide direct DMA imports or native HDR, and should only be used to diagnose a compatibility problem. Wayland and X11 are both built by default. Automatic selection prefers Wayland 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. Window and guest resolution --------------------------- With the IDD, ``win:setGuestRes=yes`` asks Windows to match the client viewport when its size changes. Press :kbd:`ScrLk` + :kbd:`=` to request the current size immediately. The IDD creates this as its dynamic ExtraMode using the default refresh configured in the IDD helper. If a requested resolution does not fit in IVSHMEM, the IDD refuses it and the helper reports the required size. See :ref:`libvirt_determining_memory`. Useful window options include: ``win:autoResize`` Resize the client window when the guest resolution changes. ``win:keepAspect`` Preserve the guest aspect ratio while resizing. ``win:fullScreen`` Start in borderless full-screen mode. ``win:rotate`` Rotate the image by 0, 90, 180 or 270 degrees. 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 built-in filters include: * a configurable downscaler; * AMD FidelityFX Super Resolution (FSR); and * AMD FidelityFX Contrast Adaptive Sharpening (CAS). The ``egl:scale`` option selects automatic, nearest-neighbor or linear scaling when a filter does not provide the required scaling. Additional mpv-style GLSL shaders may be loaded from ``eglFilter:glslPath``. The `Anime4K `_ project provides compatible GLSL filters. .. _client_hdr: 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. Native HDR output on Linux requires all of the following: * the EGL renderer; * a Wayland compositor with ``color-management-v1`` support; * an HDR-capable monitor and output configuration; and * a host graphics driver that can present the required color format. 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 default. Native Wayland PQ output also requires compositor support for ST 2084 and BT.2020, while scRGB requires compositor scRGB support. 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. ``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. --- ### Doc/Faq Frequently asked questions ########################## General ------- .. _how_does_looking_glass_work: How does Looking Glass work? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Windows IDD creates a virtual monitor and places completed frames in an IVSHMEM region shared with Linux. The client imports the newest frame, renders it and returns input through the available transport. The image is not encoded as a video stream, which avoids codec latency and quality loss. See :doc:`overview` for the current components. A detailed video explanation is also available at https://www.youtube.com/watch?v=U44lihtNVVM. .. _can_i_feed_the_vm_directly_into_obs: Can I feed the VM directly into OBS? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Yes. The :doc:`OBS plugin ` is an independent frame consumer and does not capture the client window. .. _why_is_my_ups_so_low: Why is UPS lower than the guest refresh rate? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ UPS counts frames delivered to that consumer, not every frame Windows may render. The IDD publishes to the deadline requested by the fastest active client and can skip guest frames that have already been superseded. This saves memory bandwidth without deliberately adding a frame of latency. If UPS is below the active consumer's requested rate, use :ref:`client_performance` to locate the slow stage. High resolution, software processing, memory bandwidth, host scheduling and compositor presentation can all impose a lower limit. .. _is_my_gpu_supported: 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. 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? ~~~~~~~~~~~~~~~~ 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. 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 application runs on Linux? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. Input and window system ----------------------- .. _gnome_wayland_decorations: Why is there no title bar on GNOME Wayland? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GNOME does not implement the standard Wayland server-side decoration protocol. Build Looking Glass with libdecor support: .. code:: bash 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. .. _the_mouse_is_jumpy_slow_laggy_when_using_spice: Why is SPICE fallback mouse movement different? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The IDD's direct input path uses absolute positioning for normal desktop use and relative movement in capture mode. SPICE input is relative-only, so guest 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 virtual tablet? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. Audio ----- 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`. 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: Where is the legacy Host log? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The application log is: ``%ProgramData%\Looking Glass (host)\looking-glass-host.txt`` The service log is: ``%ProgramData%\Looking Glass (host)\looking-glass-host-service.txt`` .. _faq_host_admin_privs: 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. .. _nvfbc_nvidia_capture_api_doesnt_work: 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. .. _the_screen_stops_updating_when_left_idle_for_a_time: 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. .. _a_note_about_ivshmem_and_scream_audio: Can Scream and Looking Glass share IVSHMEM? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. Technical details ----------------- .. toctree:: :maxdepth: 1 tech_faq --- ### Doc/Host Usage .. _host_usage: 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. 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 ----------------- The legacy Host captures an existing Windows display through Desktop Duplication or NvFBC. It does not use Windows Graphics Capture. Select an interface only when automatic selection fails: .. code-block:: ini [app] capture=d12 .. _host_capture_d12: D12 The preferred Direct3D 12 Desktop Duplication path on supported systems. It can copy directly toward shared memory and supports damage tracking. .. _host_capture_dxgi: DXGI The Direct3D 11 Desktop Duplication compatibility path. It may require an additional staging copy and can show cursor-related capture jitter. .. _host_capture_nvfbc: 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. .. _host_select_ivshmem: Select an IVSHMEM device ------------------------ 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 [os] 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. .. _host_downsampling: Downsampling ------------ 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 ; Downsample exactly 3840x2160 to 1920x1080 downsample=3840x2160:1920x1080 ; Downsample anything larger than 1920x1080 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. --- ### Doc/Idd Configuration .. _idd_configuration: Configure the IDD ################# 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. Display modes ------------- The mode list controls the resolutions and refresh rates that Windows may use for the Looking Glass monitor. * Select a mode to edit its width, height or refresh rate, then select **Update**. * Select ****, enter a mode in the fields below the list and select **Update** to add it. * Select **Delete** to remove the selected mode. * Select **Load default** to replace the working list with the standard modes. * 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 ``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. Default refresh --------------- **Default refresh** is used when the client asks the IDD to create a dynamic 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 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. Preferences ----------- Make LG the only monitor Makes the Looking Glass display the only active Windows monitor. This is enabled by default and the helper restores the topology when required. Disable it if you intentionally use other guest displays at the same time. Disabling it stops future enforcement but does not automatically restore displays that Windows has already disabled. 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. Unlike mode-list edits, preference checkboxes are saved when clicked. Software processing ------------------- 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 .. _idd_diagnostics: IDD status and logs ################### 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)`` Collect these files when reporting an IDD fault: * ``looking-glass-idd.txt``: display creation, GPU selection, modes, transport and frame scheduling; * ``looking-glass-input.txt``: direct keyboard and mouse device activity; * ``looking-glass-idd-service.txt``: service and driver control requests; and * ``looking-glass-idd-helper.txt``: configuration, topology and user notifications. Each log rotates through suffixes ``.1`` to ``.4``. Include the current file and rotated files when the problem happened before the most recent restart. Useful IDD lines ---------------- Render adapter Shows the Windows GPU selected by the IDD. A software-processing warning explains why HDR, cadence and high frame rates are unavailable. IVSHMEM size Confirms which device was opened and its capacity. Compare this with the VM configuration and :ref:`libvirt_determining_memory`. Filtered mode A configured mode was omitted because its frame buffers do not fit. Increase IVSHMEM or remove the oversized 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. Frame schedule owner 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. 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 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. .. toctree:: :maxdepth: 2 overview requirements quickstart build install usage troubleshooting obs faq legacy_host .. toctree:: :hidden: credits More information: * `Official Website `_ * `GitHub `_ * `Discord `_ * `Forum `_ * `Community wiki `_ * IRC - #LookingGlass on `libera.chat `_ Donate: * `GitHub `__ * `Ko-Fi `_ * `Patreon `_ * `PayPal `_ Expand a cryptocurrency address to copy it: .. raw:: html
Bitcoin (BTC) 14ZFcYjsKPiVreHqcaekvHGL846u3ZuT13
Ethereum (ETH) 0x6f8aEe454384122bF9ed28f025FBCe2Bce98db85
Monero (XMR) 47xM4zG7b2tEj4mnSywHve4ydZzn3wzhf22snDRB7aSEcXrgUBpoT2Z4phTnyFMi1sMyQtHbdufMYRQ2PzMn3PGUJAE1dpc
--- ### Doc/Input .. _client_input: Keyboard and mouse input ######################## The current IDD provides keyboard and mouse input directly over LGMP. It uses absolute positioning for normal desktop use and relative movement in capture mode. SPICE remains available as a fallback when direct input is unavailable. The client changes input provider automatically. If the displayed video has fallen back to SPICE, the client also uses SPICE input so that the picture and pointer always refer to the same guest. Only one LGMP client controls direct input at a time. Starting another client does not give both clients simultaneous control. Disconnecting or restarting the IDD releases held keys and buttons before ownership changes. Normal input ------------ Move the pointer into the guest view to use absolute desktop input. This keeps the guest pointer aligned without requiring capture. Direct IDD input supports the keyboard, media keys and up to 32 mouse buttons. SPICE fallback uses relative mouse input and supports fewer extra buttons. Capture mode ------------ Press the escape key, :kbd:`ScrLk` by default, to capture the mouse. Capture mode confines the pointer and sends relative motion, which is appropriate for games and applications that lock the cursor. Press the escape key again to leave capture mode. Common capture options are: ``input:captureOnFocus`` Enter capture mode whenever the client receives focus. ``input:captureOnStart`` Start captured. ``input:captureOnly`` Disable guest input outside capture mode. ``input:rawMouse`` Use raw relative mouse input in capture mode. This is usually best for games. ``input:mouseSens`` Adjust relative sensitivity from -9 to 9. The default is 0. ``input:hideCursor`` Hide the host cursor while Looking Glass renders the guest cursor. Automatic keyboard capture -------------------------- Set ``input:autoCapture=yes`` to grab the keyboard when the pointer enters the guest view. Looking Glass predicts when the next mouse movement would leave the guest area and releases the keyboard before that movement. This makes it possible to move naturally between Looking Glass and the Linux desktop without using the escape key for the keyboard. Automatic keyboard capture is disabled by ``input:captureOnly=yes``. It also keeps the keyboard grabbed while a mouse button is held so that dragging does not unexpectedly leave the guest. This is separate from full mouse capture: the pointer remains in normal absolute mode. Use regular capture mode when an application requires relative mouse input. ``input:grabKeyboardOnFocus`` instead keeps the keyboard grabbed while the guest view is active. ``input:grabKeyboard`` controls whether full capture mode grabs the keyboard. SPICE fallback -------------- Keep ``spice:input=yes`` when SPICE input fallback is wanted. It uses the VM's default PS/2 keyboard and mouse, so no additional virtio input devices or tablet are required. To disable all SPICE input while keeping SPICE audio or clipboard services: .. code-block:: ini [spice] input=no If direct input is also unavailable, the client will display video without being able to control the guest. Evdev capture ------------- Advanced users may list Linux evdev devices in ``input:evdev``. They become active whenever Looking Glass grabs the keyboard, including capture mode and automatic keyboard capture. The client user must be allowed to read those devices. Keep ``input:evdevExclusive=yes`` unless duplicate input from the window system is specifically required. --- ### Doc/Install .. _installing: 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: 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. .. toctree:: install_libvirt install_idd install_client --- ### Doc/Install Client .. _installing_client: Client Application Installation ############################### .. _client_install: For Linux --------- 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 `, then run the following from the client build directory as root:: make install To install for the current user only, configure the build with a user-local 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. --- ### Doc/Install Host .. _installing_host: .. _host_install: Legacy Host Application installation #################################### .. warning:: The Host Application is the legacy implementation of the Looking Glass Server. New installations should use the :doc:`Looking Glass 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. The legacy Looking Glass Host Application captures frames from the guest using a capture API, and sends them to the :ref:`client `—be it on the host OS (hypervisor) or another 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 the source code as described in :ref:`building`, then :ref:`build the host `. .. _host_install_linux: For Linux ^^^^^^^^^ While the host application can be compiled and is somewhat functional for Linux it is currently considered incomplete and not ready for usage. As such use at your own risk and do not ask for support. .. _host_install_osx: For OSX ^^^^^^^ Currently there is no support or plans for support for OSX due to technical limitations. .. _host_install_windows: For Windows ^^^^^^^^^^^ To begin, you must first run the Windows VM with the changes noted in the :doc:`install_libvirt` section. .. _installing_the_ivshmem_driver: 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. .. _host_install_service: Installing the Looking Glass service ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ After installing your IVSHMEM driver, we can now install the Looking Glass Host onto our Windows Virtual Machine. 1. First, run ``looking-glass-host-setup.exe`` as an administrator (:ref:`Why? `) 2. You will be greeted by an intro screen. Press ``Next`` to continue. 3. You are presented with the |license| license. Please read and agree to the license by pressing ``Agree``. 4. You can change the install path if you wish, otherwise press ``Next`` to continue. 5. You may enable or disable options on this screen to configure the installation. The default values are recommended for most users. Press ``Install`` to begin installation. 6. After a few moments, installation will complete, and you will have a running instance of Looking Glass. If you experience failures, you can see them in the install log appearing in the middle of the window. 7. Press ``Close`` to exit the installer. 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 .. _installing_idd: 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 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. The display may briefly disappear while Windows installs or reloads the driver. Restart Windows if the installer requests it. 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. 3. Select **IVSHMEM Driver** if a suitable IVSHMEM driver is not already installed in the guest. 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. 6. Complete the installation and restart Windows if requested. 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 input package to install. 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. Windows may briefly remove and recreate the virtual display. Restart Windows when the installer reports that a restart is required. Uninstall --------- 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. Silent installation ------------------- The installer accepts these options for managed installations: ``/S`` Install silently. The uppercase spelling is required. ``/ivshmem`` Install the bundled IVSHMEM driver when it is present in the installer. ``/D=path`` Change the installation directory. This must be the final option and must not be quoted. Configuration and diagnostics ----------------------------- .. toctree:: :maxdepth: 1 idd_configuration For faults, the helper can open the IDD log directory directly. See :ref:`idd_diagnostics` for the files to collect. --- ### Doc/Install Libvirt .. _installing_libvirt: 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. .. _libvirt_determining_memory: Determining memory ^^^^^^^^^^^^^^^^^^ Calculate the IVSHMEM requirement 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) Convert the result to MiB and round it up to the next power of two. The common values below have already been rounded. 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. .. note:: 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 :header-rows: 1 * - Maximum resolution - Total IVSHMEM size (MiB) * - 1920x1080 (1080p) - 32 * - 1920x1200 - 32 * - 2560x1440 (1440p) - 64 * - 3440x1440 - 64 * - 3840x2160 (4K) - 128 * - 5120x1440 - 128 * - 5120x2880 (5K) - 256 * - 7680x4320 (8K) - 512 .. _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`. .. _libvirt_ivshmem: IVSHMEM ^^^^^^^ There are two methods of configuring IVSHMEM, using shared memory directly, or using the KVMFR kernel module. While the KVMFR module is slightly more complicated to configure, it substantially improves performance as it allows Looking Glass to use your GPUs DMA engine to transfer the frame data. .. toctree:: :maxdepth: 1 ivshmem_kvmfr ivshmem_shm .. seealso:: :ref:`igpu_kvmfr_recommended` .. _libvirt_spice_server: Keyboard/mouse/display/audio ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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. .. 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``. Keep a ```` device if you want these services. For a usable display fallback, set the VM's ``