Mirrored_Repos/LookingGlass
1
0
Fork 0
mirror of https://github.com/gnif/LookingGlass.git synced 2026-08-22 07:01:30 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

[docs] guide: document current Looking Glass features

Browse Source
This commit is contained in:
Geoffrey McRae
2026-08-11 19:18:17 +10:00
parent 45429681a0
commit 33bdc611d8
36 changed files with 2356 additions and 1328 deletions
Download Patch File Download Diff File Expand all files Collapse all files

302
doc/faq.rst
View File

@@ -9,271 +9,183 @@ General
How does Looking Glass work?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This YouTube video featured created by the author features a detailed
explanation:
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.
https://www.youtube.com/watch?v=U44lihtNVVM
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?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Looking Glass now features a functional :doc:`OBS plugin <obs>`, which acts as
another Looking Glass client, but instead feeds the captured frames into OBS.
Yes. The :doc:`OBS plugin <obs>` is an independent frame consumer and does not
capture the client window.
.. _why_is_my_ups_so_low:
Why is my UPS (Updates Per Second) so low?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Why is UPS lower than the guest refresh rate?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are several reasons why this can happen, the most common are your
capture resolution, or refresh rate. The windows capture methods currently
struggle to capture high resolutions under certain circumstances.
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.
Some titles do some strange things at early initialization that cause
capture performance issues. One such title is the Unigine Valley
benchmark where the capture rate is limited to 1/2 the actual rate. For
an unknown reason to both myself and the Unigine developers a simple
task switch (alt+tab) in and out resolves the issue. This is not a
Looking Glass bug.
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 my GPU supported?
~~~~~~~~~~~~~~~~~~~~
Is a passed-through GPU required?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Your guest GPU almost certainly supports DXGI. Use DxDiag to confirm
that you have support for WDDM 1.2 or greater.
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 server-side (guest) probing error "Capture is not possible,
unsupported device or driver" indicates NVidia duplication has failed,
not that DXGI has failed. You can fix the error by specifying
``-c DXGI``
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:
Why do I need Spice if I don't want a Spice display device?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Do I need SPICE?
~~~~~~~~~~~~~~~~
You don't need Display Spice enabled. Looking Glass has a Spice client
built in to provide some conveniences, but you can disable it with the
"-s" argument.
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.
.. note::
Without Spice, Looking Glass cannot send mouse/keyboard input to the guest
and clipboard synchronization is disabled.
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:
Where is the host application for Linux?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Which application runs on Linux?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The "Windows host application" is actually the display server, which
runs in the guest VM. The only thing that needs to run in your Linux
host OS is the ``looking-glass-client`` application.
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 producer; “Host” in that name does not mean the Linux host
OS.
You can :ref:`build <host_linux_on_linux>` a version of the host for Linux as
well.
Input and window system
-----------------------
.. _gnome_wayland_decorations:
Why is there no title bar on GNOME? / Why can't I resize the window on GNOME?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Why is there no title bar on GNOME Wayland?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This happens because GNOME on Wayland doesn't support the `standard protocol`_
for server-side decorations, and Looking Glass doesn't implement its own
decorations.
GNOME does not implement the standard Wayland server-side decoration
protocol. Build Looking Glass with libdecor support:
The easiest solution is to build Looking Glass with `libdecor`_ support.
Install the ``libdecor-0-dev`` package. If your distribution lacks this package
or any equivalents, you must build it from `source code <libdecor_>`_.
.. code:: bash
You can then build the the client with libdecor support by passing
``-DENABLE_LIBDECOR=ON`` to ``cmake``.
cmake -DENABLE_LIBDECOR=ON ../
An alternative solution is to hold down the Super key (Windows key on most
keyboards), then right click Looking Glass. This should bring up a menu,
which will allow you to move the window and resize it.
.. warning::
Libdecor support is provided for the convenience of our Wayland users on
GNOME, however it is not a priority feature and may break, please seek
alternatives if you require stable operation.
.. _standard protocol: https://wayland.app/protocols/xdg-decoration-unstable-v1
.. _libdecor: https://gitlab.freedesktop.org/libdecor/libdecor
Mouse
-----
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:
The mouse is jumpy, slow, laggy when using SPICE
Why is SPICE fallback mouse movement different?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Please be sure to install the SPICE guest tools from
https://www.spice-space.org/download.html#windows-binaries.
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.
.. _mouse_desync_when_entering:
The mouse position is wrong when entering the window
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is due to windows mouse acceleration, it can be disabled by
following one of these methods:
- Disabling pointer precision (Control Panel > Mouse > Pointer Options
> Uncheck Enhance pointer precision)
- By changing the acceleration behavior with the following registry
magic:
http://donewmouseaccel.blogspot.com.au/2010/03/markc-windows-7-mouse-acceleration-fix.html
(Contrary to the title this works just fine on Windows 10)
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:
The cursor position doesn't update until I click
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Should I add a virtual tablet?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Make sure you have removed the Virtual Tablet Device from the Virtual
Machine. Due to the design of Windows, absolute pointing devices break
applications/games that require cursor capture, and as such Looking Glass
does not support them.
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
-----
As of B6 Looking Glass supports audio input and output via SPICE.
Does Looking Glass support microphone input and surround sound?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _faq_win:
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`.
Windows
-------
Legacy Host Application
-----------------------
.. _nvfbc_nvidia_capture_api_doesnt_work:
NvFBC (NVIDIA Capture API) doesn't work
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
NvFBC is only supported on professional-grade GPUs, and will not function on
consumer-grade cards like those from the GeForce series.
If you have a supported card, you can enable NVFBC by adding the following
to the host ini file, found at
``%ProgramFiles%\Looking Glass (host)\looking-glass-host.ini``
(create one if it doesn't exist):
.. code:: INI
[app]
capture=nvfbc
.. _the_screen_stops_updating_when_left_idle_for_a_time:
The screen stops updating when left idle for a time
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Windows is likely turning off the display to save power, you can prevent
this by adjusting the ``Power Options`` in the control panel.
The sections below apply only to the legacy Windows Host Application. New
installations should use the IDD. See :ref:`legacy_host_policy`.
.. _faq_host:
Host
----
Where is the legacy Host log?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Where is the log?
~~~~~~~~~~~~~~~~~
The application log is:
The log file for the host application is located at::
``%ProgramData%\Looking Glass (host)\looking-glass-host.txt``
%ProgramData%\Looking Glass (host)\looking-glass-host.txt
The service log is:
You can also open the log file by right clicking on the Looking Glass
system tray icon, then clicking *Open Log File*. This opens the log
file in Notepad.
The log file for the looking glass service is located at::
%ProgramData%\Looking Glass (host)\looking-glass-host-service.txt
This is useful for troubleshooting errors related to the host
application not starting.
High priority capture using DXGI and Secure Desktop (UAC) capture support
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default Windows gives priority to the foreground application for any
GPU work which causes issues with capture if the foreground application
is consuming 100% of the available GPU resources. The looking glass host
application is able to increase the kernel GPU thread to realtime
priority which fixes this, but in order to do so it must run as the
``SYSTEM`` user account. To do this, Looking Glass needs to run as a
service. This can be accomplished by either using the NSIS installer
which will do this for you, or you can use the following command to
Install the service manually:
::
looking-glass-host.exe InstallService
To remove the service use the following command:
::
looking-glass-host.exe UninstallService
This will also enable the host application to capture the secure desktop
which includes things like the lock screen and UAC prompts.
``%ProgramData%\Looking Glass (host)\looking-glass-host-service.txt``
.. _faq_host_admin_privs:
Why does the host require Administrator privileges?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Why does the legacy Host require administrator privileges?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is intentional for several reasons.
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.
1. NvFBC requires a system wide hook to correctly obtain the cursor
position as NVIDIA decided to not provide this as part of the cursor
updates.
2. NvFBC requires administrator level access to enable the interface in
the first place.
3. General capture performance is boosted by taking advantage of high priority
scheduling with SYSTEM level privileges.
.. _nvfbc_nvidia_capture_api_doesnt_work:
NvFBC (NVIDIA Frame Buffer Capture)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Why does NvFBC not work?
~~~~~~~~~~~~~~~~~~~~~~~~
Why can't I compile NvFBC support into the host?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
NvFBC is a legacy Host capture method and requires supported NVIDIA hardware
and SDK licensing. It is not part of the IDD path.
You must download and install the NVidia Capture SDK. Please note that
by doing so you will be agreeing to NVIDIA's SDK License agreement.
.. _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:
Why doesn't Looking Glass work with Scream over IVSHMEM?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Can Scream and Looking Glass share IVSHMEM?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
Using IVSHMEM with Scream may interfere with Looking Glass, as they may try
to use the same 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.
Please do not use the IVSHMEM plugin for Scream.
To fix this issue, use the default network transfer method.
The IVSHMEM method induces additional latency that is built into its
implementation. When using VirtIO for a network device the VM is already using
a highly optimized memory copy anyway so there is no need to make another one.
Technical details
-----------------
If you insist on using IVSHMEM for Scream—despite its inferiority to the
default network implementation—the Windows Host Application can be told
what device to use. Edit the file
``%ProgramFiles%\Looking Glass (host)\looking-glass-host.ini``,
(create one if it doesn't exist)
then, you can add the ``os:shmDevice`` option like so:
.. code:: INI
[os]
shmDevice=1
.. toctree::
:maxdepth: 1
tech_faq