mirror of
https://github.com/gnif/LookingGlass.git
synced 2026-10-29 16:07:21 +00:00
[docs] guide: document current Looking Glass features
This commit is contained in:
Geoffrey McRae
111
.github/ISSUE_TEMPLATE/bug_report.md
vendored
111
.github/ISSUE_TEMPLATE/bug_report.md
vendored
@@ -1,73 +1,84 @@
|
|||||||
---
|
---
|
||||||
name: Bug report
|
name: Bug report
|
||||||
about: Report bugs in Looking Glass (only confirmed bugs and feature requests please)
|
about: Report a reproducible Looking Glass fault
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### Issues are for Bug Reports and Feature Requests Only!
|
## Before reporting
|
||||||
|
|
||||||
If you are looking for help or support please use one of the following methods
|
Use the forum or Discord for setup help:
|
||||||
|
|
||||||
Create a New Topic on the Level1Tech's forum under the Looking Glass category:
|
- https://forum.level1techs.com/c/software/lookingGlass/142
|
||||||
* https://forum.level1techs.com/c/software/lookingGlass/142
|
- https://discord.gg/52SMupxkvt
|
||||||
|
|
||||||
Ask for help in the Looking Glass discord server
|
Use GitHub issues for reproducible bugs and feature requests. Check the current
|
||||||
* https://discord.gg/52SMupxkvt
|
documentation and existing issues first. Do not report a protocol mismatch
|
||||||
|
until the client, IDD and OBS plugin have been updated to the same release.
|
||||||
|
|
||||||
*Issues that are not bug reports or feature requests will be closed & ignored*
|
## Describe the fault
|
||||||
|
|
||||||
### Errors that are not bugs
|
What happened, what did you expect, and what exact steps reproduce it?
|
||||||
|
|
||||||
Some errors generated by the LG client are not bugs, but rather issues with your
|
|
||||||
system's configuration and/or timing. Please do not report these, but rather use
|
|
||||||
one of the above resources to ask for advice/help.
|
|
||||||
|
|
||||||
* `LGMP_ERR_QUEUE_UNSUBSCRIBED` - Failure to heed advice on things such as
|
|
||||||
using `isolcpus` and CPU pinning may result in this message, especially if you
|
|
||||||
are over-taxing your CPU.
|
|
||||||
|
|
||||||
* `Could not create an SDL window: *` - Failure to create a SDL window is not an
|
|
||||||
issue with Looking Glass but rather a more substantial issue with your system,
|
|
||||||
such as missing hardware support for the RGBA32 pixmap format, or missing
|
|
||||||
required OpenGL EGL features.
|
|
||||||
|
|
||||||
* `The host application is not compatible with this client` - The Looking Glass
|
|
||||||
Host application in Windows is the incorrect version and is not compatible,
|
|
||||||
you need to make sure you run matching versions of both the host and client
|
|
||||||
applications.
|
|
||||||
|
|
||||||
### Bug Report Required Information
|
|
||||||
|
|
||||||
The entire (not truncated) output from the client application (if applicable).
|
|
||||||
To obtain this run `looking-glass-client` in a terminal.
|
|
||||||
|
|
||||||
```
|
```
|
||||||
PASTE CLIENT OUTPUT HERE
|
DESCRIPTION AND STEPS
|
||||||
```
|
```
|
||||||
|
|
||||||
The entire (not truncated) log file from the host application (if applicable).
|
Does it reproduce every time? If not, how often?
|
||||||
Normally, this is found on the guest system at:
|
|
||||||
|
|
||||||
%ProgramData%\Looking Glass (host)\looking-glass-host.txt
|
|
||||||
|
|
||||||
This log may be quite long, please delete the file first and then proceed to
|
|
||||||
launch the host and reproduce the issue so that the log only contains the
|
|
||||||
pertinent information.
|
|
||||||
|
|
||||||
|
|
||||||
```
|
```
|
||||||
PASTE HOST LOG FILE CONTENTS HERE
|
REPRODUCTION RATE
|
||||||
```
|
```
|
||||||
|
|
||||||
If the client is unexpectedly exiting without a backtrace, please provide one via
|
## Versions and system
|
||||||
gdb with the command `thread apply all bt`. If you are unsure how to do this
|
|
||||||
please watch the video below on how to perform a Debug build and generate this
|
|
||||||
backtrace.
|
|
||||||
|
|
||||||
https://www.youtube.com/watch?v=EqxxJK9Yo64
|
- Looking Glass Client version:
|
||||||
|
- Looking Glass IDD or legacy Host version:
|
||||||
|
- OBS plugin version, if applicable:
|
||||||
|
- Linux distribution and kernel:
|
||||||
|
- X11 or Wayland, and compositor:
|
||||||
|
- Host GPU and driver:
|
||||||
|
- Guest GPU and driver, or IDD software mode:
|
||||||
|
- Guest resolution and refresh rate:
|
||||||
|
- Primary transport (`lgmp` or `spice`):
|
||||||
|
- DMA enabled and successfully imported:
|
||||||
|
|
||||||
|
## Client output
|
||||||
|
|
||||||
|
Run `looking-glass-client` from a terminal, reproduce the fault and include its
|
||||||
|
complete output from startup. Do not include only the final error.
|
||||||
|
|
||||||
```
|
```
|
||||||
PASTE FULL BACKTRACE HERE
|
PASTE COMPLETE CLIENT OUTPUT
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Windows logs
|
||||||
|
|
||||||
|
For the IDD, use its notification-area helper to open
|
||||||
|
`C:\ProgramData\Looking Glass (IDD)` and attach the current files plus rotated
|
||||||
|
files from the affected run:
|
||||||
|
|
||||||
|
- `looking-glass-idd.txt`
|
||||||
|
- `looking-glass-input.txt`
|
||||||
|
- `looking-glass-idd-service.txt`
|
||||||
|
- `looking-glass-idd-helper.txt`
|
||||||
|
|
||||||
|
For the legacy Host Application, attach:
|
||||||
|
|
||||||
|
- `C:\ProgramData\Looking Glass (host)\looking-glass-host.txt`
|
||||||
|
- `C:\ProgramData\Looking Glass (host)\looking-glass-host-service.txt`
|
||||||
|
|
||||||
|
## Crash backtrace
|
||||||
|
|
||||||
|
For a client crash without a complete built-in trace, run the client under
|
||||||
|
`gdb`, reproduce it, then run:
|
||||||
|
|
||||||
|
```
|
||||||
|
thread apply all bt full
|
||||||
|
```
|
||||||
|
|
||||||
|
Attach that output and keep the matching `looking-glass-client.debug` file
|
||||||
|
available.
|
||||||
|
|
||||||
|
## Additional evidence
|
||||||
|
|
||||||
|
Attach screenshots, timing graphs, OBS logs or short recordings when they make
|
||||||
|
the fault clearer. State which settings differ from their defaults.
|
||||||
|
|||||||
23
README.md
23
README.md
@@ -1,12 +1,27 @@
|
|||||||
# Looking Glass
|
# Looking Glass
|
||||||
|
|
||||||
An extremely low latency KVMFR (KVM FrameRelay) implementation for guests with
|
Looking Glass lets you use a Windows virtual machine from Linux with very low
|
||||||
VGA PCI Passthrough.
|
display and input latency. The current recommended setup uses the Looking Glass
|
||||||
|
Indirect Display Driver (IDD) in the Windows guest and the Looking Glass Client
|
||||||
|
on the Linux host.
|
||||||
|
|
||||||
* Project Website: https://looking-glass.io
|
* Project Website: https://looking-glass.io
|
||||||
* Documentation: https://looking-glass.io/docs
|
* Documentation: https://looking-glass.io/docs
|
||||||
|
|
||||||
## Documentation
|
## Start here
|
||||||
|
|
||||||
|
The Linux client is currently distributed as source code and must be built
|
||||||
|
before it can be installed. The end-user guide covers the complete process:
|
||||||
|
|
||||||
|
1. Build the Linux client.
|
||||||
|
2. Configure shared memory for the virtual machine.
|
||||||
|
3. Install the Looking Glass IDD in Windows.
|
||||||
|
4. Install and run the client.
|
||||||
|
|
||||||
|
See the [Looking Glass documentation](https://looking-glass.io/docs) for the
|
||||||
|
current requirements and setup guide.
|
||||||
|
|
||||||
|
## Source archives
|
||||||
|
|
||||||
❕❕❕ **IMPORTANT** ❕❕❕
|
❕❕❕ **IMPORTANT** ❕❕❕
|
||||||
|
|
||||||
@@ -16,7 +31,7 @@ Glass, please download the source archive from the website instead:
|
|||||||
|
|
||||||
https://looking-glass.io/downloads
|
https://looking-glass.io/downloads
|
||||||
|
|
||||||
Source code for the documentation can be found in the `/doc` directory.
|
Source code for the documentation can be found in the `doc` directory.
|
||||||
|
|
||||||
You may view this locally as HTML by running `make html` with `python3-sphinx`
|
You may view this locally as HTML by running `make html` with `python3-sphinx`
|
||||||
and `python3-sphinx-rtd-theme` installed.
|
and `python3-sphinx-rtd-theme` installed.
|
||||||
|
|||||||
@@ -1,32 +1,49 @@
|
|||||||
# Debugging the Looking Glass Client
|
# Debugging the Looking Glass Client
|
||||||
|
|
||||||
If you are asked to provide debugging information to resolve an issue please
|
Start by running `looking-glass-client` in a terminal and retain its complete
|
||||||
follow the following procedure.
|
output from startup through the fault. It records the selected transport,
|
||||||
|
renderer, display server, import method and audio backend.
|
||||||
|
|
||||||
## If you're experiencing a crash:
|
## Crashes
|
||||||
|
|
||||||
Run the program under the `gdb` debugger (you may need to install gdb), for
|
Run the matching binary under `gdb`:
|
||||||
example:
|
|
||||||
|
|
||||||
gdb ./looking-glass-client
|
```text
|
||||||
|
gdb ./looking-glass-client
|
||||||
|
```
|
||||||
|
|
||||||
If you need to set any arguments, do so now by running `set args ARGS`, for
|
Set arguments when needed:
|
||||||
example:
|
|
||||||
|
|
||||||
set args -F -k
|
```text
|
||||||
|
set args -F -k
|
||||||
|
```
|
||||||
|
|
||||||
Now start the program by typing `r`. When the application crashes you will be
|
Start with `run`. After the crash, collect every thread and local variable:
|
||||||
dumped back into the debugger, the application may appear to be frozen. Run
|
|
||||||
the following command:
|
|
||||||
|
|
||||||
thread apply all bt
|
```text
|
||||||
|
thread apply all bt full
|
||||||
|
```
|
||||||
|
|
||||||
Once you have this information please pastebin the log from looking-glass as
|
Provide that output together with the complete client log. Keep
|
||||||
well as the information resulting from this command.
|
`looking-glass-client.debug` from the same build; installed builds place it in
|
||||||
|
the standard `bin/.debug` location.
|
||||||
|
|
||||||
## If you're experencing high CPU load and/or poor performance.
|
## Hangs or high CPU use
|
||||||
|
|
||||||
The steps here are identical to the above, except instead of waiting for the
|
Run under `gdb` as above. While the fault is visible, press `Ctrl+C` in the
|
||||||
program to crash, in the debugger press `CTRL+C` while the program is
|
debugger and collect:
|
||||||
exhibiting the problem, then run `thread apply all bt` and pastebin your log
|
|
||||||
and the results of the command.
|
```text
|
||||||
|
thread apply all bt full
|
||||||
|
```
|
||||||
|
|
||||||
|
For an intermittent stall, collect several samples rather than one. Include
|
||||||
|
the frame-timing graph when it helps identify the affected stage.
|
||||||
|
|
||||||
|
## IDD faults
|
||||||
|
|
||||||
|
Use the Windows IDD helper to open
|
||||||
|
`C:\ProgramData\Looking Glass (IDD)`. Collect the IDD, input, service and helper
|
||||||
|
logs, including rotated `.1` through `.4` files when the fault happened before
|
||||||
|
the latest restart. See the end-user IDD diagnostics page for the exact file
|
||||||
|
names.
|
||||||
|
|||||||
@@ -2305,9 +2305,9 @@ static PlaybackDataResult playbackData(const void * data, size_t frameCount,
|
|||||||
const int maxPeriodFrames =
|
const int maxPeriodFrames =
|
||||||
max(audio.playback.deviceMaxPeriodFrames, sourceData->devPeriodFrames);
|
max(audio.playback.deviceMaxPeriodFrames, sourceData->devPeriodFrames);
|
||||||
/* The device period, delivery jitter, packet phase, and resampler delay
|
/* The device period, delivery jitter, packet phase, and resampler delay
|
||||||
* define the minimum viable latency. latencyOffset is strictly an additive
|
* define the minimum viable latency. Provider feedback directly controls
|
||||||
* user offset over that same minimum for both startup and steady state. */
|
* the source rate, so latencyOffset only applies to local rate control. */
|
||||||
const double latencyOffsetFrames =
|
const double latencyOffsetFrames = providerRateControl ? 0.0 :
|
||||||
max(g_params.audioLatencyOffset, 0) *
|
max(g_params.audioLatencyOffset, 0) *
|
||||||
audio.playback.sampleRate / 1000.0;
|
audio.playback.sampleRate / 1000.0;
|
||||||
const double arrivalReserveFrames =
|
const double arrivalReserveFrames =
|
||||||
|
|||||||
@@ -86,9 +86,9 @@ static void spiceSetup(void)
|
|||||||
{
|
{
|
||||||
.module = "spice",
|
.module = "spice",
|
||||||
.name = "usbAudio",
|
.name = "usbAudio",
|
||||||
.description = "Use USB redirection for SPICE audio playback",
|
.description = "Use the emulated USB audio device",
|
||||||
.type = OPTION_TYPE_BOOL,
|
.type = OPTION_TYPE_BOOL,
|
||||||
.value.x_bool = false
|
.value.x_bool = true
|
||||||
},
|
},
|
||||||
{0}
|
{0}
|
||||||
};
|
};
|
||||||
|
|||||||
131
doc/audio.rst
Normal file
131
doc/audio.rst
Normal file
@@ -0,0 +1,131 @@
|
|||||||
|
.. _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
|
||||||
|
|
||||||
|
<redirdev bus='usb' type='spicevmc'/>
|
||||||
|
|
||||||
|
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.
|
||||||
@@ -1,11 +1,11 @@
|
|||||||
.. _building:
|
.. _building:
|
||||||
|
|
||||||
Building
|
Build the Linux client
|
||||||
########
|
######################
|
||||||
|
|
||||||
The following instructions will help you build Looking Glass from source code.
|
The Looking Glass Client is currently distributed as source code. Building it
|
||||||
Before attempting this, you should have a basic understanding of
|
is a normal part of installation, not an optional developer step. These
|
||||||
how to use the shell.
|
instructions require basic familiarity with a Linux shell.
|
||||||
|
|
||||||
.. _download_source:
|
.. _download_source:
|
||||||
|
|
||||||
@@ -32,8 +32,10 @@ Developers can clone the source code repo with ``git``.
|
|||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
When using the latest bleeding-edge client version,
|
The current client, IDD and OBS plugin must come from the same Looking Glass
|
||||||
you *MUST* download and install the corresponding host application.
|
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:
|
.. _build_client_section:
|
||||||
|
|
||||||
@@ -75,6 +77,7 @@ Required dependencies
|
|||||||
- ``libfontconfig-dev``
|
- ``libfontconfig-dev``
|
||||||
- ``libgmp-dev``
|
- ``libgmp-dev``
|
||||||
- ``libspice-protocol-dev``
|
- ``libspice-protocol-dev``
|
||||||
|
- ``libxkbcommon-dev``
|
||||||
- ``make``
|
- ``make``
|
||||||
- ``nettle-dev``
|
- ``nettle-dev``
|
||||||
- ``pkg-config``
|
- ``pkg-config``
|
||||||
@@ -101,10 +104,10 @@ feature is disabled when running :ref:`cmake <client_building>`.
|
|||||||
- ``libxss-dev``
|
- ``libxss-dev``
|
||||||
- ``libxcursor-dev``
|
- ``libxcursor-dev``
|
||||||
- ``libxpresent-dev``
|
- ``libxpresent-dev``
|
||||||
|
- ``libxrandr-dev``
|
||||||
|
|
||||||
- Disable with ``cmake -DENABLE_WAYLAND=no ..``
|
- Disable with ``cmake -DENABLE_WAYLAND=no ..``
|
||||||
|
|
||||||
- ``libxkbcommon-dev``
|
|
||||||
- ``libwayland-bin``
|
- ``libwayland-bin``
|
||||||
- ``libwayland-dev``
|
- ``libwayland-dev``
|
||||||
|
|
||||||
@@ -113,6 +116,7 @@ feature is disabled when running :ref:`cmake <client_building>`.
|
|||||||
- ``libpipewire-0.3-dev``
|
- ``libpipewire-0.3-dev``
|
||||||
- ``libpulse-dev``
|
- ``libpulse-dev``
|
||||||
- ``libsamplerate0-dev``
|
- ``libsamplerate0-dev``
|
||||||
|
- ``libusbredirparser-dev``
|
||||||
|
|
||||||
- Disable with ``cmake -DENABLE_PIPEWIRE=no ..``
|
- Disable with ``cmake -DENABLE_PIPEWIRE=no ..``
|
||||||
|
|
||||||
@@ -122,6 +126,10 @@ feature is disabled when running :ref:`cmake <client_building>`.
|
|||||||
|
|
||||||
- ``libpulse-dev``
|
- ``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.
|
``libsamplerate0-dev`` is required whenever audio support remains enabled.
|
||||||
|
|
||||||
.. _client_deps_recommended:
|
.. _client_deps_recommended:
|
||||||
@@ -141,20 +149,21 @@ You can fetch these dependencies with the following command:
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Do not just blindly install the list below, check if you are using PipeWire
|
The command below builds both PipeWire and PulseAudio playback backends.
|
||||||
or PulseAudio and adjust the list accordingly. Installing PipeWire libraries
|
Omit one development package only when also disabling its backend in CMake.
|
||||||
on a PulseAudio system will result in a broken partial PipeWire install.
|
Microphone recording requires PipeWire; the current PulseAudio backend is
|
||||||
|
playback-only.
|
||||||
If you are not already using PipeWire we highly recommend you upgrade,
|
|
||||||
Looking Glass does not support audio input (microphone) with PulseAudio.
|
|
||||||
|
|
||||||
.. code:: bash
|
.. code:: bash
|
||||||
|
|
||||||
apt-get install binutils cmake fonts-dejavu-core libdw-dev libfontconfig-dev \
|
apt-get install binutils cmake make fonts-dejavu-core libdw-dev \
|
||||||
libunwind-dev gcc g++ pkg-config libegl-dev libgl-dev libgles-dev \
|
libfontconfig-dev libgmp-dev libunwind-dev gcc g++ pkg-config \
|
||||||
libspice-protocol-dev nettle-dev libx11-dev libxcursor-dev libxi-dev libxinerama-dev \
|
libegl-dev libgl-dev libgles-dev libspice-protocol-dev nettle-dev \
|
||||||
libxpresent-dev libxss-dev libxkbcommon-dev libwayland-dev \
|
libx11-dev libxcursor-dev libxfixes-dev libxi-dev libxinerama-dev \
|
||||||
libpipewire-0.3-dev libpulse-dev libsamplerate0-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
|
You may omit some dependencies if you disable the feature which requires them
|
||||||
when running :ref:`cmake <client_building>`.
|
when running :ref:`cmake <client_building>`.
|
||||||
@@ -219,8 +228,15 @@ it directly from the build directory:
|
|||||||
|
|
||||||
.. _host_building:
|
.. _host_building:
|
||||||
|
|
||||||
Host Application
|
Legacy Host Application build
|
||||||
----------------
|
-----------------------------
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
The Host Application is a legacy frame producer. 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`.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
|
|||||||
11
doc/conf.py
11
doc/conf.py
@@ -22,7 +22,7 @@ from lgrelease import release
|
|||||||
# -- Project information -----------------------------------------------------
|
# -- Project information -----------------------------------------------------
|
||||||
|
|
||||||
project = 'Looking Glass'
|
project = 'Looking Glass'
|
||||||
copyright = '2024, Looking Glass team'
|
copyright = '2026, Looking Glass team'
|
||||||
author = 'Geoffrey McRae and the Looking Glass team'
|
author = 'Geoffrey McRae and the Looking Glass team'
|
||||||
|
|
||||||
rst_prolog = """
|
rst_prolog = """
|
||||||
@@ -55,7 +55,7 @@ else:
|
|||||||
spelling_word_list_filename = [os.path.join(os.path.dirname(__file__), 'words.txt')]
|
spelling_word_list_filename = [os.path.join(os.path.dirname(__file__), 'words.txt')]
|
||||||
|
|
||||||
# Add any paths that contain templates here, relative to this directory.
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
# templates_path = ['_templates']
|
templates_path = ['templates/']
|
||||||
|
|
||||||
# List of patterns, relative to source directory, that match files and
|
# List of patterns, relative to source directory, that match files and
|
||||||
# directories to ignore when looking for source files.
|
# directories to ignore when looking for source files.
|
||||||
@@ -78,10 +78,15 @@ html_unescape_onlyinclude = []
|
|||||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||||
# a list of builtin themes.
|
# a list of builtin themes.
|
||||||
#
|
#
|
||||||
html_theme = 'sphinx_rtd_theme'
|
html_theme = 'lookingglass'
|
||||||
|
|
||||||
|
html_theme_path = [
|
||||||
|
'theme/',
|
||||||
|
]
|
||||||
|
|
||||||
html_theme_options = {
|
html_theme_options = {
|
||||||
'logo_only': True,
|
'logo_only': True,
|
||||||
|
'prev_next_buttons_location': 'both',
|
||||||
'style_nav_header_background': '#343131',
|
'style_nav_header_background': '#343131',
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -1,17 +1,9 @@
|
|||||||
/* Center content in the RTD theme */
|
/* Align content with the navigation menu */
|
||||||
@media screen and (min-width: 1100px) {
|
@media screen and (min-width: 769px) {
|
||||||
.wy-nav-content-wrap {
|
|
||||||
margin-left: auto;
|
|
||||||
}
|
|
||||||
|
|
||||||
.wy-nav-content {
|
|
||||||
margin: auto;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
@media screen and (min-width:769px) and (max-width:1420px) {
|
|
||||||
.wy-nav-content-wrap {
|
.wy-nav-content-wrap {
|
||||||
|
background: #edf0f2;
|
||||||
margin-left: 300px;
|
margin-left: 300px;
|
||||||
|
padding-left: 12px;
|
||||||
}
|
}
|
||||||
|
|
||||||
.wy-nav-content {
|
.wy-nav-content {
|
||||||
@@ -19,6 +11,31 @@
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/* Allow documentation tables to wrap long descriptions */
|
||||||
|
.wy-table-responsive table td,
|
||||||
|
.wy-table-responsive table th {
|
||||||
|
white-space: normal;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Keep cryptocurrency donation addresses compact and copyable */
|
||||||
|
.donation-address {
|
||||||
|
margin: .5em 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.donation-address summary {
|
||||||
|
cursor: pointer;
|
||||||
|
}
|
||||||
|
|
||||||
|
.donation-address code {
|
||||||
|
display: block;
|
||||||
|
margin-top: .5em;
|
||||||
|
overflow-wrap: anywhere;
|
||||||
|
padding: .5em;
|
||||||
|
user-select: all;
|
||||||
|
white-space: normal;
|
||||||
|
word-break: break-all;
|
||||||
|
}
|
||||||
|
|
||||||
/* Make <kbd> look like a key */
|
/* Make <kbd> look like a key */
|
||||||
kbd {
|
kbd {
|
||||||
background-color: #eee;
|
background-color: #eee;
|
||||||
@@ -32,3 +49,340 @@ kbd {
|
|||||||
padding: 2px 4px;
|
padding: 2px 4px;
|
||||||
white-space: nowrap;
|
white-space: nowrap;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/* Follow the system colour preference */
|
||||||
|
@media screen and (prefers-color-scheme: dark) {
|
||||||
|
html {
|
||||||
|
color-scheme: dark;
|
||||||
|
}
|
||||||
|
|
||||||
|
body,
|
||||||
|
.wy-body-for-nav,
|
||||||
|
.wy-nav-content-wrap {
|
||||||
|
background: #0d1117;
|
||||||
|
color: #c9d1d9;
|
||||||
|
}
|
||||||
|
|
||||||
|
.wy-nav-content {
|
||||||
|
background: #161b22;
|
||||||
|
}
|
||||||
|
|
||||||
|
h1,
|
||||||
|
h2,
|
||||||
|
h3,
|
||||||
|
h4,
|
||||||
|
h5,
|
||||||
|
h6,
|
||||||
|
.rst-content .toc-backref,
|
||||||
|
.rst-content code.xref,
|
||||||
|
.rst-content tt.xref {
|
||||||
|
color: #f0f6fc;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content a {
|
||||||
|
color: #58a6ff;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content a:visited {
|
||||||
|
color: #bc8cff;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content a:hover,
|
||||||
|
.rst-content a:focus {
|
||||||
|
color: #79c0ff;
|
||||||
|
}
|
||||||
|
|
||||||
|
hr {
|
||||||
|
border-color: #30363d;
|
||||||
|
}
|
||||||
|
|
||||||
|
footer,
|
||||||
|
.rst-content table.docutils.footnote,
|
||||||
|
html.writer-html4 .rst-content table.docutils.citation,
|
||||||
|
html.writer-html5 .rst-content aside.footnote,
|
||||||
|
html.writer-html5 .rst-content aside.footnote-list aside.footnote,
|
||||||
|
html.writer-html5 .rst-content div.citation-list > div.citation,
|
||||||
|
html.writer-html5 .rst-content dl.citation,
|
||||||
|
html.writer-html5 .rst-content dl.footnote {
|
||||||
|
color: #8b949e;
|
||||||
|
}
|
||||||
|
|
||||||
|
.btn-neutral,
|
||||||
|
.btn-neutral:visited {
|
||||||
|
background-color: #21262d !important;
|
||||||
|
color: #f0f6fc !important;
|
||||||
|
}
|
||||||
|
|
||||||
|
.btn-neutral:hover {
|
||||||
|
background-color: #30363d !important;
|
||||||
|
color: #fff !important;
|
||||||
|
}
|
||||||
|
|
||||||
|
label,
|
||||||
|
.wy-checkbox,
|
||||||
|
.wy-radio,
|
||||||
|
.wy-text-neutral {
|
||||||
|
color: #c9d1d9 !important;
|
||||||
|
}
|
||||||
|
|
||||||
|
input,
|
||||||
|
select,
|
||||||
|
textarea,
|
||||||
|
.wy-side-nav-search input[type="text"] {
|
||||||
|
background-color: #0d1117;
|
||||||
|
border-color: #484f58;
|
||||||
|
box-shadow: inset 0 1px 3px #010409;
|
||||||
|
color: #f0f6fc;
|
||||||
|
}
|
||||||
|
|
||||||
|
input[disabled],
|
||||||
|
input[readonly],
|
||||||
|
select[disabled],
|
||||||
|
select[readonly],
|
||||||
|
textarea[disabled],
|
||||||
|
textarea[readonly] {
|
||||||
|
background-color: #21262d !important;
|
||||||
|
color: #8b949e;
|
||||||
|
}
|
||||||
|
|
||||||
|
.wy-nav-side,
|
||||||
|
.wy-side-scroll {
|
||||||
|
background: #161b22;
|
||||||
|
}
|
||||||
|
|
||||||
|
.wy-menu-vertical li.current {
|
||||||
|
background: #21262d;
|
||||||
|
}
|
||||||
|
|
||||||
|
.wy-menu-vertical li.current a {
|
||||||
|
border-color: #30363d;
|
||||||
|
color: #c9d1d9;
|
||||||
|
}
|
||||||
|
|
||||||
|
.wy-menu-vertical li.current a:hover,
|
||||||
|
.wy-menu-vertical li.current > a,
|
||||||
|
.wy-menu-vertical li.on a,
|
||||||
|
.wy-menu-vertical li.current > a:hover,
|
||||||
|
.wy-menu-vertical li.on a:hover {
|
||||||
|
background: #30363d;
|
||||||
|
color: #f0f6fc;
|
||||||
|
}
|
||||||
|
|
||||||
|
.wy-menu-vertical li.toctree-l1.current > a {
|
||||||
|
border-color: #484f58;
|
||||||
|
}
|
||||||
|
|
||||||
|
.wy-menu-vertical li.toctree-l2.current > a,
|
||||||
|
.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a,
|
||||||
|
.wy-menu-vertical li.toctree-l3.current > a,
|
||||||
|
.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a {
|
||||||
|
background: #262c36;
|
||||||
|
color: #f0f6fc;
|
||||||
|
}
|
||||||
|
|
||||||
|
.wy-menu-vertical li.current > a button.toctree-expand,
|
||||||
|
.wy-menu-vertical li.on a button.toctree-expand,
|
||||||
|
.wy-menu-vertical li button.toctree-expand {
|
||||||
|
color: #8b949e;
|
||||||
|
}
|
||||||
|
|
||||||
|
.wy-dropdown-menu,
|
||||||
|
.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu {
|
||||||
|
background: #21262d;
|
||||||
|
border-color: #484f58;
|
||||||
|
}
|
||||||
|
|
||||||
|
.wy-dropdown-menu > dd > a {
|
||||||
|
color: #c9d1d9;
|
||||||
|
}
|
||||||
|
|
||||||
|
.wy-dropdown-menu > dd.call-to-action,
|
||||||
|
.wy-dropdown-menu > dd.call-to-action:hover {
|
||||||
|
background: #30363d;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content code,
|
||||||
|
.rst-content code.literal,
|
||||||
|
.rst-content tt,
|
||||||
|
code,
|
||||||
|
.donation-address code {
|
||||||
|
background: #0d1117;
|
||||||
|
border-color: #30363d;
|
||||||
|
color: #ff7b72;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content a code,
|
||||||
|
.rst-content a tt {
|
||||||
|
color: inherit;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content div[class^="highlight"],
|
||||||
|
.rst-content pre.literal-block {
|
||||||
|
background: #0d1117;
|
||||||
|
border-color: #30363d;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content div.highlight span.linenos {
|
||||||
|
border-color: #30363d;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content .admonition,
|
||||||
|
.rst-content .admonition-todo,
|
||||||
|
.rst-content .attention,
|
||||||
|
.rst-content .caution,
|
||||||
|
.rst-content .danger,
|
||||||
|
.rst-content .error,
|
||||||
|
.rst-content .hint,
|
||||||
|
.rst-content .important,
|
||||||
|
.rst-content .note,
|
||||||
|
.rst-content .seealso,
|
||||||
|
.rst-content .tip,
|
||||||
|
.rst-content .warning,
|
||||||
|
.wy-alert {
|
||||||
|
background: #21262d;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content .admonition-title,
|
||||||
|
.wy-alert-title {
|
||||||
|
background: #1f6feb;
|
||||||
|
color: #fff;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content .danger .admonition-title,
|
||||||
|
.rst-content .danger .wy-alert-title,
|
||||||
|
.rst-content .error .admonition-title,
|
||||||
|
.rst-content .error .wy-alert-title {
|
||||||
|
background: #b62324;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content .admonition-todo .admonition-title,
|
||||||
|
.rst-content .admonition-todo .wy-alert-title,
|
||||||
|
.rst-content .attention .admonition-title,
|
||||||
|
.rst-content .attention .wy-alert-title,
|
||||||
|
.rst-content .caution .admonition-title,
|
||||||
|
.rst-content .caution .wy-alert-title,
|
||||||
|
.rst-content .warning .admonition-title,
|
||||||
|
.rst-content .warning .wy-alert-title {
|
||||||
|
background: #9a6700;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content .hint .admonition-title,
|
||||||
|
.rst-content .hint .wy-alert-title,
|
||||||
|
.rst-content .important .admonition-title,
|
||||||
|
.rst-content .important .wy-alert-title,
|
||||||
|
.rst-content .tip .admonition-title,
|
||||||
|
.rst-content .tip .wy-alert-title {
|
||||||
|
background: #238636;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content .admonition table,
|
||||||
|
.rst-content .admonition table td,
|
||||||
|
.rst-content .admonition table th {
|
||||||
|
border-color: #484f58 !important;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content table.docutils caption,
|
||||||
|
.rst-content table.field-list caption,
|
||||||
|
.wy-table caption,
|
||||||
|
.rst-content table.docutils thead,
|
||||||
|
.rst-content table.field-list thead,
|
||||||
|
.wy-table thead {
|
||||||
|
color: #f0f6fc;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content table.docutils,
|
||||||
|
.rst-content table.docutils td,
|
||||||
|
.rst-content table.docutils th,
|
||||||
|
.wy-table-bordered,
|
||||||
|
.wy-table-bordered-all,
|
||||||
|
.wy-table-bordered-all td,
|
||||||
|
.wy-table-bordered-rows td,
|
||||||
|
.wy-table-horizontal td,
|
||||||
|
.wy-table-horizontal th,
|
||||||
|
html.writer-html5 .rst-content table.docutils th {
|
||||||
|
border-color: #30363d;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,
|
||||||
|
.wy-table-backed,
|
||||||
|
.wy-table-odd td,
|
||||||
|
.wy-table-striped tr:nth-child(2n-1) td {
|
||||||
|
background-color: #1c2128;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content .sidebar {
|
||||||
|
background: #21262d;
|
||||||
|
border-color: #30363d;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content .sidebar .sidebar-title {
|
||||||
|
background: #30363d;
|
||||||
|
}
|
||||||
|
|
||||||
|
#search-results .search li {
|
||||||
|
border-color: #30363d;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content .highlighted {
|
||||||
|
background: #9a6700;
|
||||||
|
box-shadow: 0 0 0 2px #9a6700;
|
||||||
|
color: #fff;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content .guilabel,
|
||||||
|
.rst-content .menuselection,
|
||||||
|
html.writer-html4 .rst-content dl:not(.docutils) > dt,
|
||||||
|
html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt {
|
||||||
|
background: #21262d;
|
||||||
|
border-color: #388bfd;
|
||||||
|
color: #79c0ff;
|
||||||
|
}
|
||||||
|
|
||||||
|
html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt,
|
||||||
|
html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt {
|
||||||
|
background: #1c2128;
|
||||||
|
border-color: #484f58;
|
||||||
|
color: #c9d1d9;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content dl dt .headerlink,
|
||||||
|
.rst-content .descclassname,
|
||||||
|
.rst-content .descname,
|
||||||
|
.rst-content .sig-name,
|
||||||
|
.rst-content .optional {
|
||||||
|
color: #f0f6fc !important;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content table.docutils.footnote code,
|
||||||
|
.rst-content table.docutils.footnote tt,
|
||||||
|
html.writer-html4 .rst-content table.docutils.citation code,
|
||||||
|
html.writer-html4 .rst-content table.docutils.citation tt,
|
||||||
|
html.writer-html5 .rst-content aside.footnote code,
|
||||||
|
html.writer-html5 .rst-content aside.footnote tt,
|
||||||
|
html.writer-html5 .rst-content div.citation-list > div.citation code,
|
||||||
|
html.writer-html5 .rst-content div.citation-list > div.citation tt,
|
||||||
|
html.writer-html5 .rst-content dl.citation code,
|
||||||
|
html.writer-html5 .rst-content dl.citation tt,
|
||||||
|
html.writer-html5 .rst-content dl.footnote code,
|
||||||
|
html.writer-html5 .rst-content dl.footnote tt {
|
||||||
|
color: #8b949e;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-content :not(dl.option-list) > :not(dt):not(kbd):not(.kbd) > .kbd,
|
||||||
|
.rst-content :not(dl.option-list) > :not(dt):not(kbd):not(.kbd) > kbd,
|
||||||
|
kbd {
|
||||||
|
background-color: #21262d;
|
||||||
|
border-color: #484f58;
|
||||||
|
box-shadow: 0 1px 0 #0d1117;
|
||||||
|
color: #f0f6fc;
|
||||||
|
}
|
||||||
|
|
||||||
|
span[id*="MathJax-Span"] {
|
||||||
|
color: #c9d1d9;
|
||||||
|
}
|
||||||
|
|
||||||
|
.breadcrumb-item:before,
|
||||||
|
.wy-breadcrumbs-extra {
|
||||||
|
color: #8b949e;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
95
doc/display.rst
Normal file
95
doc/display.rst
Normal file
@@ -0,0 +1,95 @@
|
|||||||
|
.. _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 <https://github.com/bloc97/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.
|
||||||
302
doc/faq.rst
302
doc/faq.rst
@@ -9,271 +9,183 @@ General
|
|||||||
How does Looking Glass work?
|
How does Looking Glass work?
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
This YouTube video featured created by the author features a detailed
|
The Windows IDD creates a virtual monitor and places completed frames in an
|
||||||
explanation:
|
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:
|
||||||
|
|
||||||
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
|
Yes. The :doc:`OBS plugin <obs>` is an independent frame consumer and does not
|
||||||
another Looking Glass client, but instead feeds the captured frames into OBS.
|
capture the client window.
|
||||||
|
|
||||||
.. _why_is_my_ups_so_low:
|
.. _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
|
UPS counts frames delivered to that consumer, not every frame Windows may
|
||||||
capture resolution, or refresh rate. The windows capture methods currently
|
render. The IDD publishes to the deadline requested by the fastest active
|
||||||
struggle to capture high resolutions under certain circumstances.
|
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
|
If UPS is below the active consumer's requested rate, use
|
||||||
capture performance issues. One such title is the Unigine Valley
|
:ref:`client_performance` to locate the slow stage. High resolution, software
|
||||||
benchmark where the capture rate is limited to 1/2 the actual rate. For
|
processing, memory bandwidth, host scheduling and compositor presentation can
|
||||||
an unknown reason to both myself and the Unigine developers a simple
|
all impose a lower limit.
|
||||||
task switch (alt+tab) in and out resolves the issue. This is not a
|
|
||||||
Looking Glass bug.
|
|
||||||
|
|
||||||
.. _is_my_gpu_supported:
|
.. _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
|
No. The IDD can create an SDR display using software processing when it cannot
|
||||||
that you have support for WDDM 1.2 or greater.
|
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,
|
The Linux client still needs an EGL-capable host graphics driver. Direct
|
||||||
unsupported device or driver" indicates NVidia duplication has failed,
|
DMA-BUF import depends on the host GPU and driver; the client falls back to a
|
||||||
not that DXGI has failed. You can fix the error by specifying
|
copy when it is unavailable.
|
||||||
``-c DXGI``
|
|
||||||
|
|
||||||
.. _why_do_i_need_spice_if_i_dont_want_a_spice_display_device:
|
.. _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
|
SPICE is not required for the primary IDD video or direct input paths. It is
|
||||||
built in to provide some conveniences, but you can disable it with the
|
still useful for clipboard, audio, input fallback and automatic video fallback.
|
||||||
"-s" argument.
|
These services are selected independently.
|
||||||
|
|
||||||
.. note::
|
Set ``spice:enable=no`` or use ``-s`` to disable SPICE completely. Disable an
|
||||||
|
individual service with ``spice:input``, ``spice:clipboard`` or
|
||||||
Without Spice, Looking Glass cannot send mouse/keyboard input to the guest
|
``spice:audio`` instead when the other services are still wanted.
|
||||||
and clipboard synchronization is disabled.
|
|
||||||
|
|
||||||
.. _where_is_the_host_application_for_linux:
|
.. _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
|
The Looking Glass Client runs on the Linux host operating system. The IDD runs
|
||||||
runs in the guest VM. The only thing that needs to run in your Linux
|
inside the Windows guest. The older product named the **Host Application** is
|
||||||
host OS is the ``looking-glass-client`` application.
|
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
|
Input and window system
|
||||||
well.
|
-----------------------
|
||||||
|
|
||||||
.. _gnome_wayland_decorations:
|
.. _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`_
|
GNOME does not implement the standard Wayland server-side decoration
|
||||||
for server-side decorations, and Looking Glass doesn't implement its own
|
protocol. Build Looking Glass with libdecor support:
|
||||||
decorations.
|
|
||||||
|
|
||||||
The easiest solution is to build Looking Glass with `libdecor`_ support.
|
.. code:: bash
|
||||||
Install the ``libdecor-0-dev`` package. If your distribution lacks this package
|
|
||||||
or any equivalents, you must build it from `source code <libdecor_>`_.
|
|
||||||
|
|
||||||
You can then build the the client with libdecor support by passing
|
cmake -DENABLE_LIBDECOR=ON ../
|
||||||
``-DENABLE_LIBDECOR=ON`` to ``cmake``.
|
|
||||||
|
|
||||||
An alternative solution is to hold down the Super key (Windows key on most
|
Install ``libdecor-0-dev`` first on Debian-based systems. Alternatively, hold
|
||||||
keyboards), then right click Looking Glass. This should bring up a menu,
|
the Super key and right-click the window to use the compositor's move and
|
||||||
which will allow you to move the window and resize it.
|
resize menu.
|
||||||
|
|
||||||
.. 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
|
|
||||||
-----
|
|
||||||
|
|
||||||
.. _the_mouse_is_jumpy_slow_laggy_when_using_spice:
|
.. _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
|
The IDD's direct input path uses absolute positioning for normal desktop use
|
||||||
https://www.spice-space.org/download.html#windows-binaries.
|
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:
|
Use the direct IDD input path when available. For a game, use capture mode and
|
||||||
|
consider ``input:rawMouse=yes``.
|
||||||
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)
|
|
||||||
|
|
||||||
.. _the_cursor_position_doesnt_update_until_i_click:
|
.. _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
|
No. Looking Glass does not require an additional virtio tablet, mouse or
|
||||||
Machine. Due to the design of Windows, absolute pointing devices break
|
keyboard. Direct IDD input provides its own absolute and relative devices, and
|
||||||
applications/games that require cursor capture, and as such Looking Glass
|
SPICE fallback uses the VM's default PS/2 input devices.
|
||||||
does not support them.
|
|
||||||
|
|
||||||
Audio
|
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:
|
The sections below apply only to the legacy Windows Host Application. New
|
||||||
|
installations should use the IDD. See :ref:`legacy_host_policy`.
|
||||||
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.
|
|
||||||
|
|
||||||
.. _faq_host:
|
.. _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
|
``%ProgramData%\Looking Glass (host)\looking-glass-host-service.txt``
|
||||||
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.
|
|
||||||
|
|
||||||
.. _faq_host_admin_privs:
|
.. _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
|
.. _nvfbc_nvidia_capture_api_doesnt_work:
|
||||||
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 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
|
.. _the_screen_stops_updating_when_left_idle_for_a_time:
|
||||||
by doing so you will be agreeing to NVIDIA's SDK License agreement.
|
|
||||||
|
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:
|
.. _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::
|
Do not use Scream with Looking Glass. Use the built-in classic SPICE or USB
|
||||||
Using IVSHMEM with Scream may interfere with Looking Glass, as they may try
|
audio path instead. In particular, Scream's IVSHMEM transport can select or
|
||||||
to use the same device.
|
interfere with the shared device used for Looking Glass frames.
|
||||||
|
|
||||||
Please do not use the IVSHMEM plugin for Scream.
|
Technical details
|
||||||
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.
|
|
||||||
|
|
||||||
If you insist on using IVSHMEM for Scream—despite its inferiority to the
|
.. toctree::
|
||||||
default network implementation—the Windows Host Application can be told
|
:maxdepth: 1
|
||||||
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
|
|
||||||
|
|
||||||
|
tech_faq
|
||||||
|
|||||||
89
doc/host_usage.rst
Normal file
89
doc/host_usage.rst
Normal file
@@ -0,0 +1,89 @@
|
|||||||
|
.. _host_usage:
|
||||||
|
|
||||||
|
Legacy Host 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.
|
||||||
87
doc/idd_configuration.rst
Normal file
87
doc/idd_configuration.rst
Normal file
@@ -0,0 +1,87 @@
|
|||||||
|
.. _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 **<add new>**, 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
|
||||||
|
producer 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.
|
||||||
71
doc/idd_diagnostics.rst
Normal file
71
doc/idd_diagnostics.rst
Normal file
@@ -0,0 +1,71 @@
|
|||||||
|
.. _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;
|
||||||
|
* ``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.
|
||||||
@@ -1,23 +1,25 @@
|
|||||||
Looking Glass |release| documentation
|
Looking Glass |release| documentation
|
||||||
=====================================
|
=====================================
|
||||||
|
|
||||||
Looking Glass is an open-source application that allows the use of a KVM
|
Looking Glass is an open-source, low-latency way to use a Windows virtual
|
||||||
(Kernel-based Virtual Machine) configured for VGA PCI Pass-through
|
machine from Linux. The current setup uses a virtual display in the Windows
|
||||||
without an attached physical monitor, keyboard or mouse. This is the
|
guest, shared memory for frames, and a native Linux client for display and
|
||||||
final step required to move away from dual booting with other operating
|
input.
|
||||||
systems for legacy programs that require high-performance graphics.
|
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
|
overview
|
||||||
requirements
|
requirements
|
||||||
|
quickstart
|
||||||
|
|
||||||
build
|
build
|
||||||
install
|
install
|
||||||
|
|
||||||
usage
|
usage
|
||||||
troubleshooting
|
troubleshooting
|
||||||
obs
|
obs
|
||||||
faq
|
faq
|
||||||
tech_faq
|
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:hidden:
|
:hidden:
|
||||||
@@ -39,6 +41,20 @@ Donate:
|
|||||||
* `Ko-Fi <https://ko-fi.com/lookingglass>`_
|
* `Ko-Fi <https://ko-fi.com/lookingglass>`_
|
||||||
* `Patreon <https://www.patreon.com/gnif>`_
|
* `Patreon <https://www.patreon.com/gnif>`_
|
||||||
* `PayPal <https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ESQ72XUPGKXRY>`_
|
* `PayPal <https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ESQ72XUPGKXRY>`_
|
||||||
* BTC - 14ZFcYjsKPiVreHqcaekvHGL846u3ZuT13
|
|
||||||
* ETH - 0x6f8aEe454384122bF9ed28f025FBCe2Bce98db85
|
Expand a cryptocurrency address to copy it:
|
||||||
* XMR - 47xM4zG7b2tEj4mnSywHve4ydZzn3wzhf22snDRB7aSEcXrgUBpoT2Z4phTnyFMi1sMyQtHbdufMYRQ2PzMn3PGUJAE1dpc
|
|
||||||
|
.. raw:: html
|
||||||
|
|
||||||
|
<details class="donation-address">
|
||||||
|
<summary>Bitcoin (BTC)</summary>
|
||||||
|
<code>14ZFcYjsKPiVreHqcaekvHGL846u3ZuT13</code>
|
||||||
|
</details>
|
||||||
|
<details class="donation-address">
|
||||||
|
<summary>Ethereum (ETH)</summary>
|
||||||
|
<code>0x6f8aEe454384122bF9ed28f025FBCe2Bce98db85</code>
|
||||||
|
</details>
|
||||||
|
<details class="donation-address">
|
||||||
|
<summary>Monero (XMR)</summary>
|
||||||
|
<code>47xM4zG7b2tEj4mnSywHve4ydZzn3wzhf22snDRB7aSEcXrgUBpoT2Z4phTnyFMi1sMyQtHbdufMYRQ2PzMn3PGUJAE1dpc</code>
|
||||||
|
</details>
|
||||||
|
|||||||
101
doc/input.rst
Normal file
101
doc/input.rst
Normal file
@@ -0,0 +1,101 @@
|
|||||||
|
.. _client_input:
|
||||||
|
|
||||||
|
Keyboard and mouse input
|
||||||
|
########################
|
||||||
|
|
||||||
|
The current IDD provides keyboard and mouse input directly over LGMP. It uses
|
||||||
|
absolute positioning for normal desktop use and relative movement in capture
|
||||||
|
mode. SPICE remains available as a fallback when direct input is unavailable.
|
||||||
|
|
||||||
|
The client changes input provider automatically. If the displayed video has
|
||||||
|
fallen back to SPICE, the client also uses SPICE input so that the picture and
|
||||||
|
pointer always refer to the same guest.
|
||||||
|
|
||||||
|
Only one LGMP client controls direct input at a time. Starting another client
|
||||||
|
does not give both clients simultaneous control. Disconnecting or restarting
|
||||||
|
the IDD releases held keys and buttons before ownership changes.
|
||||||
|
|
||||||
|
Normal input
|
||||||
|
------------
|
||||||
|
|
||||||
|
Move the pointer into the guest view to use absolute desktop input. This keeps
|
||||||
|
the guest pointer aligned without requiring capture.
|
||||||
|
|
||||||
|
Direct IDD input supports the keyboard, media keys and up to 32 mouse buttons.
|
||||||
|
SPICE fallback uses relative mouse input and supports fewer extra buttons.
|
||||||
|
|
||||||
|
Capture mode
|
||||||
|
------------
|
||||||
|
|
||||||
|
Press the escape key, :kbd:`ScrLk` by default, to capture the mouse. Capture
|
||||||
|
mode confines the pointer and sends relative motion, which is appropriate for
|
||||||
|
games and applications that lock the cursor. Press the escape key again to
|
||||||
|
leave capture mode.
|
||||||
|
|
||||||
|
Common capture options are:
|
||||||
|
|
||||||
|
``input:captureOnFocus``
|
||||||
|
Enter capture mode whenever the client receives focus.
|
||||||
|
|
||||||
|
``input:captureOnStart``
|
||||||
|
Start captured.
|
||||||
|
|
||||||
|
``input:captureOnly``
|
||||||
|
Disable guest input outside capture mode.
|
||||||
|
|
||||||
|
``input:rawMouse``
|
||||||
|
Use raw relative mouse input in capture mode. This is usually best for
|
||||||
|
games.
|
||||||
|
|
||||||
|
``input:mouseSens``
|
||||||
|
Adjust relative sensitivity from -9 to 9. The default is 0.
|
||||||
|
|
||||||
|
``input:hideCursor``
|
||||||
|
Hide the host cursor while Looking Glass renders the guest cursor.
|
||||||
|
|
||||||
|
Automatic keyboard capture
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
Set ``input:autoCapture=yes`` to grab the keyboard when the pointer enters the
|
||||||
|
guest view. Looking Glass predicts when the next mouse movement would leave
|
||||||
|
the guest area and releases the keyboard before that movement. This makes it
|
||||||
|
possible to move naturally between Looking Glass and the Linux desktop without
|
||||||
|
using the escape key for the keyboard.
|
||||||
|
|
||||||
|
Automatic keyboard capture is disabled by ``input:captureOnly=yes``. It also
|
||||||
|
keeps the keyboard grabbed while a mouse button is held so that dragging does
|
||||||
|
not unexpectedly leave the guest.
|
||||||
|
|
||||||
|
This is separate from full mouse capture: the pointer remains in normal
|
||||||
|
absolute mode. Use regular capture mode when an application requires relative
|
||||||
|
mouse input.
|
||||||
|
|
||||||
|
``input:grabKeyboardOnFocus`` instead keeps the keyboard grabbed while the
|
||||||
|
guest view is active. ``input:grabKeyboard`` controls whether full capture
|
||||||
|
mode grabs the keyboard.
|
||||||
|
|
||||||
|
SPICE fallback
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Keep ``spice:input=yes`` when SPICE input fallback is wanted. It uses the VM's
|
||||||
|
default PS/2 keyboard and mouse, so no additional virtio input devices or
|
||||||
|
tablet are required.
|
||||||
|
|
||||||
|
To disable all SPICE input while keeping SPICE audio or clipboard services:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[spice]
|
||||||
|
input=no
|
||||||
|
|
||||||
|
If direct input is also unavailable, the client will display video without
|
||||||
|
being able to control the guest.
|
||||||
|
|
||||||
|
Evdev capture
|
||||||
|
-------------
|
||||||
|
|
||||||
|
Advanced users may list Linux evdev devices in ``input:evdev``. They become
|
||||||
|
active whenever Looking Glass grabs the keyboard, including capture mode and
|
||||||
|
automatic keyboard capture. The client user must be allowed to read those
|
||||||
|
devices. Keep ``input:evdevExclusive=yes`` unless duplicate input from the
|
||||||
|
window system is specifically required.
|
||||||
@@ -3,8 +3,16 @@
|
|||||||
Installation
|
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 producers.
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
|
|
||||||
install_libvirt
|
install_libvirt
|
||||||
install_host
|
install_idd
|
||||||
install_client
|
install_client
|
||||||
|
install_host
|
||||||
|
|||||||
@@ -8,15 +8,21 @@ Client Application Installation
|
|||||||
For Linux
|
For Linux
|
||||||
---------
|
---------
|
||||||
|
|
||||||
The Looking Glass client receives frames from the :ref:`host <host_install>` to
|
The Looking Glass Client receives frames from the Windows producer and displays
|
||||||
display on your screen. It also handles input, and can optionally share the
|
them on Linux. It also handles input, audio, overlays and optional SPICE
|
||||||
system clipboard with your guest OS through SPICE.
|
services.
|
||||||
|
|
||||||
First you must build the client from source, see :ref:`building`. Once you have
|
There are currently no Linux distribution packages for the client. First
|
||||||
built the client, you can install it. Run the following as root::
|
:ref:`build it from source <build_client_section>`, then run the following from
|
||||||
|
the client build directory as root::
|
||||||
|
|
||||||
make install
|
make install
|
||||||
|
|
||||||
To install for the local user only, run::
|
To install for the current user only, configure the build with a user-local
|
||||||
|
prefix before installing::
|
||||||
|
|
||||||
cmake -DCMAKE_INSTALL_PREFIX=~/.local .. && make install
|
cmake -DCMAKE_INSTALL_PREFIX="$HOME/.local" ..
|
||||||
|
make install
|
||||||
|
|
||||||
|
Ensure ``$HOME/.local/bin`` is in your ``PATH`` when using the user-local
|
||||||
|
installation.
|
||||||
|
|||||||
@@ -1,17 +1,26 @@
|
|||||||
.. _installing_host:
|
.. _installing_host:
|
||||||
|
.. _host_install:
|
||||||
|
|
||||||
Host Application Installation
|
Legacy Host Application installation
|
||||||
#############################
|
####################################
|
||||||
|
|
||||||
The Looking Glass Host application captures frames from the guest OS using a
|
.. warning::
|
||||||
|
|
||||||
|
The Host Application is a legacy frame producer. New installations should
|
||||||
|
use the :doc:`Looking Glass IDD <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.
|
||||||
|
|
||||||
|
The legacy Looking Glass Host Application captures frames from the guest using a
|
||||||
capture API, and sends them to the
|
capture API, and sends them to the
|
||||||
:ref:`client <client_install>`—be it on the host OS (hypervisor) or another
|
:ref:`client <client_install>`—be it on the host OS (hypervisor) or another
|
||||||
Virtual Machine—through a low-latency transfer protocol over shared memory.
|
Virtual Machine—through a low-latency transfer protocol over shared memory.
|
||||||
|
|
||||||
You can get the host program in two ways:
|
You can get the host program in two ways:
|
||||||
|
|
||||||
- Download a pre-built binary from https://looking-glass.io/downloads
|
- Download a matching legacy binary from https://looking-glass.io/downloads
|
||||||
(**Recommended**)
|
|
||||||
|
|
||||||
- Download the source code as described in :ref:`building`, then
|
- Download the source code as described in :ref:`building`, then
|
||||||
:ref:`build the host <host_building>`.
|
:ref:`build the host <host_building>`.
|
||||||
@@ -79,3 +88,11 @@ Command line users can run ``looking-glass-host-setup.exe /S`` to execute a
|
|||||||
silent install with default options selected. Further configuration from the
|
silent install with default options selected. Further configuration from the
|
||||||
command line can be done with flags. You can list all available flags by
|
command line can be done with flags. You can list all available flags by
|
||||||
running ``looking-glass-host-setup.exe /?``.
|
running ``looking-glass-host-setup.exe /?``.
|
||||||
|
|
||||||
|
Legacy configuration
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
host_usage
|
||||||
|
|||||||
85
doc/install_idd.rst
Normal file
85
doc/install_idd.rst
Normal file
@@ -0,0 +1,85 @@
|
|||||||
|
.. _installing_idd:
|
||||||
|
|
||||||
|
Looking Glass IDD
|
||||||
|
#################
|
||||||
|
|
||||||
|
.. _install_idd:
|
||||||
|
|
||||||
|
The Looking Glass IDD is the recommended Windows frame producer. 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 producer 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 producers
|
||||||
|
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.
|
||||||
@@ -3,85 +3,64 @@
|
|||||||
libvirt/QEMU Installation
|
libvirt/QEMU Installation
|
||||||
#########################
|
#########################
|
||||||
|
|
||||||
This article assumes you already have a fully functional `libvirt` domain with
|
This article assumes you already have a working `libvirt` Windows virtual
|
||||||
PCI passthrough working. If you use `virt-manager`, this guide also applies to
|
machine. If you use `virt-manager`, this guide also applies because
|
||||||
you, since virt-manager uses `libvirt` as its back end.
|
`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:
|
.. _libvirt_determining_memory:
|
||||||
|
|
||||||
Determining memory
|
Determining memory
|
||||||
^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
You will first need to calculate the memory size to be suitable for your desired
|
Calculate the base IVSHMEM requirement as:
|
||||||
maximum resolution using the following formula:
|
|
||||||
|
|
||||||
.. math::
|
.. math::
|
||||||
|
|
||||||
\text{WIDTH} \times \text{HEIGHT} \times \text{BPP} \times 2 = \text{frame size in bytes}
|
\text{BASE SIZE} =
|
||||||
|
\left(\left\lceil\frac{\text{WIDTH} \times 4}{256}\right\rceil
|
||||||
|
\times 256\right) \times \text{HEIGHT} \times 3
|
||||||
|
|
||||||
\text{frame size in bytes} \div 1024 \div 1024 = \text{ frame size in MiB}
|
Additional shared memory is required for protocol metadata and alignment. The
|
||||||
|
values below include that requirement and are rounded up to a power of two.
|
||||||
|
|
||||||
\text{frame size in MiB} + 10 = \text{ required size in 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
|
||||||
2^{\lceil \log_2(\text {required size in MiB}) \rceil} = \text{ total MiB}
|
and reports the minimum power-of-two size to configure. The current IDD does
|
||||||
|
not publish a truncated frame.
|
||||||
Where `BPP` is 4 for 32-bit RGB (SDR) or 8 for 64-bit
|
|
||||||
(HDR :ref:`* <libvirt_determining_memory_hdr>`).
|
|
||||||
|
|
||||||
.. hint::
|
|
||||||
The final step in this calculation is simply rounding the value up to the
|
|
||||||
nearest power of two.
|
|
||||||
|
|
||||||
For example, for a resolution of 1920x1080 (1080p) SDR:
|
|
||||||
|
|
||||||
.. math::
|
|
||||||
|
|
||||||
1920 \times 1080 \times 4 \times 2 = 16,588,800 \text{ bytes}
|
|
||||||
|
|
||||||
16,588,800 \div 1024 \div 1024 = 15.82 \text{ MiB}
|
|
||||||
|
|
||||||
15.82 \text{ MiB} + 10 \text{ MiB} = 25.82 \text{ MiB}
|
|
||||||
|
|
||||||
2^{\lceil \log_2(25.82) \rceil} = 32 \text { MiB}
|
|
||||||
|
|
||||||
|
|
||||||
Failure to provide enough memory will cause Looking Glass to truncate the
|
|
||||||
bottom of the screen and will trigger a message popup to inform you of the size
|
|
||||||
you need to increase the value to.
|
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
Increasing this value beyond what you need does not yield any performance
|
Increasing this value beyond what you need does not improve performance. It
|
||||||
improvements, it simply will block access to that RAM making it unusable by
|
only reserves more host RAM for the VM.
|
||||||
your system.
|
|
||||||
|
|
||||||
.. list-table:: Common Values
|
.. list-table:: Common IDD values
|
||||||
:widths: 50 25 25
|
:widths: 60 40
|
||||||
:header-rows: 1
|
:header-rows: 1
|
||||||
|
|
||||||
* - Resolution
|
* - Maximum resolution
|
||||||
- Standard Dynamic Range
|
- Total IVSHMEM size (MiB)
|
||||||
- High Dynamic Range (HDR) :ref:`* <libvirt_determining_memory_hdr>`
|
* - 1920x1080 (1080p)
|
||||||
* - 1920x1080 (1080p)
|
- 64
|
||||||
- 32
|
* - 1920x1200
|
||||||
- 64
|
- 64
|
||||||
* - 1920x1200 (1200p)
|
* - 2560x1440 (1440p)
|
||||||
- 32
|
- 128
|
||||||
- 64
|
* - 3440x1440
|
||||||
* - 2560x1440 (1440p)
|
- 128
|
||||||
- 64
|
* - 3840x2160 (4K)
|
||||||
- 128
|
- 256
|
||||||
* - 3840x2160 (2160p/4K)
|
* - 5120x1440
|
||||||
- 128
|
- 128
|
||||||
- 256
|
* - 5120x2880 (5K)
|
||||||
|
- 256
|
||||||
|
* - 7680x4320 (8K)
|
||||||
|
- 512
|
||||||
|
|
||||||
.. _libvirt_determining_memory_hdr:
|
.. _libvirt_determining_memory_hdr:
|
||||||
|
|
||||||
.. warning::
|
HDR uses the same 32-bit IDD transport allocation as SDR, so it does not double
|
||||||
While Looking Glass can capture and display HDR, at the time of writing
|
the IVSHMEM requirement. Native Linux HDR presentation has separate compositor
|
||||||
neither Xorg or Wayland can make use of it and it will be converted by the
|
and display requirements; see :ref:`client_hdr`.
|
||||||
GPU drivers/hardware to SDR. Additionally using HDR doubles the amount of
|
|
||||||
memory, bandwidth, and CPU load and as such should generally not be used
|
|
||||||
unless you have a special reason to do so.
|
|
||||||
|
|
||||||
.. _libvirt_ivshmem:
|
.. _libvirt_ivshmem:
|
||||||
|
|
||||||
@@ -95,7 +74,7 @@ Looking Glass to use your GPUs DMA engine to transfer the frame data.
|
|||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
ivshmem_kvmfr
|
ivshmem_kvmfr
|
||||||
ivshmem_shm
|
ivshmem_shm
|
||||||
|
|
||||||
@@ -109,36 +88,24 @@ Looking Glass to use your GPUs DMA engine to transfer the frame data.
|
|||||||
Keyboard/mouse/display/audio
|
Keyboard/mouse/display/audio
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Looking Glass makes use of the SPICE protocol to provide keyboard and mouse
|
The IDD provides the primary video, keyboard and mouse paths directly over
|
||||||
input, audio input and output, and display fallback.
|
LGMP. SPICE is optional, but is recommended for display fallback, clipboard
|
||||||
|
and audio services.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
The default configuration that libvirt uses is not optimal and must be
|
The current client owns its SPICE connection and service settings. The
|
||||||
adjusted. Failure to perform these changes will cause input issues along
|
canonical options are ``spice:enable``, ``spice:input``,
|
||||||
with failure to support 5 button mice.
|
``spice:clipboard``, ``spice:audio`` and ``spice:usbAudio``.
|
||||||
|
|
||||||
If you would like to use SPICE to give you keyboard and mouse input
|
Keep a ``<graphics type='spice'>`` device if you want these services. For a
|
||||||
along with clipboard sync support, make sure you have a
|
usable display fallback, set the VM's ``<video>`` model to ``vga``.
|
||||||
``<graphics type='spice'>`` device, then:
|
|
||||||
|
|
||||||
- Find your ``<video>`` device, and set ``<model type='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.
|
||||||
|
|
||||||
- If you can't find it, make sure you have a ``<graphics>``
|
For classic SPICE audio, add a standard Intel HDA audio device:
|
||||||
device, save and edit again.
|
|
||||||
|
|
||||||
- Remove the ``<input type='tablet'/>`` device, if you have one.
|
|
||||||
- Create an ``<input type='mouse' bus='virtio'/>`` device, if you don't
|
|
||||||
already have one.
|
|
||||||
- Create an ``<input type='keyboard' bus='virtio'/>`` device to improve
|
|
||||||
keyboard usage.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
Be sure to install the the *vioinput* driver from
|
|
||||||
`virtio-win <https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/>`_
|
|
||||||
in the guest
|
|
||||||
|
|
||||||
To enable audio support add a standard Intel HDA audio device to your
|
|
||||||
configuration as per below:
|
|
||||||
|
|
||||||
.. code:: xml
|
.. code:: xml
|
||||||
|
|
||||||
@@ -147,8 +114,10 @@ configuration as per below:
|
|||||||
</sound>
|
</sound>
|
||||||
<audio id='1' type='spice'/>
|
<audio id='1' type='spice'/>
|
||||||
|
|
||||||
If you also want clipboard synchronization please see
|
The recommended emulated USB audio path does not need this HDA device. It
|
||||||
:ref:`libvirt_clipboard_synchronization`
|
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:
|
.. _libvirt_clipboard_synchronization:
|
||||||
|
|
||||||
@@ -191,7 +160,7 @@ need to add permissions for QEMU to access the shared memory file. This
|
|||||||
can be done by adding the following to
|
can be done by adding the following to
|
||||||
``/etc/apparmor.d/local/abstractions/libvirt-qemu``::
|
``/etc/apparmor.d/local/abstractions/libvirt-qemu``::
|
||||||
|
|
||||||
/dev/shm/looking-glass rw,
|
/dev/shm/looking-glass rw,
|
||||||
|
|
||||||
then, restart AppArmor.
|
then, restart AppArmor.
|
||||||
|
|
||||||
@@ -217,7 +186,7 @@ Find the ``<memballoon>`` tag and set its type to ``none``:
|
|||||||
|
|
||||||
<memballoon model="none"/>
|
<memballoon model="none"/>
|
||||||
|
|
||||||
.. _host_install:
|
.. _libvirt_additional_tuning:
|
||||||
|
|
||||||
Additional tuning
|
Additional tuning
|
||||||
^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^
|
||||||
|
|||||||
@@ -4,8 +4,8 @@
|
|||||||
IVSHMEM with the KVMFR module (Recommended)
|
IVSHMEM with the KVMFR module (Recommended)
|
||||||
###########################################
|
###########################################
|
||||||
|
|
||||||
The kernel module implements a basic interface to the IVSHMEM device
|
The kernel module exposes IVSHMEM to Looking Glass and can export its frame
|
||||||
for Looking Glass allowing DMA GPU transfers.
|
buffers for direct GPU import.
|
||||||
|
|
||||||
.. _ivshmem_kvmfr_prereq:
|
.. _ivshmem_kvmfr_prereq:
|
||||||
|
|
||||||
@@ -47,14 +47,14 @@ Using the value you should have already calculated as per
|
|||||||
|
|
||||||
.. code:: bash
|
.. code:: bash
|
||||||
|
|
||||||
modprobe kvmfr static_size_mb=32
|
modprobe kvmfr static_size_mb=64
|
||||||
|
|
||||||
Alternatively you can make this setting permanent by creating the file
|
Alternatively you can make this setting permanent by creating the file
|
||||||
``/etc/modprobe.d/kvmfr.conf`` with the following content.
|
``/etc/modprobe.d/kvmfr.conf`` with the following content.
|
||||||
|
|
||||||
.. code:: text
|
.. code:: text
|
||||||
|
|
||||||
options kvmfr static_size_mb=32
|
options kvmfr static_size_mb=64
|
||||||
|
|
||||||
After this has been done, simply running ``modprobe kvmfr`` is all that is
|
After this has been done, simply running ``modprobe kvmfr`` is all that is
|
||||||
required.
|
required.
|
||||||
@@ -102,9 +102,11 @@ You should now also have the character device ``/dev/kvmfr0``
|
|||||||
|
|
||||||
If you start the VM prior to loading the module, QEMU will create the file
|
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
|
``/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 then
|
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
|
zero, or the permissions do not start with ``c``. If this has occurred, you
|
||||||
must delete the file and reload the module.
|
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.
|
||||||
|
|
||||||
.. _ivhsmem_kvmfr_permissions:
|
.. _ivhsmem_kvmfr_permissions:
|
||||||
|
|
||||||
@@ -165,7 +167,7 @@ should use this XML block to configure their VM for kvmfr:
|
|||||||
<qemu:arg value="-device"/>
|
<qemu:arg value="-device"/>
|
||||||
<qemu:arg value="{'driver':'ivshmem-plain','id':'shmem0','memdev':'looking-glass'}"/>
|
<qemu:arg value="{'driver':'ivshmem-plain','id':'shmem0','memdev':'looking-glass'}"/>
|
||||||
<qemu:arg value="-object"/>
|
<qemu:arg value="-object"/>
|
||||||
<qemu:arg value="{'qom-type':'memory-backend-file','id':'looking-glass','mem-path':'/dev/kvmfr0','size':33554432,'share':true}"/>
|
<qemu:arg value="{'qom-type':'memory-backend-file','id':'looking-glass','mem-path':'/dev/kvmfr0','size':67108864,'share':true}"/>
|
||||||
</qemu:commandline>
|
</qemu:commandline>
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
@@ -186,7 +188,7 @@ legacy syntax for IVSHMEM setup:
|
|||||||
<qemu:arg value="-device"/>
|
<qemu:arg value="-device"/>
|
||||||
<qemu:arg value="ivshmem-plain,id=shmem0,memdev=looking-glass"/>
|
<qemu:arg value="ivshmem-plain,id=shmem0,memdev=looking-glass"/>
|
||||||
<qemu:arg value="-object"/>
|
<qemu:arg value="-object"/>
|
||||||
<qemu:arg value="memory-backend-file,id=looking-glass,mem-path=/dev/kvmfr0,size=32M,share=yes"/>
|
<qemu:arg value="memory-backend-file,id=looking-glass,mem-path=/dev/kvmfr0,size=64M,share=yes"/>
|
||||||
</qemu:commandline>
|
</qemu:commandline>
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
@@ -218,9 +220,9 @@ and add the following:
|
|||||||
cgroups
|
cgroups
|
||||||
^^^^^^^
|
^^^^^^^
|
||||||
|
|
||||||
Edit the file ``/etc/libvirt/qemu.conf`` and uncomment the ``cgroup_device_acl``
|
Edit the file ``/etc/libvirt/qemu.conf`` and uncomment the
|
||||||
block, adding ``/dev/kvmfr0`` to the list. To make this change active you then
|
``cgroup_device_acl`` block, adding ``/dev/kvmfr0`` to the list. Restart
|
||||||
must restart ``libvirtd``
|
``libvirtd`` to apply it:
|
||||||
|
|
||||||
.. code:: bash
|
.. code:: bash
|
||||||
|
|
||||||
@@ -235,10 +237,9 @@ If you are using QEMU directly without libvirt, add the following arguments to y
|
|||||||
``qemu`` command line::
|
``qemu`` command line::
|
||||||
|
|
||||||
-device ivshmem-plain,id=shmem0,memdev=looking-glass
|
-device ivshmem-plain,id=shmem0,memdev=looking-glass
|
||||||
-object memory-backend-file,id=looking-glass,mem-path=/dev/kvmfr0,size=32M,share=yes
|
-object memory-backend-file,id=looking-glass,mem-path=/dev/kvmfr0,size=64M,share=yes
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
The ``size`` argument must be the same size you passed
|
The ``size`` argument must be the same size you passed
|
||||||
to the ``static_size_mb`` argument when loading the kernel module.
|
to the ``static_size_mb`` argument when loading the kernel module.
|
||||||
|
|
||||||
|
|||||||
@@ -4,9 +4,9 @@
|
|||||||
IVSHMEM with standard shared memory
|
IVSHMEM with standard shared memory
|
||||||
###################################
|
###################################
|
||||||
|
|
||||||
This method is here for those that can not use the KVMFR kernel module. Please
|
Use this method only when the KVMFR kernel module is unavailable. A standard
|
||||||
be aware that as a result you will not be able to take advantage of your GPUs
|
shared-memory file cannot provide KVMFR's DMA-BUF export, so the client must
|
||||||
ability to access memory via it's hardware DMA engine if you use this method.
|
copy the frame before uploading it to the host GPU.
|
||||||
|
|
||||||
Add the following to your libvirt machine configuration inside the
|
Add the following to your libvirt machine configuration inside the
|
||||||
'devices' section by running ``virsh edit <VM>`` where ``<VM>`` is the name of
|
'devices' section by running ``virsh edit <VM>`` where ``<VM>`` is the name of
|
||||||
@@ -16,7 +16,7 @@ your virtual machine.
|
|||||||
|
|
||||||
<shmem name='looking-glass'>
|
<shmem name='looking-glass'>
|
||||||
<model type='ivshmem-plain'/>
|
<model type='ivshmem-plain'/>
|
||||||
<size unit='M'>32</size>
|
<size unit='M'>64</size>
|
||||||
</shmem>
|
</shmem>
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
@@ -29,18 +29,16 @@ your virtual machine.
|
|||||||
.. code:: bash
|
.. code:: bash
|
||||||
|
|
||||||
-device ivshmem-plain,memdev=ivshmem,bus=pcie.0 \
|
-device ivshmem-plain,memdev=ivshmem,bus=pcie.0 \
|
||||||
-object memory-backend-file,id=ivshmem,share=on,mem-path=/dev/shm/looking-glass,size=32M
|
-object memory-backend-file,id=ivshmem,share=on,mem-path=/dev/shm/looking-glass,size=64M
|
||||||
|
|
||||||
The memory size (show as 32 in the example above) may need to be
|
The example uses 64 MiB. Replace it with the value from
|
||||||
adjusted as per the :ref:`Determining memory <libvirt_determining_memory>`
|
:ref:`Determining memory <libvirt_determining_memory>` when using a larger
|
||||||
section.
|
resolution.
|
||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
If you change the size of this after starting your virtual machine you may
|
Stop the VM before changing this size. You may need to remove the existing
|
||||||
need to remove the file `/dev/shm/looking-glass` to allow QEMU to re-create
|
``/dev/shm/looking-glass`` file so QEMU can recreate it at the new size.
|
||||||
it with the correct size. If you do this the permissions of the file may be
|
Check its permissions afterward; see :ref:`libvirt_shmfile_permissions`.
|
||||||
incorrect for your user to be able to access it and you will need to correct
|
|
||||||
this. See :ref:`libvirt_shmfile_permissions`
|
|
||||||
|
|
||||||
.. _libvirt_shmfile_permissions:
|
.. _libvirt_shmfile_permissions:
|
||||||
|
|
||||||
|
|||||||
177
doc/obs.rst
177
doc/obs.rst
@@ -1,105 +1,120 @@
|
|||||||
|
.. _obs_plugin:
|
||||||
|
.. _open_broadcaster_software:
|
||||||
|
|
||||||
OBS plugin
|
OBS plugin
|
||||||
##########
|
##########
|
||||||
|
|
||||||
You can add a Looking Glass video feed
|
The Looking Glass OBS plugin reads video from LGMP directly instead of
|
||||||
to OBS as a video source with the included OBS plugin. This provides a
|
capturing the client window. The client can stay hidden or show overlays
|
||||||
lower-latency alternative to capturing the Looking Glass client window
|
without adding them to the OBS source. This source does not provide audio or
|
||||||
with a Screen or Window Capture source.
|
input; add the required audio source separately in OBS.
|
||||||
|
|
||||||
This may help improve your viewers' watching experience, and
|
|
||||||
allows you to use your host privately.
|
|
||||||
|
|
||||||
Build instructions
|
|
||||||
~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The OBS plugin is included in the main source tree of Looking Glass. The
|
|
||||||
building process is very similar to the
|
|
||||||
:ref:`client's <build_client_section>`.
|
|
||||||
|
|
||||||
Dependencies
|
|
||||||
^^^^^^^^^^^^
|
|
||||||
|
|
||||||
The OBS plugin requires the following extra dependencies alongside the
|
|
||||||
:ref:`client's build
|
|
||||||
dependencies <installing_build_dependencies>`.
|
|
||||||
|
|
||||||
- ``libobs-dev``
|
|
||||||
|
|
||||||
Install this package with ``apt-get``
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
apt-get install libobs-dev
|
|
||||||
|
|
||||||
|
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
|
||||||
|
connect.
|
||||||
|
|
||||||
.. _obs_building:
|
.. _obs_building:
|
||||||
|
|
||||||
Building
|
Build and install
|
||||||
^^^^^^^^
|
-----------------
|
||||||
|
|
||||||
These instructions are similar to building the
|
On Debian-based systems, install the OBS headers and the small set of build
|
||||||
:ref:`client <client_building>`.
|
dependencies used by the plugin:
|
||||||
|
|
||||||
.. code:: bash
|
.. code:: bash
|
||||||
|
|
||||||
mkdir obs/build
|
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.
|
||||||
|
|
||||||
|
From the Looking Glass source directory, build the plugin for the current
|
||||||
|
user:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
mkdir -p obs/build
|
||||||
cd obs/build
|
cd obs/build
|
||||||
cmake -DUSER_INSTALL=1 ../
|
cmake -DUSER_INSTALL=1 ../
|
||||||
make
|
make
|
||||||
|
|
||||||
Alternatively, if you would like to install the plugin for all users:
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
mkdir obs/build
|
|
||||||
cd obs/build
|
|
||||||
cmake ../
|
|
||||||
make
|
|
||||||
|
|
||||||
Installation
|
|
||||||
~~~~~~~~~~~~
|
|
||||||
|
|
||||||
You can install the plugin by running ``make install``.
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
make install
|
make install
|
||||||
|
|
||||||
If you've opted to install the plugin for all users, you will need to run
|
For a system-wide installation, omit ``-DUSER_INSTALL=1`` and run
|
||||||
this command as ``root``.
|
``sudo make install``.
|
||||||
|
|
||||||
.. code:: bash
|
Add the source
|
||||||
|
--------------
|
||||||
|
|
||||||
sudo make install
|
1. Start OBS after installing the plugin.
|
||||||
|
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.
|
||||||
|
5. Leave **Use DMABUF import** enabled with KVMFR unless the OBS log reports
|
||||||
|
that the host graphics driver cannot import it.
|
||||||
|
|
||||||
Setup
|
The OBS process needs read and write access to ``/dev/kvmfr0``. Use the same
|
||||||
~~~~~
|
udev rule as the Looking Glass client; see :ref:`ivhsmem_kvmfr_permissions`.
|
||||||
|
|
||||||
Once installed, you can select the *"Looking Glass Client"* source from
|
|
||||||
the OBS sources menu. Configuration requires the IVSHMEM file
|
|
||||||
used by the VM, and this is pre-populated with the default
|
|
||||||
filename for Looking Glass.
|
|
||||||
|
|
||||||
.. _open_broadcaster_software:
|
|
||||||
|
|
||||||
|
|
||||||
Open Broadcaster Software
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The plugin is made for OBS, an open source streaming and recording
|
|
||||||
studio. Find out more at https://obsproject.com/
|
|
||||||
|
|
||||||
OBS is available under most distributions as *obs-studio* or just *obs*.
|
|
||||||
|
|
||||||
Screenshots
|
|
||||||
~~~~~~~~~~~
|
|
||||||
|
|
||||||
.. figure:: images/Looking-Glass-OBS-Source-Add.png
|
.. figure:: images/Looking-Glass-OBS-Source-Add.png
|
||||||
:alt: Adding the plugin as a video source
|
:alt: Adding a Looking Glass source in OBS
|
||||||
|
|
||||||
Adding the plugin as a video source
|
Adding the Looking Glass source
|
||||||
|
|
||||||
.. figure:: images/Looking-Glass-OBS-config.png
|
DMA-BUF and CPU copy
|
||||||
:alt: Plugin configuration settings
|
--------------------
|
||||||
|
|
||||||
Plugin configuration settings
|
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.
|
||||||
|
|
||||||
|
Disabling DMA-BUF is useful for diagnosis, but it increases CPU and memory
|
||||||
|
bandwidth use at high resolutions.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Frame rate and multiple clients
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
An active OBS source requests the global frame rate configured under **OBS
|
||||||
|
Settings > Video**. There is no separate FPS control in the Looking Glass
|
||||||
|
source. The IDD uses the fastest request among all active consumers, so a 120
|
||||||
|
Hz client can raise the producer cadence while OBS records at 60 FPS. Each
|
||||||
|
consumer still selects the newest frame for its own deadline.
|
||||||
|
|
||||||
|
The OBS source releases its cadence request while it is inactive or hidden.
|
||||||
|
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.
|
||||||
|
|
||||||
|
Troubleshooting
|
||||||
|
---------------
|
||||||
|
|
||||||
|
No source image
|
||||||
|
Check KVMFR permissions, the selected device and component versions. The
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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``.
|
||||||
|
|||||||
184
doc/options.rst
Normal file
184
doc/options.rst
Normal file
@@ -0,0 +1,184 @@
|
|||||||
|
.. _client_options:
|
||||||
|
.. _client_cli_options:
|
||||||
|
.. _client_full_command_options:
|
||||||
|
|
||||||
|
Client option reference
|
||||||
|
#######################
|
||||||
|
|
||||||
|
The exact option set depends on how the client was built. Use this command for
|
||||||
|
the complete reference, including defaults and short forms:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
looking-glass-client --help
|
||||||
|
|
||||||
|
Use only the canonical names shown by that command. Older configuration names
|
||||||
|
may remain as compatibility aliases, but they print a warning and can be
|
||||||
|
removed in a later release.
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
Long options use ``section:name=value``:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
looking-glass-client win:fullScreen=yes lgmp:allowDMA=no
|
||||||
|
|
||||||
|
Short options may take a separate argument:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
looking-glass-client -F -f /dev/kvmfr1
|
||||||
|
|
||||||
|
Configuration files use the section as an INI heading:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[win]
|
||||||
|
fullScreen=yes
|
||||||
|
|
||||||
|
[lgmp]
|
||||||
|
allowDMA=no
|
||||||
|
|
||||||
|
Common options
|
||||||
|
--------------
|
||||||
|
|
||||||
|
.. list-table:: Application and transport
|
||||||
|
:widths: 34 16 50
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - Option
|
||||||
|
- Default
|
||||||
|
- Purpose
|
||||||
|
* - ``app:transport``
|
||||||
|
- ``lgmp``
|
||||||
|
- Select the primary transport, normally ``lgmp`` or ``spice``
|
||||||
|
* - ``lgmp:shmDevice``
|
||||||
|
- automatic
|
||||||
|
- Select the KVMFR device or shared-memory file
|
||||||
|
* - ``lgmp:allowDMA``
|
||||||
|
- ``yes``
|
||||||
|
- Permit direct GPU imports when supported
|
||||||
|
* - ``spice:enable``
|
||||||
|
- ``yes``
|
||||||
|
- Enable the built-in SPICE transport and fallback services
|
||||||
|
* - ``spice:host``
|
||||||
|
- ``127.0.0.1``
|
||||||
|
- Set the SPICE server address or Unix socket
|
||||||
|
* - ``spice:port``
|
||||||
|
- ``5900``
|
||||||
|
- Set the SPICE port; 0 selects a Unix socket
|
||||||
|
* - ``spice:input``
|
||||||
|
- ``yes``
|
||||||
|
- Permit SPICE input fallback
|
||||||
|
* - ``spice:clipboard``
|
||||||
|
- ``yes``
|
||||||
|
- Permit SPICE clipboard service
|
||||||
|
* - ``spice:audio``
|
||||||
|
- ``yes``
|
||||||
|
- Permit SPICE audio service
|
||||||
|
* - ``spice:usbAudio``
|
||||||
|
- ``yes``
|
||||||
|
- Use the recommended emulated USB audio device instead of classic SPICE
|
||||||
|
audio
|
||||||
|
|
||||||
|
.. list-table:: Window and display
|
||||||
|
:widths: 34 16 50
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - Option
|
||||||
|
- Default
|
||||||
|
- Purpose
|
||||||
|
* - ``win:size``
|
||||||
|
- ``1024x768``
|
||||||
|
- Set the initial client window size
|
||||||
|
* - ``win:fullScreen``
|
||||||
|
- ``no``
|
||||||
|
- Start full screen
|
||||||
|
* - ``win:autoResize``
|
||||||
|
- ``no``
|
||||||
|
- Follow guest resolution changes
|
||||||
|
* - ``win:setGuestRes``
|
||||||
|
- ``yes``
|
||||||
|
- Ask a supporting producer to follow the client viewport
|
||||||
|
* - ``win:fpsMin``
|
||||||
|
- automatic
|
||||||
|
- Set the minimum redraw rate; 0 disables it and is not recommended
|
||||||
|
* - ``win:jitRender``
|
||||||
|
- ``no``
|
||||||
|
- Render close to the predicted presentation deadline
|
||||||
|
* - ``win:showFPS``
|
||||||
|
- ``no``
|
||||||
|
- Show the FPS and UPS widget
|
||||||
|
* - ``egl:mapHDRtoSDR``
|
||||||
|
- ``yes``
|
||||||
|
- Tone-map HDR frames for an SDR output
|
||||||
|
* - ``egl:preset``
|
||||||
|
- none
|
||||||
|
- Load a named filter preset at startup
|
||||||
|
|
||||||
|
.. list-table:: Input
|
||||||
|
:widths: 34 16 50
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - Option
|
||||||
|
- Default
|
||||||
|
- Purpose
|
||||||
|
* - ``input:escapeKey``
|
||||||
|
- ``KEY_SCROLLLOCK``
|
||||||
|
- Set the capture/menu key; use ``help`` to list accepted names
|
||||||
|
* - ``input:autoCapture``
|
||||||
|
- ``no``
|
||||||
|
- Grab the keyboard inside the guest view and release it before exit
|
||||||
|
* - ``input:captureOnly``
|
||||||
|
- ``no``
|
||||||
|
- Enable guest input only while captured
|
||||||
|
* - ``input:grabKeyboard``
|
||||||
|
- ``yes``
|
||||||
|
- Grab the keyboard in capture mode
|
||||||
|
* - ``input:rawMouse``
|
||||||
|
- ``no``
|
||||||
|
- Use raw relative movement in capture mode
|
||||||
|
* - ``input:mouseRedraw``
|
||||||
|
- ``yes``
|
||||||
|
- Repaint at display cadence when only the cursor changes
|
||||||
|
|
||||||
|
.. list-table:: Audio and clipboard
|
||||||
|
:widths: 34 16 50
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - Option
|
||||||
|
- Default
|
||||||
|
- Purpose
|
||||||
|
* - ``clipboard:toVM``
|
||||||
|
- ``yes``
|
||||||
|
- Allow clipboard transfers to the guest
|
||||||
|
* - ``clipboard:toLocal``
|
||||||
|
- ``yes``
|
||||||
|
- Allow clipboard transfers from the guest
|
||||||
|
* - ``audio:periodSize``
|
||||||
|
- ``512``
|
||||||
|
- Request an audio backend period in samples
|
||||||
|
* - ``audio:latencyOffset``
|
||||||
|
- ``6``
|
||||||
|
- Add safety margin to the classic SPICE audio buffer in milliseconds
|
||||||
|
* - ``audio:resampler``
|
||||||
|
- ``auto``
|
||||||
|
- Select classic SPICE resampling with ``auto``, ``libsamplerate`` or the
|
||||||
|
backend
|
||||||
|
* - ``audio:micDefault``
|
||||||
|
- ``prompt``
|
||||||
|
- Select ``prompt``, ``allow`` or ``deny`` for microphone requests
|
||||||
|
* - ``audio:debug``
|
||||||
|
- ``no``
|
||||||
|
- Log detailed audio synchronization statistics
|
||||||
|
|
||||||
|
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.
|
||||||
75
doc/overview.rst
Normal file
75
doc/overview.rst
Normal file
@@ -0,0 +1,75 @@
|
|||||||
|
.. _overview:
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
The names used throughout this guide are:
|
||||||
|
|
||||||
|
Linux host
|
||||||
|
The physical machine running KVM/QEMU and the Looking Glass Client.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Recommended setup
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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. Legacy Host users must use the complete matching
|
||||||
|
B7 stack described below.
|
||||||
|
|
||||||
|
.. _legacy_host_policy:
|
||||||
|
|
||||||
|
Legacy Host Application
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
The Host Application is a legacy producer. 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.
|
||||||
156
doc/performance.rst
Normal file
156
doc/performance.rst
Normal file
@@ -0,0 +1,156 @@
|
|||||||
|
.. _client_performance:
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
FPS and UPS
|
||||||
|
-----------
|
||||||
|
|
||||||
|
FPS
|
||||||
|
How often the client completed a render and swap. Cursor-only and overlay
|
||||||
|
redraws can raise this without a new desktop frame.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Frame latency graphs
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
The **Minimum**, **Maximum** and **Average** panels show a running history in
|
||||||
|
200 ms buckets. Each colored band is a sequential stage. The thickness of a
|
||||||
|
band is its duration; its height above zero includes all earlier bands. The top
|
||||||
|
of the final **Swap** band is the plotted total through return from EGL swap.
|
||||||
|
|
||||||
|
The current incomplete bucket is not plotted. This keeps the newest point from
|
||||||
|
jumping as samples arrive. Each panel also keeps a stable vertical scale with
|
||||||
|
hysteresis, so read the millisecond axis when comparing panels.
|
||||||
|
|
||||||
|
.. list-table:: Producer and transport stages
|
||||||
|
:widths: 18 82
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - Band
|
||||||
|
- What it measures
|
||||||
|
* - **Capture**
|
||||||
|
- Time spent successfully acquiring the next IDD swap-chain buffer. This
|
||||||
|
is not Windows Graphics Capture and does not include guest application
|
||||||
|
rendering or the wait between unsuccessful acquisition attempts.
|
||||||
|
* - **Post**
|
||||||
|
- IDD preparation before the measured copy, including format and damage
|
||||||
|
processing, synchronization and any required compute effect.
|
||||||
|
* - **Copy**
|
||||||
|
- IDD work that copies the selected frame into retained or transport
|
||||||
|
storage. It may include more than one copy when the selected path needs
|
||||||
|
it.
|
||||||
|
* - **Ready**
|
||||||
|
- Remaining IDD queue, fence, finalization and publication overhead not
|
||||||
|
included in Post, Copy or Hold.
|
||||||
|
* - **Hold**
|
||||||
|
- Time a prepared hardware frame waits for the cadence deadline before
|
||||||
|
its final transport copy starts. This is intentional scheduling time.
|
||||||
|
Software processing does not use cadence and reports zero.
|
||||||
|
* - **Transport**
|
||||||
|
- Inferred publication-to-client delay for a frame matched to a cadence
|
||||||
|
deadline. It is not an “IVSHMEM copy” measurement and is omitted when
|
||||||
|
producer and client timing cannot be matched safely.
|
||||||
|
|
||||||
|
.. list-table:: Client EGL stages
|
||||||
|
:widths: 18 82
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - Band
|
||||||
|
- What it measures
|
||||||
|
* - **Import**
|
||||||
|
- Work needed to make the frame usable by EGL, such as a CPU staging copy
|
||||||
|
or DMA import and snapshot submission.
|
||||||
|
* - **Dispatch**
|
||||||
|
- Remaining frame-thread validation, format, damage and queueing work
|
||||||
|
after Import.
|
||||||
|
* - **Queue**
|
||||||
|
- Time from queueing the accepted update until the render thread begins.
|
||||||
|
This includes waiting for display cadence and deliberate JIT slack.
|
||||||
|
* - **Prepare**
|
||||||
|
- Client render-thread preparation such as commands, resize handling,
|
||||||
|
geometry and invalidation decisions.
|
||||||
|
* - **Setup**
|
||||||
|
- EGL state, damage history, HDR and pointer setup before desktop drawing.
|
||||||
|
* - **Effects**
|
||||||
|
- Evaluation of the active EGL filter chain.
|
||||||
|
* - **Desktop**
|
||||||
|
- Completion of the frame texture and drawing the guest desktop, with
|
||||||
|
Effects shown separately.
|
||||||
|
* - **Compose**
|
||||||
|
- Cursor, letterbox, damage diagnostics and HDR composition around the
|
||||||
|
desktop. The interactive UI overlay is deliberately excluded.
|
||||||
|
* - **Swap**
|
||||||
|
- Time inside the display-server EGL swap call. It may include blocking
|
||||||
|
in EGL or compositor submission, but not later physical scanout.
|
||||||
|
|
||||||
|
Only guest frames actually consumed by EGL contribute producer samples.
|
||||||
|
Superseded frames are not treated as latency samples. The minimum and maximum
|
||||||
|
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.
|
||||||
|
|
||||||
|
Cadence and Hold
|
||||||
|
----------------
|
||||||
|
|
||||||
|
The Linux display and Windows guest have independent clocks. Looking Glass
|
||||||
|
does not subtract their raw timestamps. The producer reports durations, while
|
||||||
|
periods, generations and deadlines identify a matching cadence event. The
|
||||||
|
Transport band is left absent when that match is not valid.
|
||||||
|
|
||||||
|
At equal nominal rates, a **Hold** sawtooth is normally a beat pattern between
|
||||||
|
two free-running refresh cycles. The age of the newest guest frame ramps as
|
||||||
|
their phase moves, then wraps when a newer frame reaches the next client
|
||||||
|
deadline. This is not accumulated cross-VM clock error.
|
||||||
|
|
||||||
|
Configure the IDD with the physical display's exact refresh rate to minimize
|
||||||
|
this pattern. For example, use 119.970 Hz when that is the rate reported for
|
||||||
|
the display instead of rounding it to 120 Hz.
|
||||||
|
|
||||||
|
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 producer work or scheduling delays rather than normal phase drift.
|
||||||
|
|
||||||
|
Frame and photon summaries
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
The compact **FRAME** plot is the interval between completed client
|
||||||
|
render-and-swap loops. It includes cadence waits and cursor-only or overlay-only
|
||||||
|
redraws, so it is not the CPU time spent rendering one frame.
|
||||||
|
|
||||||
|
On Wayland compositors that support ``wp_presentation``, **PHOTON** measures
|
||||||
|
from immediately before the EGL swap request until the compositor reports
|
||||||
|
presentation. It includes Swap and must not be added to the stacked total. The
|
||||||
|
displayed reciprocal “Hz” describes average latency, not the actual monitor
|
||||||
|
presentation rate.
|
||||||
|
|
||||||
|
Finding a bottleneck
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
* High **Copy** points to guest GPU or system-memory bandwidth and the IDD copy
|
||||||
|
path.
|
||||||
|
* High **Hold** alone usually reflects cadence phase; correlate it with other
|
||||||
|
stages before changing anything.
|
||||||
|
* High **Import** with DMA disabled points to the client-side memory copy.
|
||||||
|
* High **Queue** can be intentional cadence or JIT waiting. Disable
|
||||||
|
``win:jitRender`` while diagnosing unstable timing.
|
||||||
|
* High **Effects**, **Desktop** or **Compose** points to client GPU rendering.
|
||||||
|
* A stable high **Swap** or **PHOTON** value can be expected when cadence
|
||||||
|
matching waits for the correct presentation cycle. It does not by itself
|
||||||
|
indicate an actual end-to-end latency increase. Investigate unexpected
|
||||||
|
variation or missed cycles instead.
|
||||||
|
|
||||||
|
Keep the guest resolution and refresh realistic for the available memory
|
||||||
|
bandwidth. Reserve at least two physical CPU cores for Linux and avoid changing
|
||||||
|
poll intervals as a first response to a spike.
|
||||||
34
doc/quickstart.rst
Normal file
34
doc/quickstart.rst
Normal file
@@ -0,0 +1,34 @@
|
|||||||
|
.. _quick_start:
|
||||||
|
|
||||||
|
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
|
||||||
|
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
|
||||||
|
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:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
looking-glass-client
|
||||||
|
|
||||||
|
The client selects ``/dev/kvmfr0`` automatically when it is present, and
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
SPICE is optional for the primary IDD video and input paths. Keep it enabled
|
||||||
|
if you want clipboard, audio or display fallback services.
|
||||||
@@ -1,97 +1,103 @@
|
|||||||
.. _requirements:
|
.. _requirements:
|
||||||
|
|
||||||
Requirements
|
Requirements and compatibility
|
||||||
############
|
##############################
|
||||||
|
|
||||||
.. _minimum:
|
.. _minimum:
|
||||||
|
|
||||||
Minimum
|
Required
|
||||||
-------
|
--------
|
||||||
|
|
||||||
The most basic requirement to make use of Looking Glass is to have a system
|
Linux host
|
||||||
with two GPUs, the following configurations are valid:
|
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.
|
||||||
|
|
||||||
* Two discrete GPUs (dGPU)
|
Windows guest
|
||||||
* A discrete GPU and an integrated (iGPU) such as is common in laptops.
|
A Windows 10 version 1803 or newer, or Windows 11, virtual machine. The
|
||||||
* A discrete GPU or iGPU and a virtual GPU (vGPU) as supported by some
|
recommended IDD path can create its own virtual monitor and does not require
|
||||||
hardware.
|
a physical monitor or dummy plug.
|
||||||
|
|
||||||
.. note::
|
Shared memory
|
||||||
Please be aware that iGPU users may be limited in the resolution and refresh
|
An IVSHMEM device large enough for the maximum guest resolution. The KVMFR
|
||||||
rate possible with Looking Glass due to the memory bandwidth limitations
|
kernel module is recommended and is required for direct GPU imports.
|
||||||
imposed due to the iGPU sharing system RAM for GPU usage.
|
|
||||||
|
|
||||||
Looking Glass aims to achieve the lowest possible latency and as such it
|
Matching components
|
||||||
is important that you do not overload your system. The minimum recommended CPU
|
Use the current client, IDD and OBS plugin from the same Looking Glass
|
||||||
to obtain a decent experience with Looking Glass is 6 cores or more, with
|
release. A protocol version mismatch is not supported. Legacy Host users
|
||||||
Hyper-threading (>= 12 threads).
|
must use the complete matching B7 stack described below.
|
||||||
|
|
||||||
PCIe bandwidth can also be a limiting factor, as such both GPUs should have a
|
The IDD can fall back to software processing if the Windows guest has no
|
||||||
minimum of 8 lanes (x8) at PCIe3 speeds, or 4 lanes (x4) at PCIe4 speeds.
|
suitable render GPU. This is useful for compatibility, but hardware processing
|
||||||
|
is strongly recommended for lower latency and higher frame rates. Software
|
||||||
.. _connected_display:
|
mode is SDR-only and does not provide the same performance as the GPU path.
|
||||||
|
|
||||||
Connected Display
|
|
||||||
^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
The GPU used for the guest virtual machine must have either a physical monitor
|
|
||||||
attached to it, or a cheap dummy plug. The guest operating system (most notably
|
|
||||||
Windows) will disable the GPU output if there is nothing attached to it and
|
|
||||||
Looking Glass will not be able to function. If you are using a vGPU the virtual
|
|
||||||
device should already have a virtual monitor attached to it negating this
|
|
||||||
requirement.
|
|
||||||
|
|
||||||
.. _recommended:
|
.. _recommended:
|
||||||
|
|
||||||
Recommended
|
Recommended
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
At this time the recommended configuration is as follows:
|
For a responsive high-resolution setup, use:
|
||||||
|
|
||||||
* CPU 8 cores (16 threads) or better @ 3.0GHz or faster (full cores, not
|
* a host CPU with eight cores and sixteen threads or better, with full
|
||||||
efficiency cores).
|
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.
|
||||||
|
|
||||||
* Two discrete GPUs consisting of:
|
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.
|
||||||
|
|
||||||
* AMD or Intel brand GPU for the client application (usually your host system).
|
For a passed-through GPU, PCIe bandwidth can also limit performance. Use at
|
||||||
* NVIDIA brand GPU for the guest system (virtual machine).
|
least eight PCIe 3.0 lanes or four PCIe 4.0 lanes where practical.
|
||||||
|
|
||||||
AMD or Intel for the client
|
.. _connected_display:
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
AMD and Intel both support the `DMABUF` feature which enables offloading memory
|
Physical display and dummy plugs
|
||||||
transfers to the GPU hardware. Please note that making use of this feature
|
--------------------------------
|
||||||
requires :doc:`loading the KVMFR kernel module <ivshmem_kvmfr>`.
|
|
||||||
|
|
||||||
Additionally AMD GPUs suffer stability issues when operating as a passthrough
|
The recommended IDD does not require a physical display or dummy plug. It
|
||||||
device and as such we do not recommend their usage for such purposes. Models of
|
creates a virtual Windows monitor, including on systems without a
|
||||||
note that have issues include but are not limited to the entire Polaris, Vega,
|
passed-through display output.
|
||||||
Navi and BigNavi GPU series. Vega and Navi are notably the worst and should be
|
|
||||||
avoided for virtualization usage.
|
|
||||||
|
|
||||||
NVIDIA for the guest
|
A physical display, dummy plug or another virtual monitor is only required
|
||||||
^^^^^^^^^^^^^^^^^^^^
|
when using the :doc:`legacy Host Application <install_host>`, because that
|
||||||
|
application captures an existing Windows display.
|
||||||
NVIDIA unlike AMD do not seem to suffer from the same stability issues as AMD
|
|
||||||
GPUs when operating as a passthrough GPU, however due to the closed source
|
|
||||||
nature of their drivers NVIDIA can not make use of the DMABUF feature in the
|
|
||||||
Linux kernel unless you use the open source NVIDIA drivers.
|
|
||||||
|
|
||||||
.. _igpu_kvmfr_recommended:
|
.. _igpu_kvmfr_recommended:
|
||||||
|
|
||||||
iGPUs should use DMABUF
|
Host GPU notes
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^
|
--------------
|
||||||
|
|
||||||
While `DMABUF` with the :doc:`KVMFR module <ivshmem_kvmfr>` offers performance
|
AMD and Intel host GPUs commonly support the DMA-BUF path used by KVMFR. This
|
||||||
benefits for all users, for the often bandwidth-starved users with an iGPU on
|
can reduce CPU work and avoid an extra system-memory copy. It is particularly
|
||||||
their host it's considered a requirement for a decent experience.
|
important for integrated GPUs, which already share memory bandwidth with the
|
||||||
|
CPU.
|
||||||
|
|
||||||
When using a normal SHM file, many GPU drivers will copy incoming frames from
|
NVIDIA host GPUs require a driver configuration that supports DMA-BUF import.
|
||||||
shared memory to an intermediary buffer, then upload it from that buffer to the
|
If direct import is unavailable, the client falls back to a software copy.
|
||||||
GPU's framebuffer. The KVMFR module will instead use Direct Memory Access (DMA)
|
Looking Glass still works, but uses more CPU and memory bandwidth.
|
||||||
to download incoming frames directly from shared memory, which may depending on
|
|
||||||
GPU design eliminate the intermediary buffer. This is especially helpful to iGPU
|
|
||||||
users as it frees up RAM bandwidth, which an iGPU already uses extensively.
|
|
||||||
|
|
||||||
An added benefit: since the upload is done with the iGPU, the CPU load is
|
Windows and HDR
|
||||||
reduced as the upload does not use processor cores.
|
---------------
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Native HDR presentation on Linux requires the EGL renderer, Wayland
|
||||||
|
``color-management-v1`` support in the compositor, and an HDR-capable output.
|
||||||
|
When native HDR is unavailable, the client can map HDR content to SDR.
|
||||||
|
|
||||||
|
Legacy Host compatibility
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
The Windows Host Application is no longer the recommended producer. B7 is the
|
||||||
|
last recommended version 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.
|
||||||
|
|||||||
@@ -1,66 +1,65 @@
|
|||||||
Technical FAQ
|
Technical notes
|
||||||
#############
|
###############
|
||||||
|
|
||||||
This FAQ is targeted at developers or technical people that want to
|
This page explains a few implementation choices. It is not required for normal
|
||||||
know more about what's going on under the hood.
|
installation.
|
||||||
|
|
||||||
.. _ivshmemshared_ram:
|
.. _ivshmemshared_ram:
|
||||||
|
|
||||||
IVSHMEM/Shared RAM
|
IVSHMEM and shared memory
|
||||||
------------------
|
-------------------------
|
||||||
|
|
||||||
.. _what_exactly_is_the_ivshmem_device:
|
.. _what_exactly_is_the_ivshmem_device:
|
||||||
|
|
||||||
What exactly is the IVSHMEM device?
|
What is the IVSHMEM device?
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
This is a virtual device that maps a segment of shared memory into the
|
IVSHMEM maps the same reserved memory into QEMU, the Windows guest and Linux.
|
||||||
guest via a BAR (Base Address Register). It also has additional features
|
KVMFR provides the Linux character-device interface used by the client and OBS
|
||||||
such as interrupt triggering for synchronization however we do not use
|
and can export regions for direct GPU import.
|
||||||
these.
|
|
||||||
|
The IDD stores frame queues, frame metadata, pointer updates and input protocol
|
||||||
|
state in this region. It uses three frame buffers so a producer and multiple
|
||||||
|
consumers can progress without overwriting a frame that is still in use.
|
||||||
|
|
||||||
.. _what_is_the_ivshmem_device_being_used_for:
|
.. _what_is_the_ivshmem_device_being_used_for:
|
||||||
|
|
||||||
What is the IVSHMEM device being used for?
|
Why is the allocation larger than one image?
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
One might assume that we are simply using the device for the captured
|
In addition to three aligned images, the region contains LGMP queues and GPU
|
||||||
frames, this, however, is not entirely accurate. Looking Glass also
|
resource alignment. Use :ref:`libvirt_determining_memory` rather than
|
||||||
needs to capture mouse shape changes (the mouse cursor), and mouse
|
multiplying width and height once.
|
||||||
movement events and feed these back to the client to render. We need
|
|
||||||
this additional information as we actually are rendering the cursor on
|
|
||||||
the client-side, independent of the frame capture. This is why when you
|
|
||||||
move your cursor around it doesn't affect the UPS, which is only
|
|
||||||
counting frame updates.
|
|
||||||
|
|
||||||
.. _why_do_you_need_the_mouse_positional_information:
|
.. _why_do_you_need_the_mouse_positional_information:
|
||||||
|
|
||||||
Why do you need the mouse positional information?
|
Why are there both absolute and relative mouse paths?
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Windows has no notion of an absolute pointing device unless you are
|
Desktop interaction needs absolute positioning so the host and guest pointers
|
||||||
using a tablet, which does work, however, if you also want relative
|
stay aligned without capture. Games that lock the cursor need unbounded
|
||||||
input for applications/games that require cursor capture, you need a
|
relative movement. The IDD exposes both and the client selects the appropriate
|
||||||
relative input device such as a PS/2 mouse.
|
path when capture mode changes.
|
||||||
|
|
||||||
The problem is, due to the design of QEMU or the Windows mouse subsystem
|
SPICE fallback remains relative-only. Pointer position messages are also used
|
||||||
(not sure which), when the VM has both devices attached (which is the
|
to render the guest cursor independently from desktop frame updates.
|
||||||
default for libvirt), mouse click events are always at the last location
|
|
||||||
of the absolute positional device (tablet) even if the cursor has been
|
|
||||||
moved with the relative input device.
|
|
||||||
|
|
||||||
Because of this bug, we need to always operate in relative mouse input
|
|
||||||
mode, and since factors like windows mouse acceleration, or cursor
|
|
||||||
movement by a user application may occur in the guest, we need to pass
|
|
||||||
this information back so the client can render the cursor in the correct
|
|
||||||
location.
|
|
||||||
|
|
||||||
.. _why_does_lg_poll_for_updates_instead_of_using_interrupts:
|
.. _why_does_lg_poll_for_updates_instead_of_using_interrupts:
|
||||||
|
|
||||||
Why does LG poll for updates instead of using interrupts?
|
Why does Looking Glass poll for updates?
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Initially, we were using interrupts in early designs however it became
|
Polling avoids the high overhead and batching behavior seen with virtual
|
||||||
clear that the performance, especially for high update rate mice was
|
interrupts, especially for high-rate pointer updates. The polling intervals
|
||||||
extremely poor. This may have improved in recent QEMU versions and
|
are configurable for diagnosis, but lowering them without evidence increases
|
||||||
perhaps should be re-evaluated at some point.
|
CPU usage and does not guarantee lower latency.
|
||||||
|
|
||||||
|
How does cadence reduce bandwidth?
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Clients publish their presentation period and deadline in the shared protocol.
|
||||||
|
The IDD prepares guest frames as they arrive, but transports only the newest
|
||||||
|
frame needed for the fastest active consumer. Other consumers independently
|
||||||
|
select the newest frame appropriate for their own rate. Clock-domain feedback
|
||||||
|
is exchanged as periods and deadlines rather than comparing raw timestamps
|
||||||
|
from Windows and Linux.
|
||||||
|
|||||||
3
doc/templates/breadcrumbs.html
vendored
Normal file
3
doc/templates/breadcrumbs.html
vendored
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
{% extends "!breadcrumbs.html" %}
|
||||||
|
|
||||||
|
{% block breadcrumbs_aside %}{% endblock %}
|
||||||
20
doc/templates/footer.html
vendored
Normal file
20
doc/templates/footer.html
vendored
Normal file
@@ -0,0 +1,20 @@
|
|||||||
|
{% extends "!footer.html" %}
|
||||||
|
|
||||||
|
{% block extrafooter %}
|
||||||
|
{{ super() }}
|
||||||
|
{%- if hasdoc(pagename) and show_source %}
|
||||||
|
{%- if source_url_prefix %}
|
||||||
|
<p>
|
||||||
|
<a href="{{ source_url_prefix }}{{ pagename }}{{ page_source_suffix }}">
|
||||||
|
{{ _('View page source') }}
|
||||||
|
</a>
|
||||||
|
</p>
|
||||||
|
{%- elif has_source and sourcename %}
|
||||||
|
<p>
|
||||||
|
<a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow">
|
||||||
|
{{ _('View page source') }}
|
||||||
|
</a>
|
||||||
|
</p>
|
||||||
|
{%- endif %}
|
||||||
|
{%- endif %}
|
||||||
|
{% endblock %}
|
||||||
3
doc/theme/lookingglass/theme.conf
vendored
Normal file
3
doc/theme/lookingglass/theme.conf
vendored
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
[theme]
|
||||||
|
inherit = sphinx_rtd_theme
|
||||||
|
pygments_dark_style = github-dark
|
||||||
@@ -1,22 +1,83 @@
|
|||||||
Troubleshooting
|
Troubleshooting
|
||||||
###############
|
###############
|
||||||
|
|
||||||
There are many different issues that can arise when setting up Looking
|
Start with the symptom below. Avoid changing polling, synchronization or
|
||||||
Glass. Below is a list of known issues with potential solutions:
|
renderer options until the basic producer, shared-memory and version checks
|
||||||
|
pass.
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
idd_diagnostics
|
||||||
|
|
||||||
.. _when_launching_looking_glass_the_desktop_doesnt_appear:
|
.. _when_launching_looking_glass_the_desktop_doesnt_appear:
|
||||||
|
|
||||||
When launching Looking Glass the desktop doesn't appear
|
The Looking Glass monitor is missing in Windows
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
-----------------------------------------------
|
||||||
|
|
||||||
Make sure you meet the :ref:`minimum requirements<minimum>` for using
|
1. Confirm that the guest runs Windows 10 version 1803 or newer, or Windows 11.
|
||||||
Looking Glass, especially regarding your guest GPU. See
|
2. Confirm that the IDD installer completed and restart Windows if requested.
|
||||||
:ref:`connected_display` for more details.
|
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 frame producer should
|
||||||
|
use the Looking Glass 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.
|
||||||
|
|
||||||
|
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 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.
|
||||||
|
* 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.
|
||||||
|
|
||||||
|
The image is slow or stutters
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
Open the timing graphs with :kbd:`ScrLk` + :kbd:`T` and follow
|
||||||
|
:ref:`client_performance`. Also check:
|
||||||
|
|
||||||
|
* the IDD helper reports GPU acceleration rather than software processing;
|
||||||
|
* ``lgmp:allowDMA=yes`` is using a direct import when the host driver supports
|
||||||
|
it;
|
||||||
|
* enough CPU cores remain available to Linux;
|
||||||
|
* the guest resolution and refresh do not exceed available memory bandwidth;
|
||||||
|
* 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
|
||||||
|
can acquire newer frames and skip superseded ones before transport, but the
|
||||||
|
guest still pays the cost of rendering them.
|
||||||
|
|
||||||
|
Keyboard or mouse input does not work
|
||||||
|
-------------------------------------
|
||||||
|
|
||||||
|
* Press :kbd:`ScrLk` + :kbd:`I` to ensure guest input is enabled.
|
||||||
|
* Check ``looking-glass-input.txt`` and the client's selected input provider.
|
||||||
|
* 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.
|
||||||
|
* If ``input:captureOnly=yes``, press :kbd:`ScrLk` to enter capture mode.
|
||||||
|
|
||||||
|
See :ref:`client_input` for normal, automatic keyboard and capture modes.
|
||||||
|
|
||||||
.. _the_clipboard_is_not_working:
|
.. _the_clipboard_is_not_working:
|
||||||
|
|
||||||
The clipboard is not working
|
The clipboard is not working
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
----------------------------
|
||||||
|
|
||||||
- **Is clipboard synchronization enabled?**
|
- **Is clipboard synchronization enabled?**
|
||||||
|
|
||||||
@@ -29,7 +90,7 @@ The clipboard is not working
|
|||||||
|
|
||||||
- The `SPICE Guest Tools
|
- The `SPICE Guest Tools
|
||||||
driver <https://www.spice-space.org/download.html>`_ must be installed
|
driver <https://www.spice-space.org/download.html>`_ must be installed
|
||||||
on the host OS to synchronize the clipboard.
|
inside the Windows guest to synchronize the clipboard.
|
||||||
The download is labeled "spice-guest-tools".
|
The download is labeled "spice-guest-tools".
|
||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
@@ -46,7 +107,7 @@ The clipboard is not working
|
|||||||
.. _keyboard_shortcuts_not_captured_on_gnome_wayland:
|
.. _keyboard_shortcuts_not_captured_on_gnome_wayland:
|
||||||
|
|
||||||
Keyboard shortcuts are not captured on GNOME Wayland
|
Keyboard shortcuts are not captured on GNOME Wayland
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
-----------------------------------------------------
|
||||||
|
|
||||||
Capture mode may fail to capture compositor shortcuts like
|
Capture mode may fail to capture compositor shortcuts like
|
||||||
ALT+Tab or ALT+Middle Mouse - they go to GNOME instead of the guest VM.
|
ALT+Tab or ALT+Middle Mouse - they go to GNOME instead of the guest VM.
|
||||||
@@ -69,3 +130,23 @@ To verify the permission was set:
|
|||||||
|
|
||||||
flatpak permissions gnome shortcuts-inhibitor
|
flatpak permissions gnome shortcuts-inhibitor
|
||||||
|
|
||||||
|
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``.
|
||||||
|
* In Windows Sound settings, select the Looking Glass USB Audio speakers as
|
||||||
|
the output device.
|
||||||
|
* Check the client startup log. If USB audio creation failed before
|
||||||
|
connection, Looking Glass falls back to classic SPICE audio and reports why.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|||||||
780
doc/usage.rst
780
doc/usage.rst
@@ -1,717 +1,149 @@
|
|||||||
.. _client_usage:
|
.. _client_usage:
|
||||||
|
|
||||||
Client usage
|
Use the client
|
||||||
------------
|
##############
|
||||||
|
|
||||||
.. raw:: html
|
Start the client after the Windows guest and IDD are running:
|
||||||
|
|
||||||
<p><code class="literal"><b>looking-glass-client</b> [--help] [-f] [-F] [-s] [-S] [options...]</code></p>
|
.. code:: bash
|
||||||
|
|
||||||
|
looking-glass-client
|
||||||
|
|
||||||
.. _client_cli_options:
|
The client uses LGMP over ``/dev/kvmfr0`` automatically when that device is
|
||||||
|
available. Otherwise it uses ``/dev/shm/looking-glass``. Select another device
|
||||||
|
with ``-f`` or the canonical ``lgmp:shmDevice`` option:
|
||||||
|
|
||||||
Command line options
|
.. code:: bash
|
||||||
~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
A full list of command line options is available with the ``--help`` or ``-h``
|
looking-glass-client -f /dev/kvmfr1
|
||||||
options.
|
|
||||||
|
|
||||||
Example: ``looking-glass-client --help``
|
Use ``looking-glass-client --help`` to see the options supported by the
|
||||||
|
installed build. Command-line options override configuration files.
|
||||||
Common options are listed below:
|
|
||||||
|
|
||||||
================ ===========================================
|
|
||||||
Short option Description
|
|
||||||
================ ===========================================
|
|
||||||
``-f shmFile`` use ``shmFile`` for IVSHMEM shared memory
|
|
||||||
``-F`` automatically enter full screen
|
|
||||||
``-s`` disable spice
|
|
||||||
``-S`` disable host screensaver
|
|
||||||
================ ===========================================
|
|
||||||
|
|
||||||
Options may be provided in short form when available, or long form.
|
|
||||||
Boolean options may be specified without a parameter to toggle their
|
|
||||||
state.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
- ``looking-glass-client -F`` (short)
|
|
||||||
- ``looking-glass-client win:fullScreen`` (long)
|
|
||||||
- ``looking-glass-client -f /dev/shm/my-lg-shmem`` (short with parameter)
|
|
||||||
- ``looking-glass-client app:shmFile=/dev/shm/my-lg-shmem`` (long with parameter)
|
|
||||||
|
|
||||||
.. seealso::
|
|
||||||
|
|
||||||
:ref:`client_full_command_options`
|
|
||||||
|
|
||||||
.. _client_key_bindings:
|
.. _client_key_bindings:
|
||||||
|
|
||||||
Default key bindings
|
Default key bindings
|
||||||
~~~~~~~~~~~~~~~~~~~~
|
--------------------
|
||||||
|
|
||||||
By default, Looking Glass uses the :kbd:`ScrLk` key as the escape key
|
Looking Glass uses :kbd:`ScrLk` as its escape key by default. Press it by
|
||||||
for commands, as well as the input :kbd:`capture` mode toggle; this can be
|
itself to enter or leave capture mode. Hold it to display the available
|
||||||
changed using the ``-m`` switch if you desire a different key. Below are
|
commands. Change it with ``input:escapeKey`` or ``-m`` if the keyboard does
|
||||||
a list of current key bindings:
|
not have :kbd:`ScrLk`.
|
||||||
|
|
||||||
============================ =======================================================
|
.. list-table:: Default client commands
|
||||||
Command Description
|
:widths: 35 65
|
||||||
============================ =======================================================
|
:header-rows: 1
|
||||||
:kbd:`ScrLk` Toggle capture mode
|
|
||||||
:kbd:`ScrLk` + :kbd:`Q` Quit
|
|
||||||
:kbd:`ScrLk` + :kbd:`E` Toggle audio recording
|
|
||||||
:kbd:`ScrLk` + :kbd:`R` Rotate the output clockwise by 90° increments
|
|
||||||
:kbd:`ScrLk` + :kbd:`T` Show frame timing information
|
|
||||||
:kbd:`ScrLk` + :kbd:`I` Spice keyboard & mouse enable toggle
|
|
||||||
:kbd:`ScrLk` + :kbd:`O` Toggle overlay
|
|
||||||
:kbd:`ScrLk` + :kbd:`D` FPS display toggle
|
|
||||||
:kbd:`ScrLk` + :kbd:`F` Full screen toggle
|
|
||||||
:kbd:`ScrLk` + :kbd:`V` Video stream toggle
|
|
||||||
:kbd:`ScrLk` + :kbd:`N` Toggle night vision mode
|
|
||||||
:kbd:`ScrLk` + :kbd:`F1` Send :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F1` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`F2` Send :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F2` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`F3` Send :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F3` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`F4` Send :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F4` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`F5` Send :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F5` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`F6` Send :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F6` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`F7` Send :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F7` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`F8` Send :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F8` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`F9` Send :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F9` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`F10` Send :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F10` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`F11` Send :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F11` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`F12` Send :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F12` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`M` Send mute to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`↑` Send volume up to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`↓` Send volume down to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`Insert` Increase mouse sensitivity in capture mode
|
|
||||||
:kbd:`ScrLk` + :kbd:`Del` Decrease mouse sensitivity in capture mode
|
|
||||||
:kbd:`ScrLk` + :kbd:`LWin` Send :kbd:`LWin` to the guest
|
|
||||||
:kbd:`ScrLk` + :kbd:`RWin` Send :kbd:`RWin` to the guest
|
|
||||||
============================ =======================================================
|
|
||||||
|
|
||||||
You can also find this list at any time by holding down :kbd:`ScrLk`.
|
* - Command
|
||||||
|
- Action
|
||||||
|
* - :kbd:`ScrLk`
|
||||||
|
- Enter or leave capture mode
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`Q`
|
||||||
|
- Quit
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`F`
|
||||||
|
- Toggle full screen
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`V`
|
||||||
|
- Toggle the video stream
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`R`
|
||||||
|
- Rotate clockwise by 90 degrees
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`=`
|
||||||
|
- Ask the IDD to match the client window resolution
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`I`
|
||||||
|
- Toggle guest input
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`O`
|
||||||
|
- Enter or leave interactive overlay mode
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`D`
|
||||||
|
- Toggle the FPS and UPS widget
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`T`
|
||||||
|
- Toggle the frame-timing graphs
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`N`
|
||||||
|
- Toggle EGL night vision
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`E`
|
||||||
|
- Toggle microphone recording when the audio backend supports it
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`C`
|
||||||
|
- Cycle the default microphone permission
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`M`
|
||||||
|
- Send mute to the guest
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`Up` or :kbd:`Down`
|
||||||
|
- Send volume up or down to the guest
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`Insert` or :kbd:`Delete`
|
||||||
|
- Adjust capture-mode mouse sensitivity
|
||||||
|
* - :kbd:`ScrLk` + :kbd:`LWin` or :kbd:`RWin`
|
||||||
|
- Send that Windows key to the guest
|
||||||
|
* - :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
|
||||||
|
audio recording support. Night vision is an EGL feature. The virtual-console
|
||||||
|
bindings are registered only when the selected guest type is Linux.
|
||||||
|
|
||||||
.. _client_config_options_file:
|
.. _client_config_options_file:
|
||||||
|
|
||||||
Configuration files
|
Configuration files
|
||||||
~~~~~~~~~~~~~~~~~~~
|
-------------------
|
||||||
|
|
||||||
By default, Looking Glass will load config files from
|
The client loads these files in order when they exist:
|
||||||
the following locations:
|
|
||||||
|
|
||||||
- ``/etc/looking-glass-client.ini``
|
* ``/etc/looking-glass-client.ini``
|
||||||
- ``~/.looking-glass-client.ini``
|
* ``~/.looking-glass-client.ini``
|
||||||
- ``$XDG_CONFIG_HOME/looking-glass/client.ini`` (usually ``~/.config/looking-glass/client.ini``)
|
* ``$XDG_CONFIG_HOME/looking-glass/client.ini``
|
||||||
|
|
||||||
All config files are loaded in order. Duplicate entries override earlier ones.
|
Later files override earlier files. The usual per-user path is
|
||||||
This means you can set a system-wide configuration in
|
``~/.config/looking-glass/client.ini``. Files use INI syntax:
|
||||||
``/etc/looking-glass-client.ini``, and override specific options for just
|
|
||||||
your user in ``~/.looking-glass-client.ini``, which is overlayed on top of
|
|
||||||
the system-wide configuration.
|
|
||||||
|
|
||||||
When first launched, the Looking-Glass client will create the folder
|
|
||||||
``$XDG_CONFIG_HOME/looking-glass/`` if it does not yet exist.
|
|
||||||
|
|
||||||
The format of config files is the commonly known INI format, for example:
|
|
||||||
|
|
||||||
.. code-block:: ini
|
.. code-block:: ini
|
||||||
|
|
||||||
[win]
|
[win]
|
||||||
fullScreen=yes
|
fullScreen=yes
|
||||||
|
setGuestRes=yes
|
||||||
|
|
||||||
|
[input]
|
||||||
|
autoCapture=yes
|
||||||
|
|
||||||
|
[spice]
|
||||||
|
clipboard=yes
|
||||||
|
audio=yes
|
||||||
|
|
||||||
[egl]
|
[egl]
|
||||||
nvGain=1
|
preset=my-preset
|
||||||
|
|
||||||
; this is a comment
|
Boolean values accept ``yes`` or ``no``. Long command-line options use
|
||||||
|
``section:name=value``, for example:
|
||||||
|
|
||||||
Command line arguments will override any options loaded from config
|
.. code:: bash
|
||||||
files.
|
|
||||||
|
looking-glass-client win:fullScreen=yes input:autoCapture=yes
|
||||||
|
|
||||||
.. _client_overlay_mode:
|
.. _client_overlay_mode:
|
||||||
|
|
||||||
Overlay mode
|
|
||||||
~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The Overlay Mode lets you configure various runtime options for Looking Glass.
|
|
||||||
These include:
|
|
||||||
|
|
||||||
- EGL filters
|
|
||||||
- Performance metrics options
|
|
||||||
- Debug frame damage display
|
|
||||||
|
|
||||||
(see :ref:`client_config_widget`)
|
|
||||||
|
|
||||||
You can also reposition and resize enabled widgets, like the FPS/UPS display,
|
|
||||||
and performance metrics.
|
|
||||||
|
|
||||||
Enter and exit Overlay Mode with :kbd:`ScrLk` + :kbd:`O`.
|
|
||||||
:kbd:`ESC` can also be used to exit. (see :ref:`client_key_bindings`)
|
|
||||||
|
|
||||||
Modifications done to widgets in overlay mode are stored in
|
|
||||||
``$XDG_CONFIG_HOME/looking-glass/imgui.ini``.
|
|
||||||
Please do not manually edit this file while Looking Glass is running,
|
|
||||||
as your changes may be discarded.
|
|
||||||
|
|
||||||
.. _client_config_widget:
|
.. _client_config_widget:
|
||||||
|
|
||||||
Configuration widget
|
Interactive overlay
|
||||||
~~~~~~~~~~~~~~~~~~~~
|
-------------------
|
||||||
|
|
||||||
The configuration widget is accessible through the overlay mode. The
|
Press :kbd:`ScrLk` + :kbd:`O` to make the overlay interactive. Press
|
||||||
widget has multiple tabs that allow setting a variety of modes and
|
:kbd:`Esc` or the same binding to leave it. The overlay can:
|
||||||
parameters for Looking Glass at runtime.
|
|
||||||
|
|
||||||
Settings tab
|
* enable and arrange the FPS and timing widgets;
|
||||||
^^^^^^^^^^^^
|
* select and configure EGL filters;
|
||||||
|
* save filter settings as presets; and
|
||||||
|
* enable diagnostic views such as damage rectangles.
|
||||||
|
|
||||||
- *Performance Metrics*: A toggle for the performance metrics widget.
|
Widget positions and sizes are stored in
|
||||||
Multiple graphs are available, and they will stack vertically.
|
``$XDG_CONFIG_HOME/looking-glass/imgui.ini``. EGL filter presets are stored in
|
||||||
- *EGL*: Modify EGL settings, such as the algorithm used for scaling, and
|
``$XDG_CONFIG_HOME/looking-glass/presets``. Do not edit either while the
|
||||||
night vision mode.
|
client is running.
|
||||||
|
|
||||||
Changes in the settings tab are not persistent, and will be reset back to
|
Runtime changes are not all written to the main client configuration. Put
|
||||||
their default values when the client is restarted.
|
options that must apply at every start in ``client.ini``.
|
||||||
|
|
||||||
EGL filters tab
|
User guides
|
||||||
^^^^^^^^^^^^^^^
|
-----------
|
||||||
|
|
||||||
The EGL filters tab contains options for toggling, configuring, and ordering
|
.. toctree::
|
||||||
post-processing filters. Each filter can be expanded to open its settings.
|
:maxdepth: 1
|
||||||
Filters can also be re-ordered by dragging them up or down. Filters are applied
|
|
||||||
from top to bottom. Keep this in mind when ordering them -- for example,
|
|
||||||
applying CAS before FSR might have different results than the reverse. Users
|
|
||||||
are encouraged to experiment with the order and parameters to achieve optimal
|
|
||||||
results. The currently available filters include:
|
|
||||||
|
|
||||||
- *Downscaler*: Filter for downscaling the host resolution. Can be used to undo
|
input
|
||||||
poor upscaling on the VM to better utilize AMD FSR (see below). The filter
|
display
|
||||||
has a pixel-size setting that is used to set the effective downscaling ratio,
|
audio
|
||||||
and a configurable interpolation algorithm.
|
performance
|
||||||
|
options
|
||||||
- *AMD FidelityFX Super Resolution (FSR)*: Spatial upscaling filter that works
|
|
||||||
on low resolution frames from the guest VM and intelligently upscales to a
|
|
||||||
higher resolution. The filter sharpness is tunable, and displays the
|
|
||||||
equivalent AMD quality mode based on the resolution difference.
|
|
||||||
|
|
||||||
- *AMD FidelityFX Contrast Adaptive Sharpening (CAS)*: Filter that
|
|
||||||
increases visual quality by applying a sharpening algorithm to the
|
|
||||||
video. CAS can sometimes restore detail lost in a typical upscaling
|
|
||||||
application. Has adjustable sharpness setting.
|
|
||||||
|
|
||||||
The filter settings and order can be saved to presets so that it can be restored
|
|
||||||
at a later time. As filter settings are usually application specific, multiple
|
|
||||||
presets can be defined for each case scenario. To save a preset, click on *"Save
|
|
||||||
preset as..."* and enter a preset name. Presets are loaded by selecting them in
|
|
||||||
the *Preset name* pull down. Presets are persistent and are stored on disk at
|
|
||||||
``$XDG_CONFIG_HOME/looking-glass/presets``.
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
Please refrain from modifying any files under the ``presets`` folder.
|
|
||||||
Those files are meant to be modified only by the Looking-Glass client.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
Although presets are persistent, the client will not remember which
|
|
||||||
preset was used last session, so a preset needs to be recalled once
|
|
||||||
the client starts.
|
|
||||||
|
|
||||||
.. _client_full_command_options:
|
|
||||||
|
|
||||||
All command line options
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
+------------------------+-------+-------------+-----------------------------------------------------------------------------------------+
|
|
||||||
| Long | Short | Value | Description |
|
|
||||||
+========================+=======+=============+=========================================================================================+
|
|
||||||
| app:configFile | -C | NULL | A file to read additional configuration from |
|
|
||||||
+------------------------+-------+-------------+-----------------------------------------------------------------------------------------+
|
|
||||||
| app:renderer | -g | auto | Specify the renderer to use |
|
|
||||||
+------------------------+-------+-------------+-----------------------------------------------------------------------------------------+
|
|
||||||
| app:license | -l | no | Show the license for this application and then terminate |
|
|
||||||
+------------------------+-------+-------------+-----------------------------------------------------------------------------------------+
|
|
||||||
| app:cursorPollInterval | | 1000 | How often to check for a cursor update in microseconds |
|
|
||||||
+------------------------+-------+-------------+-----------------------------------------------------------------------------------------+
|
|
||||||
| app:framePollInterval | | 1000 | How often to check for a frame update in microseconds |
|
|
||||||
+------------------------+-------+-------------+-----------------------------------------------------------------------------------------+
|
|
||||||
| app:allowDMA | | yes | Allow direct DMA transfers if supported (see `README.md` in the `module` dir) |
|
|
||||||
+------------------------+-------+-------------+-----------------------------------------------------------------------------------------+
|
|
||||||
| app:shmFile | -f | /dev/kvmfr0 | The path to the shared memory file, or the name of the kvmfr device to use, e.g. kvmfr0 |
|
|
||||||
+------------------------+-------+-------------+-----------------------------------------------------------------------------------------+
|
|
||||||
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| Long | Short | Value | Description |
|
|
||||||
+===========================+=======+========================+=================================================================================================================+
|
|
||||||
| win:title | | Looking Glass (client) | The window title |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:appId | | looking-glass-client | The application Id |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:position | | center | Initial window position at startup |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:size | | 1024x768 | Initial window size at startup |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:autoResize | -a | no | Auto resize the window to the guest |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:allowResize | -n | yes | Allow the window to be manually resized |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:keepAspect | -r | yes | Maintain the correct aspect ratio |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:forceAspect | | yes | Force the window to maintain the aspect ratio |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:dontUpscale | | no | Never try to upscale the window |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:intUpscale | | no | Allow only integer upscaling |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:shrinkOnUpscale | | no | Limit the window dimensions when dontUpscale is enabled |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:borderless | -d | no | Borderless mode |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:fullScreen | -F | no | Launch in fullscreen borderless mode |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:maximize | -T | no | Launch window maximized |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:minimizeOnFocusLoss | | no | Minimize window on focus loss |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:setGuestRes | | yes | On window size change, request the guest to match resolution (if supported by the guest, currently LG IDD only) |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:fpsMin | -K | -1 | Frame rate minimum (0 = disable - not recommended, -1 = auto detect) |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:ignoreQuit | -Q | no | Ignore requests to quit (i.e. Alt+F4) |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:noScreensaver | -S | no | Prevent the screensaver from starting |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:autoScreensaver | | no | Prevent the screensaver from starting when guest requests it |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:alerts | -q | yes | Show on screen alert messages |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:quickSplash | | no | Skip fading out the splash screen when a connection is established |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:overlayDimsDesktop | | yes | Dim the desktop when in interactive overlay mode |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:rotate | | 0 | Rotate the displayed image (0, 90, 180, 270) |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:uiFont | | DejaVu Sans Mono | The font to use when rendering on-screen UI |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:uiSize | | 14 | The font size to use when rendering on-screen UI |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:jitRender | | no | Enable just-in-time rendering |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:requestActivation | | yes | Request activation when attention is needed |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:disableWaitingMessage | | no | Disables the confirmation message for a cleaner UI |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
| win:showFPS | -k | no | Enable the FPS & UPS display |
|
|
||||||
+---------------------------+-------+------------------------+-----------------------------------------------------------------------------------------------------------------+
|
|
||||||
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| Long | Short | Value | Description |
|
|
||||||
+==============================+=======+=====================+==========================================================================================================+
|
|
||||||
| input:captureOnFocus | | no | Enable capture mode when the window becomes focused |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:grabKeyboard | -G | yes | Grab the keyboard in capture mode |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:grabKeyboardOnFocus | | no | Grab the keyboard when focused |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:releaseKeysOnFocusLoss | | yes | On focus loss, send key up events to guest for all held keys |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:escapeKey | -m | 70 = KEY_SCROLLLOCK | Specify the escape/menu key to use (use "help" to see valid values) |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:ignoreWindowsKeys | | no | Do not pass events for the windows keys to the guest |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:hideCursor | -M | yes | Hide the local mouse cursor |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:mouseSens | | 0 | Initial mouse sensitivity when in capture mode (-9 to 9) |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:mouseSmoothing | | yes | Apply simple mouse smoothing when rawMouse is not in use (helps reduce aliasing) |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:rawMouse | | no | Use RAW mouse input when in capture mode (good for gaming) |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:mouseRedraw | | yes | Mouse movements trigger display-rate redraws |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:mouseTrace | | no | Enable mouse input diagnostics |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:autoCapture | | no | Grab the keyboard in the guest view and release it before exit |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:captureOnly | | no | Only enable input via SPICE if in capture mode |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:helpMenuDelay | | 200 | Show help menu after holding down the escape key for this many milliseconds |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:evdev | | NULL | csv list of evdev input devices to use for capture mode (ie: /dev/input/by-id/usb-some_device-event-kbd) |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
| input:evdevExclusive | | yes | Only use evdev devices for input when in capture mode |
|
|
||||||
+------------------------------+-------+---------------------+----------------------------------------------------------------------------------------------------------+
|
|
||||||
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| Long | Short | Value | Description |
|
|
||||||
+========================+=======+===========+=====================================================================+
|
|
||||||
| spice:enable | -s | yes | Enable the built in SPICE client for input and/or clipboard support |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:host | -c | 127.0.0.1 | The SPICE server host or UNIX socket |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:port | -p | 5900 | The SPICE server port (0 = unix socket) |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:input | | yes | Use SPICE to send keyboard and mouse input events to the guest |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:clipboard | | yes | Use SPICE to synchronize the clipboard contents with the guest |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:clipboardToVM | | yes | Allow the clipboard to be synchronized TO the VM |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:clipboardToLocal | | yes | Allow the clipboard to be synchronized FROM the VM |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:audio | | yes | Enable SPICE audio support |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:usbAudio | | no | Use USB redirection for SPICE audio playback |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:scaleCursor | -j | yes | Scale cursor input position to screen size when up/down scaled |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:captureOnStart | | no | Capture mouse and keyboard on start |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:alwaysShowCursor | | no | Always show host cursor |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:showCursorDot | | yes | Use a "dot" cursor when the window does not have focus |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
| spice:largeCursorDot | | no | Use a larger version of the "dot" cursor |
|
|
||||||
+------------------------+-------+-----------+---------------------------------------------------------------------+
|
|
||||||
|
|
||||||
+------------------------+-------+--------+-------------------------------------------------------------------------------+
|
|
||||||
| Long | Short | Value | Description |
|
|
||||||
+========================+=======+========+===============================================================================+
|
|
||||||
| audio:periodSize | | 512 | Requested audio device period size in samples |
|
|
||||||
+------------------------+-------+--------+-------------------------------------------------------------------------------+
|
|
||||||
| audio:latencyOffset | | 4 | Latency offset added to the calculated minimum in milliseconds |
|
|
||||||
+------------------------+-------+--------+-------------------------------------------------------------------------------+
|
|
||||||
| audio:micDefault | | prompt | Default action when an application opens the microphone (prompt, allow, deny) |
|
|
||||||
+------------------------+-------+--------+-------------------------------------------------------------------------------+
|
|
||||||
| audio:micShowIndicator | | yes | Display microphone usage indicator |
|
|
||||||
+------------------------+-------+--------+-------------------------------------------------------------------------------+
|
|
||||||
| audio:syncVolume | | yes | Synchronize the volume level with the guest |
|
|
||||||
+------------------------+-------+--------+-------------------------------------------------------------------------------+
|
|
||||||
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| Long | Short | Value | Description |
|
|
||||||
+===================+=======+=======+===========================================================================+
|
|
||||||
| egl:vsync | | no | Enable vsync |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:doubleBuffer | | no | Enable double buffering |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:multisample | | yes | Enable Multisampling |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:nvGainMax | | 1 | The maximum night vision gain |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:nvGain | | 0 | The initial night vision gain at startup |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:cbMode | | 0 | Color Blind Mode (0 = Off, 1 = Protanope, 2 = Deuteranope, 3 = Tritanope) |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:scale | | 0 | Set the scale algorithm (0 = auto, 1 = nearest, 2 = linear) |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:debug | | no | Enable debug output |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:noBufferAge | | no | Disable partial rendering based on buffer age |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:noSwapDamage | | no | Disable swapping with damage |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:scalePointer | | yes | Keep the pointer size 1:1 when downscaling |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:mapHDRtoSDR | | yes | Map HDR content to the SDR color space |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:peakLuminance | | 250 | The peak luminance level in nits for HDR to SDR mapping |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:maxCLL | | 10000 | Maximum content light level in nits for HDR to SDR mapping |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
| egl:preset | | NULL | The initial filter preset to load |
|
|
||||||
+-------------------+-------+-------+---------------------------------------------------------------------------+
|
|
||||||
|
|
||||||
+----------------------+-------+-------+---------------------------------------------+
|
|
||||||
| Long | Short | Value | Description |
|
|
||||||
+======================+=======+=======+=============================================+
|
|
||||||
| opengl:mipmap | | yes | Enable mipmapping |
|
|
||||||
+----------------------+-------+-------+---------------------------------------------+
|
|
||||||
| opengl:vsync | | no | Enable vsync |
|
|
||||||
+----------------------+-------+-------+---------------------------------------------+
|
|
||||||
| opengl:preventBuffer | | yes | Prevent the driver from buffering frames |
|
|
||||||
+----------------------+-------+-------+---------------------------------------------+
|
|
||||||
| opengl:amdPinnedMem | | yes | Use GL_AMD_pinned_memory if it is available |
|
|
||||||
+----------------------+-------+-------+---------------------------------------------+
|
|
||||||
|
|
||||||
+-----------------------+-------+-------+-------------------------+
|
|
||||||
| Long | Short | Value | Description |
|
|
||||||
+=======================+=======+=======+=========================+
|
|
||||||
| wayland:fractionScale | | yes | Enable fractional scale |
|
|
||||||
+-----------------------+-------+-------+-------------------------+
|
|
||||||
|
|
||||||
+---------------------+-------+-------+----------------------------------------------------------+
|
|
||||||
| Long | Short | Value | Description |
|
|
||||||
+=====================+=======+=======+==========================================================+
|
|
||||||
| i3:globalFullScreen | | no | Use i3's global full screen feature (spans all monitors) |
|
|
||||||
+---------------------+-------+-------+----------------------------------------------------------+
|
|
||||||
|
|
||||||
+--------------------+-------+-------+------------------------------------+
|
|
||||||
| Long | Short | Value | Description |
|
|
||||||
+====================+=======+=======+====================================+
|
|
||||||
| pipewire:outDevice | | NULL | The default playback device to use |
|
|
||||||
+--------------------+-------+-------+------------------------------------+
|
|
||||||
| pipewire:recDevice | | NULL | The default record device to use |
|
|
||||||
+--------------------+-------+-------+------------------------------------+
|
|
||||||
|
|
||||||
.. _host_usage:
|
|
||||||
|
|
||||||
Host usage
|
|
||||||
----------
|
|
||||||
|
|
||||||
By default the host application will simply work however there are some
|
|
||||||
configurable options available. While the host application will accept command
|
|
||||||
line arguments, it is more convenient to create a ``looking-glass-host.ini``
|
|
||||||
config file for persistent configuration changes.
|
|
||||||
|
|
||||||
This file must be placed in the same directory as the Looking Glass host, by
|
|
||||||
default ``C:\Program Files\Looking Glass (host)\``.
|
|
||||||
|
|
||||||
.. _host_capture:
|
|
||||||
|
|
||||||
Capture interface
|
|
||||||
~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
Currently we only provide support for the Windows host application, Linux
|
|
||||||
options are not currently documented.
|
|
||||||
|
|
||||||
Currently under windows there are three capture interfaces available for use,
|
|
||||||
by default the most compatible and commonly supported interface is selected
|
|
||||||
however this can be changed via the ini file with the following configuration:
|
|
||||||
|
|
||||||
.. code:: ini
|
|
||||||
|
|
||||||
[app]
|
|
||||||
capture=<INTERFACE>
|
|
||||||
|
|
||||||
Where ``<INTERFACE>`` is one of ``d12``, ``dxgi`` or ``nvfbc``
|
|
||||||
|
|
||||||
DXGI Desktop Duplication Caveat
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
Due to the design of Microsoft's DXGI API and the decision made to roll
|
|
||||||
hardware cursor updates into the capture stream this interface can suffer from
|
|
||||||
microstutters when the mouse is being moved/updated. This issue only affects
|
|
||||||
guest applications that make use of the hardware cursor instead of compositing
|
|
||||||
the cursor directly, as such titles that do not use a mouse (most FPV games)
|
|
||||||
are not affected.
|
|
||||||
|
|
||||||
Most people will not even notice this, but it needs to be said for those that
|
|
||||||
do so that we do not get flooded with support requests for something we can not
|
|
||||||
fix.
|
|
||||||
|
|
||||||
.. _host_capture_d12:
|
|
||||||
|
|
||||||
DirectX 12 DXGI Desktop Duplication
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
This interface (``D12``) is the default and most performant capture interface
|
|
||||||
for Windows 10 and later having been introduced with the Beta 7 release of
|
|
||||||
Looking Glass. Impressively this new capture engine is faster then NvFBC, and
|
|
||||||
has fewer overheads. This is because this interface can capture and download
|
|
||||||
the captured frames directly from the GPU into the shared memory interface.
|
|
||||||
|
|
||||||
D12 Configuration Options
|
|
||||||
"""""""""""""""""""""""""
|
|
||||||
|
|
||||||
* ``adapter`` - The name of the specific adapter you wish to capture
|
|
||||||
|
|
||||||
* ``output`` - The name of the specific output you wish to capture
|
|
||||||
|
|
||||||
* ``trackDamage`` - Default enabled, this saves bandwidth by only updating and
|
|
||||||
transferring the regions of the capture that have changed since the last
|
|
||||||
frame.
|
|
||||||
|
|
||||||
* ``debug`` - Enables DirectX 12 debugging and validation, only enable this if
|
|
||||||
you're having problems and have been told to do so by our support team. Note
|
|
||||||
that you must have the DirectX SDK installed for this to work.
|
|
||||||
|
|
||||||
* ``downsample`` - See :ref:`host_downsampling`
|
|
||||||
|
|
||||||
* ``HDR16to10`` - Converts HDR16/8bpp content to HDR10/4bpp to save bandwidth.
|
|
||||||
Note that this incurs additional overheads in the guest and may decrease
|
|
||||||
performance. Default enabled, but only active if HDR is enabled in Windows.
|
|
||||||
|
|
||||||
* ``allowRGB24`` - Losslessly packs 32-bit RGBA8 content into 24-bit RGB by
|
|
||||||
omitting the unused alpha channel. This saves bandwidth but requires
|
|
||||||
additional processing so may not yield a performance increase. Might be
|
|
||||||
helpful if you're already bandwidth constrained. Default disabled.
|
|
||||||
|
|
||||||
.. _host_capture_dxgi:
|
|
||||||
|
|
||||||
DirectX 11 DXGI Desktop Duplication
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
This interface (``DXGI``) is the most compatible capture interface for Windows,
|
|
||||||
unfortunately though it does suffer from several drawbacks over other options.
|
|
||||||
If the DirectX 12 (``D12``) capture interface fails to initialize Looking Glass
|
|
||||||
will automatically fall back to using this capture interface instead.
|
|
||||||
|
|
||||||
Due to the design of Microsoft's DXGI API and the decision made to roll
|
|
||||||
hardware cursor updates into the capture stream this interface can suffer from
|
|
||||||
microstutters when the mouse is being moved/updated. This issue only affects
|
|
||||||
guest applications that make use of the hardware cursor instead of compositing
|
|
||||||
the cursor directly, as such titles that do not use a mouse (most FPV games)
|
|
||||||
are not affected.
|
|
||||||
|
|
||||||
The other drawback of this API is the overall system overhead as it requires
|
|
||||||
copying the captured frames into a staging buffer before it is copied into the
|
|
||||||
shared memory area.
|
|
||||||
|
|
||||||
DXGI Configuration Options
|
|
||||||
""""""""""""""""""""""""""
|
|
||||||
|
|
||||||
* ``adapter`` - The name of the specific adapter you wish to capture
|
|
||||||
|
|
||||||
* ``output`` - The name of the specific output you wish to capture
|
|
||||||
|
|
||||||
* ``maxTextures`` - The maximum number of frames to buffer before skipping
|
|
||||||
frames. Default is 4 however realistically the this limit should never be
|
|
||||||
reached unless the Looking Glass client application is not keeping up.
|
|
||||||
|
|
||||||
* ``useAcquireLock`` - Enable locking around ``AcquireNextFrame``. This is an
|
|
||||||
experimental feature and should be left enabled if you're not sure. Default
|
|
||||||
is enabled.
|
|
||||||
|
|
||||||
* ``dwmFlush`` - Use ``DwmFlush`` to sync the capture to the windows
|
|
||||||
presentation interval. This is experimental and may degrade performance.
|
|
||||||
Default is disabled.
|
|
||||||
|
|
||||||
* ``disableDamage`` - Default is false. This disables damage tracking which
|
|
||||||
normally would save bandwidth by only updating and transferring the regions
|
|
||||||
of the capture that have changed since the last frame.
|
|
||||||
|
|
||||||
* ``debug`` - Enables DirectX 11 debugging, only enable this if you're having
|
|
||||||
problems and have been told to do so by our support team. Note that you must
|
|
||||||
have the DirectX SDK installed for this to work.
|
|
||||||
|
|
||||||
* ``allowRGB24`` - Losslessly packs 32-bit RGBA8 content into 24-bit RGB by
|
|
||||||
omitting the unused alpha channel. This saves bandwidth but requires
|
|
||||||
additional processing so may not yield a performance increase. Might be
|
|
||||||
helpful if you're already bandwidth constrained. Default enabled.
|
|
||||||
|
|
||||||
* ``downsample`` - See :ref:`host_downsampling`
|
|
||||||
|
|
||||||
.. _host_capture_nvfbc:
|
|
||||||
|
|
||||||
|
|
||||||
NVIDIA Frame Buffer Capture
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
Due to the NVIDIA SDK License agreement this GPU feature is only available on
|
|
||||||
professional/workstation GPUs such as the Quadro series. It is known however
|
|
||||||
that **all** NVIDIA GPUs are capable of this as both GeForce Experience and
|
|
||||||
Steam are able to make use of it.
|
|
||||||
|
|
||||||
If you are able to make use/enable this this feature it offers lower overall
|
|
||||||
system load and lower latency capture, and does not suffer from the mouse
|
|
||||||
motion stutter issues that DXGI suffers from.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
As of Looking Glass Beta 7, the D12 capture interface is faster then NvFBC
|
|
||||||
while also reducing the memory bandwidth requirements. We recommend
|
|
||||||
migrating to D12 if at all possible.
|
|
||||||
|
|
||||||
To enable its usage use the following configuration in the
|
|
||||||
``looking-glass-host.ini`` file:
|
|
||||||
|
|
||||||
.. code:: ini
|
|
||||||
|
|
||||||
[app]
|
|
||||||
capture=nvfbc
|
|
||||||
|
|
||||||
If this feature is unavailable to you the host application will fail to start
|
|
||||||
and the host log will contain an error stating that the feature is not
|
|
||||||
available.
|
|
||||||
|
|
||||||
NvFBC Configuration Options
|
|
||||||
"""""""""""""""""""""""""""
|
|
||||||
|
|
||||||
* ``decoupleCursor`` - This option prevents the cursor from being composited
|
|
||||||
before capture onto the captured frame, and instead sends cursor updates to
|
|
||||||
the client independent of frame updates. Default is true.
|
|
||||||
|
|
||||||
* ``diffRes`` - The resolution of the differential map, see the NvFBC capture
|
|
||||||
SDK documentation for more information. Default is 128.
|
|
||||||
|
|
||||||
* ``adapterIndex`` - If you have multiple adapters, you can select which to use
|
|
||||||
with this option. Default is to select the first valid device.
|
|
||||||
|
|
||||||
* ``dwmFlush`` - Use ``DwmFlush`` to sync the capture to the windows
|
|
||||||
presentation interval. This is experimental and may degrade performance.
|
|
||||||
Default is disabled.
|
|
||||||
|
|
||||||
* ``noHDR`` - Force NvFBC to capture HDR content as SDR. Default is enabled.
|
|
||||||
|
|
||||||
* ``downsample`` - See :ref:`host_downsampling`
|
|
||||||
|
|
||||||
|
|
||||||
This capture interface also looks for and reads the value of the system
|
|
||||||
environment variable ``NVFBC_PRIV_DATA`` if it has been set, documentation on
|
|
||||||
its usage however is unavailable (Google is your friend).
|
|
||||||
|
|
||||||
.. _host_select_ivshmem:
|
|
||||||
|
|
||||||
Selecting an IVSHMEM device
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
For those attaching multiple IVSHMEM devices to their Virtual Machines, you must
|
|
||||||
configure the Looking Glass host to use the correct device. By default the first
|
|
||||||
device is selected.
|
|
||||||
|
|
||||||
The ``os:shmDevice`` option configures which device is used. These are ordered
|
|
||||||
by PCI slot and count up from 0 (default), with 0 being the first IVSHMEM device
|
|
||||||
in the lowest slot.
|
|
||||||
|
|
||||||
.. code:: ini
|
|
||||||
|
|
||||||
[os]
|
|
||||||
; Select the second IVSHMEM device
|
|
||||||
shmDevice=1
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
``os:shmDevice`` ignores the actual PCI slot number, instead selecting the
|
|
||||||
*N*\th slot occupied by an IVSHMEM device. For example: with only two IVSHMEM
|
|
||||||
devices in slots 0x03 and 0x05, the device in slot 0x03 will be referred to
|
|
||||||
by *0* (first shm device), and the device in 0x05 by *1* (second shm device).
|
|
||||||
|
|
||||||
PCI slot numbers are visible in Device Manager:
|
|
||||||
|
|
||||||
1. Double-click any "IVSHMEM device" in Device Manager (``devmgmt.msc``)
|
|
||||||
2. Find the slot number in the "Location:" field. (e.g. PCI slot 5)
|
|
||||||
|
|
||||||
You can also find a listing of IVSHMEM devices in the ``looking-glass-host.txt``
|
|
||||||
log file, with slot numbers shown next to "device" (asterisk indicates currently
|
|
||||||
selected device)::
|
|
||||||
|
|
||||||
[I] 19989544 … IVSHMEM 0 on bus 0x6, device 0x3, function 0x0
|
|
||||||
[I] 19990438 … IVSHMEM 1* on bus 0x6, device 0x5, function 0x0
|
|
||||||
|
|
||||||
.. _host_downsampling:
|
|
||||||
|
|
||||||
Downsampling
|
|
||||||
~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The host application is able to downsample the captured frame before transfer
|
|
||||||
to the client application, this provides an opportunity to save some bandwidth
|
|
||||||
on memory constrained systems. It also makes it possible to run the guest at a
|
|
||||||
substantially higher resolution then your actual monitor for a super scaling
|
|
||||||
type effect, without having to incur the bandwidth penalty that would normally
|
|
||||||
occur when doing this.
|
|
||||||
|
|
||||||
The configuration for this is fairly straightforward and is defined as set of
|
|
||||||
rules to determine when to perform this downsampling. The format is as follows:
|
|
||||||
|
|
||||||
.. code::
|
|
||||||
|
|
||||||
(>|>=)(WIDTH)x(HEIGHT):(TARGET WIDTH)x(TARGET HEIGHT)
|
|
||||||
|
|
||||||
**Examples:**
|
|
||||||
|
|
||||||
.. code:: ini
|
|
||||||
|
|
||||||
; Downsample exactly 3840x2160 to 1920x1080
|
|
||||||
downsample=3840x2160:1920x1080
|
|
||||||
|
|
||||||
; Downsample anything greater then 1920x1080 to 1920x1080
|
|
||||||
downsample=>1920x1080:1920x1080
|
|
||||||
|
|
||||||
; Downsample 3840x2160 to 1920x1080, or 3840x2400 to 1920x1200
|
|
||||||
downsample=3840x2160:1920x1080,3840x2400:1920x1200
|
|
||||||
|
|||||||
@@ -1,11 +1,14 @@
|
|||||||
|
Anime4K
|
||||||
backend
|
backend
|
||||||
backtrace
|
backtrace
|
||||||
BigNavi
|
BigNavi
|
||||||
borderless
|
borderless
|
||||||
Brindus
|
Brindus
|
||||||
|
cadence
|
||||||
cgroups
|
cgroups
|
||||||
clang
|
clang
|
||||||
cmake
|
cmake
|
||||||
|
compositor
|
||||||
config
|
config
|
||||||
CopySleep
|
CopySleep
|
||||||
Debian
|
Debian
|
||||||
@@ -22,6 +25,7 @@ downsampling
|
|||||||
downscaler
|
downscaler
|
||||||
downscaling
|
downscaling
|
||||||
evdev
|
evdev
|
||||||
|
ExtraMode
|
||||||
Flatpak
|
Flatpak
|
||||||
framebuffer
|
framebuffer
|
||||||
fullscreen
|
fullscreen
|
||||||
@@ -31,6 +35,7 @@ gnif
|
|||||||
Guanzhong
|
Guanzhong
|
||||||
hypervisor
|
hypervisor
|
||||||
i3
|
i3
|
||||||
|
IddCx
|
||||||
ie
|
ie
|
||||||
imgui
|
imgui
|
||||||
ini
|
ini
|
||||||
@@ -55,21 +60,29 @@ msys
|
|||||||
multisampling
|
multisampling
|
||||||
namespace
|
namespace
|
||||||
Navi
|
Navi
|
||||||
|
NvFBC
|
||||||
Nvidia
|
Nvidia
|
||||||
overlayed
|
overlayed
|
||||||
|
overrun
|
||||||
pacman
|
pacman
|
||||||
passthrough
|
passthrough
|
||||||
performant
|
performant
|
||||||
pre
|
pre
|
||||||
|
prebuilt
|
||||||
protanope
|
protanope
|
||||||
QEMU
|
QEMU
|
||||||
|
quadraphonic
|
||||||
Quadro
|
Quadro
|
||||||
radeon
|
radeon
|
||||||
realtime
|
realtime
|
||||||
renderer
|
renderer
|
||||||
repo
|
repo
|
||||||
|
resampler
|
||||||
Rubenstein
|
Rubenstein
|
||||||
runtime
|
runtime
|
||||||
|
scanout
|
||||||
|
Scream
|
||||||
|
scRGB
|
||||||
shm
|
shm
|
||||||
spencercw
|
spencercw
|
||||||
submodule
|
submodule
|
||||||
@@ -78,6 +91,7 @@ systemd
|
|||||||
th
|
th
|
||||||
Threadripper
|
Threadripper
|
||||||
toolchain
|
toolchain
|
||||||
|
tooltip
|
||||||
tritanope
|
tritanope
|
||||||
tunable
|
tunable
|
||||||
uaccess
|
uaccess
|
||||||
@@ -85,12 +99,14 @@ udev
|
|||||||
UEFI
|
UEFI
|
||||||
uncheck
|
uncheck
|
||||||
uncomment
|
uncomment
|
||||||
|
underrun
|
||||||
Unigine
|
Unigine
|
||||||
unix
|
unix
|
||||||
upscaled
|
upscaled
|
||||||
upscaler
|
upscaler
|
||||||
upscales
|
upscales
|
||||||
upscaling
|
upscaling
|
||||||
|
VirtIO
|
||||||
VM
|
VM
|
||||||
vsync
|
vsync
|
||||||
wayland
|
wayland
|
||||||
|
|||||||
Reference in New Issue
Block a user