mirror of
https://github.com/gnif/LookingGlass.git
synced 2026-08-22 07:01:30 +00:00
[docs] guide: document current Looking Glass features
This commit is contained in:
Geoffrey McRae
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
|
||||
########
|
||||
Build the Linux client
|
||||
######################
|
||||
|
||||
The following instructions will help you build Looking Glass from source code.
|
||||
Before attempting this, you should have a basic understanding of
|
||||
how to use the shell.
|
||||
The Looking Glass Client is currently distributed as source code. Building it
|
||||
is a normal part of installation, not an optional developer step. These
|
||||
instructions require basic familiarity with a Linux shell.
|
||||
|
||||
.. _download_source:
|
||||
|
||||
@@ -32,8 +32,10 @@ Developers can clone the source code repo with ``git``.
|
||||
|
||||
.. note::
|
||||
|
||||
When using the latest bleeding-edge client version,
|
||||
you *MUST* download and install the corresponding host application.
|
||||
The current client, IDD and OBS plugin must come from the same Looking Glass
|
||||
release. Bleeding-edge builds must be paired with their matching
|
||||
bleeding-edge components. Legacy Host users must instead use the complete
|
||||
matching B7 stack described in :ref:`legacy_host_policy`.
|
||||
|
||||
.. _build_client_section:
|
||||
|
||||
@@ -75,6 +77,7 @@ Required dependencies
|
||||
- ``libfontconfig-dev``
|
||||
- ``libgmp-dev``
|
||||
- ``libspice-protocol-dev``
|
||||
- ``libxkbcommon-dev``
|
||||
- ``make``
|
||||
- ``nettle-dev``
|
||||
- ``pkg-config``
|
||||
@@ -101,10 +104,10 @@ feature is disabled when running :ref:`cmake <client_building>`.
|
||||
- ``libxss-dev``
|
||||
- ``libxcursor-dev``
|
||||
- ``libxpresent-dev``
|
||||
- ``libxrandr-dev``
|
||||
|
||||
- Disable with ``cmake -DENABLE_WAYLAND=no ..``
|
||||
|
||||
- ``libxkbcommon-dev``
|
||||
- ``libwayland-bin``
|
||||
- ``libwayland-dev``
|
||||
|
||||
@@ -113,6 +116,7 @@ feature is disabled when running :ref:`cmake <client_building>`.
|
||||
- ``libpipewire-0.3-dev``
|
||||
- ``libpulse-dev``
|
||||
- ``libsamplerate0-dev``
|
||||
- ``libusbredirparser-dev``
|
||||
|
||||
- Disable with ``cmake -DENABLE_PIPEWIRE=no ..``
|
||||
|
||||
@@ -122,6 +126,10 @@ feature is disabled when running :ref:`cmake <client_building>`.
|
||||
|
||||
- ``libpulse-dev``
|
||||
|
||||
- Disable USB audio with ``cmake -DENABLE_USB_AUDIO=no ..``
|
||||
|
||||
- ``libusbredirparser-dev`` version 0.7.1 or newer
|
||||
|
||||
``libsamplerate0-dev`` is required whenever audio support remains enabled.
|
||||
|
||||
.. _client_deps_recommended:
|
||||
@@ -141,20 +149,21 @@ You can fetch these dependencies with the following command:
|
||||
|
||||
.. warning::
|
||||
|
||||
Do not just blindly install the list below, check if you are using PipeWire
|
||||
or PulseAudio and adjust the list accordingly. Installing PipeWire libraries
|
||||
on a PulseAudio system will result in a broken partial PipeWire install.
|
||||
|
||||
If you are not already using PipeWire we highly recommend you upgrade,
|
||||
Looking Glass does not support audio input (microphone) with PulseAudio.
|
||||
The command below builds both PipeWire and PulseAudio playback backends.
|
||||
Omit one development package only when also disabling its backend in CMake.
|
||||
Microphone recording requires PipeWire; the current PulseAudio backend is
|
||||
playback-only.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
apt-get install binutils cmake fonts-dejavu-core libdw-dev libfontconfig-dev \
|
||||
libunwind-dev gcc g++ pkg-config libegl-dev libgl-dev libgles-dev \
|
||||
libspice-protocol-dev nettle-dev libx11-dev libxcursor-dev libxi-dev libxinerama-dev \
|
||||
libxpresent-dev libxss-dev libxkbcommon-dev libwayland-dev \
|
||||
libpipewire-0.3-dev libpulse-dev libsamplerate0-dev
|
||||
apt-get install binutils cmake make fonts-dejavu-core libdw-dev \
|
||||
libfontconfig-dev libgmp-dev libunwind-dev gcc g++ pkg-config \
|
||||
libegl-dev libgl-dev libgles-dev libspice-protocol-dev nettle-dev \
|
||||
libx11-dev libxcursor-dev libxfixes-dev libxi-dev libxinerama-dev \
|
||||
libxpresent-dev libxrandr-dev libxss-dev libxkbcommon-dev \
|
||||
libwayland-bin libwayland-dev \
|
||||
libpipewire-0.3-dev libpulse-dev libsamplerate0-dev \
|
||||
libusbredirparser-dev
|
||||
|
||||
You may omit some dependencies if you disable the feature which requires them
|
||||
when running :ref:`cmake <client_building>`.
|
||||
@@ -219,8 +228,15 @@ it directly from the build directory:
|
||||
|
||||
.. _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::
|
||||
|
||||
|
||||
11
doc/conf.py
11
doc/conf.py
@@ -22,7 +22,7 @@ from lgrelease import release
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'Looking Glass'
|
||||
copyright = '2024, Looking Glass team'
|
||||
copyright = '2026, Looking Glass team'
|
||||
author = 'Geoffrey McRae and the Looking Glass team'
|
||||
|
||||
rst_prolog = """
|
||||
@@ -55,7 +55,7 @@ else:
|
||||
spelling_word_list_filename = [os.path.join(os.path.dirname(__file__), 'words.txt')]
|
||||
|
||||
# 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
|
||||
# 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
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
html_theme = 'lookingglass'
|
||||
|
||||
html_theme_path = [
|
||||
'theme/',
|
||||
]
|
||||
|
||||
html_theme_options = {
|
||||
'logo_only': True,
|
||||
'prev_next_buttons_location': 'both',
|
||||
'style_nav_header_background': '#343131',
|
||||
}
|
||||
|
||||
|
||||
@@ -1,17 +1,9 @@
|
||||
/* Center content in the RTD theme */
|
||||
@media screen and (min-width: 1100px) {
|
||||
.wy-nav-content-wrap {
|
||||
margin-left: auto;
|
||||
}
|
||||
|
||||
.wy-nav-content {
|
||||
margin: auto;
|
||||
}
|
||||
}
|
||||
|
||||
@media screen and (min-width:769px) and (max-width:1420px) {
|
||||
/* Align content with the navigation menu */
|
||||
@media screen and (min-width: 769px) {
|
||||
.wy-nav-content-wrap {
|
||||
background: #edf0f2;
|
||||
margin-left: 300px;
|
||||
padding-left: 12px;
|
||||
}
|
||||
|
||||
.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 */
|
||||
kbd {
|
||||
background-color: #eee;
|
||||
@@ -32,3 +49,340 @@ kbd {
|
||||
padding: 2px 4px;
|
||||
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?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This YouTube video featured created by the author features a detailed
|
||||
explanation:
|
||||
The Windows IDD creates a virtual monitor and places completed frames in an
|
||||
IVSHMEM region shared with Linux. The client imports the newest frame, renders
|
||||
it and returns input through the available transport. The image is not encoded
|
||||
as a video stream, which avoids codec latency and quality loss.
|
||||
|
||||
https://www.youtube.com/watch?v=U44lihtNVVM
|
||||
See :doc:`overview` for the current components. A detailed video explanation
|
||||
is also available at https://www.youtube.com/watch?v=U44lihtNVVM.
|
||||
|
||||
.. _can_i_feed_the_vm_directly_into_obs:
|
||||
|
||||
Can I feed the VM directly into OBS?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Looking Glass now features a functional :doc:`OBS plugin <obs>`, which acts as
|
||||
another Looking Glass client, but instead feeds the captured frames into OBS.
|
||||
Yes. The :doc:`OBS plugin <obs>` is an independent frame consumer and does not
|
||||
capture the client window.
|
||||
|
||||
.. _why_is_my_ups_so_low:
|
||||
|
||||
Why is my UPS (Updates Per Second) so low?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Why is UPS lower than the guest refresh rate?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
There are several reasons why this can happen, the most common are your
|
||||
capture resolution, or refresh rate. The windows capture methods currently
|
||||
struggle to capture high resolutions under certain circumstances.
|
||||
UPS counts frames delivered to that consumer, not every frame Windows may
|
||||
render. The IDD publishes to the deadline requested by the fastest active
|
||||
client and can skip guest frames that have already been superseded. This saves
|
||||
memory bandwidth without deliberately adding a frame of latency.
|
||||
|
||||
Some titles do some strange things at early initialization that cause
|
||||
capture performance issues. One such title is the Unigine Valley
|
||||
benchmark where the capture rate is limited to 1/2 the actual rate. For
|
||||
an unknown reason to both myself and the Unigine developers a simple
|
||||
task switch (alt+tab) in and out resolves the issue. This is not a
|
||||
Looking Glass bug.
|
||||
If UPS is below the active consumer's requested rate, use
|
||||
:ref:`client_performance` to locate the slow stage. High resolution, software
|
||||
processing, memory bandwidth, host scheduling and compositor presentation can
|
||||
all impose a lower limit.
|
||||
|
||||
.. _is_my_gpu_supported:
|
||||
|
||||
Is my GPU supported?
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
Is a passed-through GPU required?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Your guest GPU almost certainly supports DXGI. Use DxDiag to confirm
|
||||
that you have support for WDDM 1.2 or greater.
|
||||
No. The IDD can create an SDR display using software processing when it cannot
|
||||
use a Windows render adapter. A hardware adapter is strongly recommended for
|
||||
lower latency, higher refresh rates, HDR and cadence scheduling.
|
||||
|
||||
The server-side (guest) probing error "Capture is not possible,
|
||||
unsupported device or driver" indicates NVidia duplication has failed,
|
||||
not that DXGI has failed. You can fix the error by specifying
|
||||
``-c DXGI``
|
||||
The Linux client still needs an EGL-capable host graphics driver. Direct
|
||||
DMA-BUF import depends on the host GPU and driver; the client falls back to a
|
||||
copy when it is unavailable.
|
||||
|
||||
.. _why_do_i_need_spice_if_i_dont_want_a_spice_display_device:
|
||||
|
||||
Why do I need Spice if I don't want a Spice display device?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Do I need SPICE?
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
You don't need Display Spice enabled. Looking Glass has a Spice client
|
||||
built in to provide some conveniences, but you can disable it with the
|
||||
"-s" argument.
|
||||
SPICE is not required for the primary IDD video or direct input paths. It is
|
||||
still useful for clipboard, audio, input fallback and automatic video fallback.
|
||||
These services are selected independently.
|
||||
|
||||
.. note::
|
||||
|
||||
Without Spice, Looking Glass cannot send mouse/keyboard input to the guest
|
||||
and clipboard synchronization is disabled.
|
||||
Set ``spice:enable=no`` or use ``-s`` to disable SPICE completely. Disable an
|
||||
individual service with ``spice:input``, ``spice:clipboard`` or
|
||||
``spice:audio`` instead when the other services are still wanted.
|
||||
|
||||
.. _where_is_the_host_application_for_linux:
|
||||
|
||||
Where is the host application for Linux?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Which application runs on Linux?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The "Windows host application" is actually the display server, which
|
||||
runs in the guest VM. The only thing that needs to run in your Linux
|
||||
host OS is the ``looking-glass-client`` application.
|
||||
The Looking Glass Client runs on the Linux host operating system. The IDD runs
|
||||
inside the Windows guest. The older product named the **Host Application** is
|
||||
a legacy Windows producer; “Host” in that name does not mean the Linux host
|
||||
OS.
|
||||
|
||||
You can :ref:`build <host_linux_on_linux>` a version of the host for Linux as
|
||||
well.
|
||||
Input and window system
|
||||
-----------------------
|
||||
|
||||
.. _gnome_wayland_decorations:
|
||||
|
||||
Why is there no title bar on GNOME? / Why can't I resize the window on GNOME?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Why is there no title bar on GNOME Wayland?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This happens because GNOME on Wayland doesn't support the `standard protocol`_
|
||||
for server-side decorations, and Looking Glass doesn't implement its own
|
||||
decorations.
|
||||
GNOME does not implement the standard Wayland server-side decoration
|
||||
protocol. Build Looking Glass with libdecor support:
|
||||
|
||||
The easiest solution is to build Looking Glass with `libdecor`_ support.
|
||||
Install the ``libdecor-0-dev`` package. If your distribution lacks this package
|
||||
or any equivalents, you must build it from `source code <libdecor_>`_.
|
||||
.. code:: bash
|
||||
|
||||
You can then build the the client with libdecor support by passing
|
||||
``-DENABLE_LIBDECOR=ON`` to ``cmake``.
|
||||
cmake -DENABLE_LIBDECOR=ON ../
|
||||
|
||||
An alternative solution is to hold down the Super key (Windows key on most
|
||||
keyboards), then right click Looking Glass. This should bring up a menu,
|
||||
which will allow you to move the window and resize it.
|
||||
|
||||
.. warning::
|
||||
Libdecor support is provided for the convenience of our Wayland users on
|
||||
GNOME, however it is not a priority feature and may break, please seek
|
||||
alternatives if you require stable operation.
|
||||
|
||||
.. _standard protocol: https://wayland.app/protocols/xdg-decoration-unstable-v1
|
||||
.. _libdecor: https://gitlab.freedesktop.org/libdecor/libdecor
|
||||
|
||||
Mouse
|
||||
-----
|
||||
Install ``libdecor-0-dev`` first on Debian-based systems. Alternatively, hold
|
||||
the Super key and right-click the window to use the compositor's move and
|
||||
resize menu.
|
||||
|
||||
.. _the_mouse_is_jumpy_slow_laggy_when_using_spice:
|
||||
|
||||
The mouse is jumpy, slow, laggy when using SPICE
|
||||
Why is SPICE fallback mouse movement different?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Please be sure to install the SPICE guest tools from
|
||||
https://www.spice-space.org/download.html#windows-binaries.
|
||||
The IDD's direct input path uses absolute positioning for normal desktop use
|
||||
and relative movement in capture mode. SPICE input is relative-only, so guest
|
||||
mouse acceleration can change its feel or cause temporary position error.
|
||||
|
||||
.. _mouse_desync_when_entering:
|
||||
|
||||
The mouse position is wrong when entering the window
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is due to windows mouse acceleration, it can be disabled by
|
||||
following one of these methods:
|
||||
|
||||
- Disabling pointer precision (Control Panel > Mouse > Pointer Options
|
||||
> Uncheck Enhance pointer precision)
|
||||
- By changing the acceleration behavior with the following registry
|
||||
magic:
|
||||
http://donewmouseaccel.blogspot.com.au/2010/03/markc-windows-7-mouse-acceleration-fix.html
|
||||
(Contrary to the title this works just fine on Windows 10)
|
||||
Use the direct IDD input path when available. For a game, use capture mode and
|
||||
consider ``input:rawMouse=yes``.
|
||||
|
||||
.. _the_cursor_position_doesnt_update_until_i_click:
|
||||
|
||||
The cursor position doesn't update until I click
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Should I add a virtual tablet?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Make sure you have removed the Virtual Tablet Device from the Virtual
|
||||
Machine. Due to the design of Windows, absolute pointing devices break
|
||||
applications/games that require cursor capture, and as such Looking Glass
|
||||
does not support them.
|
||||
No. Looking Glass does not require an additional virtio tablet, mouse or
|
||||
keyboard. Direct IDD input provides its own absolute and relative devices, and
|
||||
SPICE fallback uses the VM's default PS/2 input devices.
|
||||
|
||||
Audio
|
||||
-----
|
||||
|
||||
As of B6 Looking Glass supports audio input and output via SPICE.
|
||||
Does Looking Glass support microphone input and surround sound?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. _faq_win:
|
||||
Yes. The recommended emulated USB Audio 2.0 device provides stereo,
|
||||
quadraphonic, 5.1 and 7.1 playback plus stereo recording at rates up to
|
||||
192 kHz. Classic SPICE audio also provides playback and recording. Client
|
||||
microphone recording currently requires the PipeWire backend. See
|
||||
:doc:`audio`.
|
||||
|
||||
Windows
|
||||
-------
|
||||
Legacy Host Application
|
||||
-----------------------
|
||||
|
||||
.. _nvfbc_nvidia_capture_api_doesnt_work:
|
||||
|
||||
NvFBC (NVIDIA Capture API) doesn't work
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
NvFBC is only supported on professional-grade GPUs, and will not function on
|
||||
consumer-grade cards like those from the GeForce series.
|
||||
|
||||
If you have a supported card, you can enable NVFBC by adding the following
|
||||
to the host ini file, found at
|
||||
``%ProgramFiles%\Looking Glass (host)\looking-glass-host.ini``
|
||||
(create one if it doesn't exist):
|
||||
|
||||
.. code:: INI
|
||||
|
||||
[app]
|
||||
capture=nvfbc
|
||||
|
||||
.. _the_screen_stops_updating_when_left_idle_for_a_time:
|
||||
|
||||
The screen stops updating when left idle for a time
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Windows is likely turning off the display to save power, you can prevent
|
||||
this by adjusting the ``Power Options`` in the control panel.
|
||||
The sections below apply only to the legacy Windows Host Application. New
|
||||
installations should use the IDD. See :ref:`legacy_host_policy`.
|
||||
|
||||
.. _faq_host:
|
||||
|
||||
Host
|
||||
----
|
||||
Where is the legacy Host log?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Where is the log?
|
||||
~~~~~~~~~~~~~~~~~
|
||||
The application log is:
|
||||
|
||||
The log file for the host application is located at::
|
||||
``%ProgramData%\Looking Glass (host)\looking-glass-host.txt``
|
||||
|
||||
%ProgramData%\Looking Glass (host)\looking-glass-host.txt
|
||||
The service log is:
|
||||
|
||||
You can also open the log file by right clicking on the Looking Glass
|
||||
system tray icon, then clicking *Open Log File*. This opens the log
|
||||
file in Notepad.
|
||||
|
||||
The log file for the looking glass service is located at::
|
||||
|
||||
%ProgramData%\Looking Glass (host)\looking-glass-host-service.txt
|
||||
|
||||
This is useful for troubleshooting errors related to the host
|
||||
application not starting.
|
||||
|
||||
High priority capture using DXGI and Secure Desktop (UAC) capture support
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
By default Windows gives priority to the foreground application for any
|
||||
GPU work which causes issues with capture if the foreground application
|
||||
is consuming 100% of the available GPU resources. The looking glass host
|
||||
application is able to increase the kernel GPU thread to realtime
|
||||
priority which fixes this, but in order to do so it must run as the
|
||||
``SYSTEM`` user account. To do this, Looking Glass needs to run as a
|
||||
service. This can be accomplished by either using the NSIS installer
|
||||
which will do this for you, or you can use the following command to
|
||||
Install the service manually:
|
||||
|
||||
::
|
||||
|
||||
looking-glass-host.exe InstallService
|
||||
|
||||
To remove the service use the following command:
|
||||
|
||||
::
|
||||
|
||||
looking-glass-host.exe UninstallService
|
||||
|
||||
This will also enable the host application to capture the secure desktop
|
||||
which includes things like the lock screen and UAC prompts.
|
||||
``%ProgramData%\Looking Glass (host)\looking-glass-host-service.txt``
|
||||
|
||||
.. _faq_host_admin_privs:
|
||||
|
||||
Why does the host require Administrator privileges?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Why does the legacy Host require administrator privileges?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is intentional for several reasons.
|
||||
The legacy capture APIs use privileged functions for GPU scheduling, NvFBC
|
||||
setup and secure-desktop capture. The installer runs it as a Windows service
|
||||
under the SYSTEM account. This is not how the current IDD is configured.
|
||||
|
||||
1. NvFBC requires a system wide hook to correctly obtain the cursor
|
||||
position as NVIDIA decided to not provide this as part of the cursor
|
||||
updates.
|
||||
2. NvFBC requires administrator level access to enable the interface in
|
||||
the first place.
|
||||
3. General capture performance is boosted by taking advantage of high priority
|
||||
scheduling with SYSTEM level privileges.
|
||||
.. _nvfbc_nvidia_capture_api_doesnt_work:
|
||||
|
||||
NvFBC (NVIDIA Frame Buffer Capture)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Why does NvFBC not work?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Why can't I compile NvFBC support into the host?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
NvFBC is a legacy Host capture method and requires supported NVIDIA hardware
|
||||
and SDK licensing. It is not part of the IDD path.
|
||||
|
||||
You must download and install the NVidia Capture SDK. Please note that
|
||||
by doing so you will be agreeing to NVIDIA's SDK License agreement.
|
||||
.. _the_screen_stops_updating_when_left_idle_for_a_time:
|
||||
|
||||
Why does a legacy captured display stop when idle?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Windows may turn off the physical or dummy display captured by the legacy
|
||||
Host. Disable display sleep for that monitor. The IDD virtual-monitor path does
|
||||
not require a physical display.
|
||||
|
||||
.. _a_note_about_ivshmem_and_scream_audio:
|
||||
|
||||
Why doesn't Looking Glass work with Scream over IVSHMEM?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Can Scream and Looking Glass share IVSHMEM?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. warning::
|
||||
Using IVSHMEM with Scream may interfere with Looking Glass, as they may try
|
||||
to use the same device.
|
||||
Do not use Scream with Looking Glass. Use the built-in classic SPICE or USB
|
||||
audio path instead. In particular, Scream's IVSHMEM transport can select or
|
||||
interfere with the shared device used for Looking Glass frames.
|
||||
|
||||
Please do not use the IVSHMEM plugin for Scream.
|
||||
To fix this issue, use the default network transfer method.
|
||||
The IVSHMEM method induces additional latency that is built into its
|
||||
implementation. When using VirtIO for a network device the VM is already using
|
||||
a highly optimized memory copy anyway so there is no need to make another one.
|
||||
Technical details
|
||||
-----------------
|
||||
|
||||
If you insist on using IVSHMEM for Scream—despite its inferiority to the
|
||||
default network implementation—the Windows Host Application can be told
|
||||
what device to use. Edit the file
|
||||
``%ProgramFiles%\Looking Glass (host)\looking-glass-host.ini``,
|
||||
(create one if it doesn't exist)
|
||||
then, you can add the ``os:shmDevice`` option like so:
|
||||
|
||||
.. code:: INI
|
||||
|
||||
[os]
|
||||
shmDevice=1
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
tech_faq
|
||||
|
||||
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 is an open-source application that allows the use of a KVM
|
||||
(Kernel-based Virtual Machine) configured for VGA PCI Pass-through
|
||||
without an attached physical monitor, keyboard or mouse. This is the
|
||||
final step required to move away from dual booting with other operating
|
||||
systems for legacy programs that require high-performance graphics.
|
||||
Looking Glass is an open-source, low-latency way to use a Windows virtual
|
||||
machine from Linux. The current setup uses a virtual display in the Windows
|
||||
guest, shared memory for frames, and a native Linux client for display and
|
||||
input.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
overview
|
||||
requirements
|
||||
quickstart
|
||||
|
||||
build
|
||||
install
|
||||
|
||||
usage
|
||||
troubleshooting
|
||||
obs
|
||||
faq
|
||||
tech_faq
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
@@ -39,6 +41,20 @@ Donate:
|
||||
* `Ko-Fi <https://ko-fi.com/lookingglass>`_
|
||||
* `Patreon <https://www.patreon.com/gnif>`_
|
||||
* `PayPal <https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ESQ72XUPGKXRY>`_
|
||||
* BTC - 14ZFcYjsKPiVreHqcaekvHGL846u3ZuT13
|
||||
* ETH - 0x6f8aEe454384122bF9ed28f025FBCe2Bce98db85
|
||||
* XMR - 47xM4zG7b2tEj4mnSywHve4ydZzn3wzhf22snDRB7aSEcXrgUBpoT2Z4phTnyFMi1sMyQtHbdufMYRQ2PzMn3PGUJAE1dpc
|
||||
|
||||
Expand a cryptocurrency address to copy it:
|
||||
|
||||
.. 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
|
||||
############
|
||||
|
||||
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::
|
||||
|
||||
|
||||
install_libvirt
|
||||
install_host
|
||||
install_idd
|
||||
install_client
|
||||
install_host
|
||||
|
||||
@@ -8,15 +8,21 @@ Client Application Installation
|
||||
For Linux
|
||||
---------
|
||||
|
||||
The Looking Glass client receives frames from the :ref:`host <host_install>` to
|
||||
display on your screen. It also handles input, and can optionally share the
|
||||
system clipboard with your guest OS through SPICE.
|
||||
The Looking Glass Client receives frames from the Windows producer and displays
|
||||
them on Linux. It also handles input, audio, overlays and optional SPICE
|
||||
services.
|
||||
|
||||
First you must build the client from source, see :ref:`building`. Once you have
|
||||
built the client, you can install it. Run the following as root::
|
||||
There are currently no Linux distribution packages for the client. First
|
||||
:ref:`build it from source <build_client_section>`, then run the following from
|
||||
the client build directory as root::
|
||||
|
||||
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:
|
||||
.. _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
|
||||
:ref:`client <client_install>`—be it on the host OS (hypervisor) or another
|
||||
Virtual Machine—through a low-latency transfer protocol over shared memory.
|
||||
|
||||
You can get the host program in two ways:
|
||||
|
||||
- Download a pre-built binary from https://looking-glass.io/downloads
|
||||
(**Recommended**)
|
||||
- Download a matching legacy binary from https://looking-glass.io/downloads
|
||||
|
||||
- Download the source code as described in :ref:`building`, then
|
||||
:ref:`build the host <host_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
|
||||
command line can be done with flags. You can list all available flags by
|
||||
running ``looking-glass-host-setup.exe /?``.
|
||||
|
||||
Legacy configuration
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
host_usage
|
||||
|
||||
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
|
||||
#########################
|
||||
|
||||
This article assumes you already have a fully functional `libvirt` domain with
|
||||
PCI passthrough working. If you use `virt-manager`, this guide also applies to
|
||||
you, since virt-manager uses `libvirt` as its back end.
|
||||
This article assumes you already have a working `libvirt` Windows virtual
|
||||
machine. If you use `virt-manager`, this guide also applies because
|
||||
`virt-manager` uses `libvirt` as its back end. A passed-through or virtual GPU
|
||||
is strongly recommended, but the IDD can start in software mode without one.
|
||||
|
||||
.. _libvirt_determining_memory:
|
||||
|
||||
Determining memory
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You will first need to calculate the memory size to be suitable for your desired
|
||||
maximum resolution using the following formula:
|
||||
Calculate the base IVSHMEM requirement as:
|
||||
|
||||
.. 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}
|
||||
|
||||
2^{\lceil \log_2(\text {required size in MiB}) \rceil} = \text{ total MiB}
|
||||
|
||||
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.
|
||||
If a configured mode does not fit, the IDD omits it from the Windows mode list.
|
||||
If a client-requested dynamic resolution does not fit, the helper refuses it
|
||||
and reports the minimum power-of-two size to configure. The current IDD does
|
||||
not publish a truncated frame.
|
||||
|
||||
.. note::
|
||||
Increasing this value beyond what you need does not yield any performance
|
||||
improvements, it simply will block access to that RAM making it unusable by
|
||||
your system.
|
||||
Increasing this value beyond what you need does not improve performance. It
|
||||
only reserves more host RAM for the VM.
|
||||
|
||||
.. list-table:: Common Values
|
||||
:widths: 50 25 25
|
||||
:header-rows: 1
|
||||
.. list-table:: Common IDD values
|
||||
:widths: 60 40
|
||||
:header-rows: 1
|
||||
|
||||
* - Resolution
|
||||
- Standard Dynamic Range
|
||||
- High Dynamic Range (HDR) :ref:`* <libvirt_determining_memory_hdr>`
|
||||
* - 1920x1080 (1080p)
|
||||
- 32
|
||||
- 64
|
||||
* - 1920x1200 (1200p)
|
||||
- 32
|
||||
- 64
|
||||
* - 2560x1440 (1440p)
|
||||
- 64
|
||||
- 128
|
||||
* - 3840x2160 (2160p/4K)
|
||||
- 128
|
||||
- 256
|
||||
* - Maximum resolution
|
||||
- Total IVSHMEM size (MiB)
|
||||
* - 1920x1080 (1080p)
|
||||
- 64
|
||||
* - 1920x1200
|
||||
- 64
|
||||
* - 2560x1440 (1440p)
|
||||
- 128
|
||||
* - 3440x1440
|
||||
- 128
|
||||
* - 3840x2160 (4K)
|
||||
- 256
|
||||
* - 5120x1440
|
||||
- 128
|
||||
* - 5120x2880 (5K)
|
||||
- 256
|
||||
* - 7680x4320 (8K)
|
||||
- 512
|
||||
|
||||
.. _libvirt_determining_memory_hdr:
|
||||
|
||||
.. warning::
|
||||
While Looking Glass can capture and display HDR, at the time of writing
|
||||
neither Xorg or Wayland can make use of it and it will be converted by the
|
||||
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.
|
||||
HDR uses the same 32-bit IDD transport allocation as SDR, so it does not double
|
||||
the IVSHMEM requirement. Native Linux HDR presentation has separate compositor
|
||||
and display requirements; see :ref:`client_hdr`.
|
||||
|
||||
.. _libvirt_ivshmem:
|
||||
|
||||
@@ -95,7 +74,7 @@ Looking Glass to use your GPUs DMA engine to transfer the frame data.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
|
||||
ivshmem_kvmfr
|
||||
ivshmem_shm
|
||||
|
||||
@@ -109,36 +88,24 @@ Looking Glass to use your GPUs DMA engine to transfer the frame data.
|
||||
Keyboard/mouse/display/audio
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Looking Glass makes use of the SPICE protocol to provide keyboard and mouse
|
||||
input, audio input and output, and display fallback.
|
||||
The IDD provides the primary video, keyboard and mouse paths directly over
|
||||
LGMP. SPICE is optional, but is recommended for display fallback, clipboard
|
||||
and audio services.
|
||||
|
||||
.. note::
|
||||
The default configuration that libvirt uses is not optimal and must be
|
||||
adjusted. Failure to perform these changes will cause input issues along
|
||||
with failure to support 5 button mice.
|
||||
The current client owns its SPICE connection and service settings. The
|
||||
canonical options are ``spice:enable``, ``spice:input``,
|
||||
``spice:clipboard``, ``spice:audio`` and ``spice:usbAudio``.
|
||||
|
||||
If you would like to use SPICE to give you keyboard and mouse input
|
||||
along with clipboard sync support, make sure you have a
|
||||
``<graphics type='spice'>`` device, then:
|
||||
Keep a ``<graphics type='spice'>`` device if you want these services. For a
|
||||
usable display fallback, set the VM's ``<video>`` model to ``vga``.
|
||||
|
||||
- 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>``
|
||||
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:
|
||||
For classic SPICE audio, add a standard Intel HDA audio device:
|
||||
|
||||
.. code:: xml
|
||||
|
||||
@@ -147,8 +114,10 @@ configuration as per below:
|
||||
</sound>
|
||||
<audio id='1' type='spice'/>
|
||||
|
||||
If you also want clipboard synchronization please see
|
||||
:ref:`libvirt_clipboard_synchronization`
|
||||
The recommended emulated USB audio path does not need this HDA device. It
|
||||
requires a SPICE USB channel and is covered in :ref:`client_usb_audio`. For
|
||||
clipboard synchronization, continue with
|
||||
:ref:`libvirt_clipboard_synchronization`.
|
||||
|
||||
.. _libvirt_clipboard_synchronization:
|
||||
|
||||
@@ -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
|
||||
``/etc/apparmor.d/local/abstractions/libvirt-qemu``::
|
||||
|
||||
/dev/shm/looking-glass rw,
|
||||
/dev/shm/looking-glass rw,
|
||||
|
||||
then, restart AppArmor.
|
||||
|
||||
@@ -217,7 +186,7 @@ Find the ``<memballoon>`` tag and set its type to ``none``:
|
||||
|
||||
<memballoon model="none"/>
|
||||
|
||||
.. _host_install:
|
||||
.. _libvirt_additional_tuning:
|
||||
|
||||
Additional tuning
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -4,8 +4,8 @@
|
||||
IVSHMEM with the KVMFR module (Recommended)
|
||||
###########################################
|
||||
|
||||
The kernel module implements a basic interface to the IVSHMEM device
|
||||
for Looking Glass allowing DMA GPU transfers.
|
||||
The kernel module exposes IVSHMEM to Looking Glass and can export its frame
|
||||
buffers for direct GPU import.
|
||||
|
||||
.. _ivshmem_kvmfr_prereq:
|
||||
|
||||
@@ -47,14 +47,14 @@ Using the value you should have already calculated as per
|
||||
|
||||
.. 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
|
||||
``/etc/modprobe.d/kvmfr.conf`` with the following content.
|
||||
|
||||
.. 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
|
||||
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
|
||||
``/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
|
||||
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:
|
||||
|
||||
@@ -165,7 +167,7 @@ should use this XML block to configure their VM for kvmfr:
|
||||
<qemu:arg value="-device"/>
|
||||
<qemu:arg value="{'driver':'ivshmem-plain','id':'shmem0','memdev':'looking-glass'}"/>
|
||||
<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>
|
||||
|
||||
.. note::
|
||||
@@ -186,7 +188,7 @@ legacy syntax for IVSHMEM setup:
|
||||
<qemu:arg value="-device"/>
|
||||
<qemu:arg value="ivshmem-plain,id=shmem0,memdev=looking-glass"/>
|
||||
<qemu:arg value="-object"/>
|
||||
<qemu:arg value="memory-backend-file,id=looking-glass,mem-path=/dev/kvmfr0,size=32M,share=yes"/>
|
||||
<qemu:arg value="memory-backend-file,id=looking-glass,mem-path=/dev/kvmfr0,size=64M,share=yes"/>
|
||||
</qemu:commandline>
|
||||
|
||||
.. note::
|
||||
@@ -218,9 +220,9 @@ and add the following:
|
||||
cgroups
|
||||
^^^^^^^
|
||||
|
||||
Edit the file ``/etc/libvirt/qemu.conf`` and uncomment the ``cgroup_device_acl``
|
||||
block, adding ``/dev/kvmfr0`` to the list. To make this change active you then
|
||||
must restart ``libvirtd``
|
||||
Edit the file ``/etc/libvirt/qemu.conf`` and uncomment the
|
||||
``cgroup_device_acl`` block, adding ``/dev/kvmfr0`` to the list. Restart
|
||||
``libvirtd`` to apply it:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
@@ -235,10 +237,9 @@ If you are using QEMU directly without libvirt, add the following arguments to y
|
||||
``qemu`` command line::
|
||||
|
||||
-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::
|
||||
|
||||
The ``size`` argument must be the same size you passed
|
||||
to the ``static_size_mb`` argument when loading the kernel module.
|
||||
|
||||
|
||||
@@ -4,9 +4,9 @@
|
||||
IVSHMEM with standard shared memory
|
||||
###################################
|
||||
|
||||
This method is here for those that can not use the KVMFR kernel module. Please
|
||||
be aware that as a result you will not be able to take advantage of your GPUs
|
||||
ability to access memory via it's hardware DMA engine if you use this method.
|
||||
Use this method only when the KVMFR kernel module is unavailable. A standard
|
||||
shared-memory file cannot provide KVMFR's DMA-BUF export, so the client must
|
||||
copy the frame before uploading it to the host GPU.
|
||||
|
||||
Add the following to your libvirt machine configuration inside the
|
||||
'devices' section by running ``virsh edit <VM>`` where ``<VM>`` is the name of
|
||||
@@ -16,7 +16,7 @@ your virtual machine.
|
||||
|
||||
<shmem name='looking-glass'>
|
||||
<model type='ivshmem-plain'/>
|
||||
<size unit='M'>32</size>
|
||||
<size unit='M'>64</size>
|
||||
</shmem>
|
||||
|
||||
.. note::
|
||||
@@ -29,18 +29,16 @@ your virtual machine.
|
||||
.. code:: bash
|
||||
|
||||
-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
|
||||
adjusted as per the :ref:`Determining memory <libvirt_determining_memory>`
|
||||
section.
|
||||
The example uses 64 MiB. Replace it with the value from
|
||||
:ref:`Determining memory <libvirt_determining_memory>` when using a larger
|
||||
resolution.
|
||||
|
||||
.. warning::
|
||||
If you change the size of this after starting your virtual machine you may
|
||||
need to remove the file `/dev/shm/looking-glass` to allow QEMU to re-create
|
||||
it with the correct size. If you do this the permissions of the file may be
|
||||
incorrect for your user to be able to access it and you will need to correct
|
||||
this. See :ref:`libvirt_shmfile_permissions`
|
||||
Stop the VM before changing this size. You may need to remove the existing
|
||||
``/dev/shm/looking-glass`` file so QEMU can recreate it at the new size.
|
||||
Check its permissions afterward; see :ref:`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
|
||||
##########
|
||||
|
||||
You can add a Looking Glass video feed
|
||||
to OBS as a video source with the included OBS plugin. This provides a
|
||||
lower-latency alternative to capturing the Looking Glass client window
|
||||
with a Screen or Window Capture source.
|
||||
|
||||
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
|
||||
The Looking Glass OBS plugin reads video from LGMP directly instead of
|
||||
capturing the client window. The client can stay hidden or show overlays
|
||||
without adding them to the OBS source. This source does not provide audio or
|
||||
input; add the required audio source separately in OBS.
|
||||
|
||||
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:
|
||||
|
||||
Building
|
||||
^^^^^^^^
|
||||
Build and install
|
||||
-----------------
|
||||
|
||||
These instructions are similar to building the
|
||||
:ref:`client <client_building>`.
|
||||
On Debian-based systems, install the OBS headers and the small set of build
|
||||
dependencies used by the plugin:
|
||||
|
||||
.. 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
|
||||
cmake -DUSER_INSTALL=1 ../
|
||||
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
|
||||
|
||||
If you've opted to install the plugin for all users, you will need to run
|
||||
this command as ``root``.
|
||||
For a system-wide installation, omit ``-DUSER_INSTALL=1`` and run
|
||||
``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
|
||||
~~~~~
|
||||
|
||||
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
|
||||
~~~~~~~~~~~
|
||||
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`.
|
||||
|
||||
.. 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
|
||||
:alt: Plugin configuration settings
|
||||
DMA-BUF and CPU copy
|
||||
--------------------
|
||||
|
||||
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 and compatibility
|
||||
##############################
|
||||
|
||||
.. _minimum:
|
||||
|
||||
Minimum
|
||||
-------
|
||||
Required
|
||||
--------
|
||||
|
||||
The most basic requirement to make use of Looking Glass is to have a system
|
||||
with two GPUs, the following configurations are valid:
|
||||
Linux host
|
||||
A Linux system capable of running KVM/QEMU and building the Looking Glass
|
||||
Client. The client requires an EGL-capable graphics driver. X11 and Wayland
|
||||
are supported. For a responsive passthrough setup, use at least six CPU
|
||||
cores with twelve hardware threads.
|
||||
|
||||
* Two discrete GPUs (dGPU)
|
||||
* A discrete GPU and an integrated (iGPU) such as is common in laptops.
|
||||
* A discrete GPU or iGPU and a virtual GPU (vGPU) as supported by some
|
||||
hardware.
|
||||
Windows guest
|
||||
A Windows 10 version 1803 or newer, or Windows 11, virtual machine. The
|
||||
recommended IDD path can create its own virtual monitor and does not require
|
||||
a physical monitor or dummy plug.
|
||||
|
||||
.. note::
|
||||
Please be aware that iGPU users may be limited in the resolution and refresh
|
||||
rate possible with Looking Glass due to the memory bandwidth limitations
|
||||
imposed due to the iGPU sharing system RAM for GPU usage.
|
||||
Shared memory
|
||||
An IVSHMEM device large enough for the maximum guest resolution. The KVMFR
|
||||
kernel module is recommended and is required for direct GPU imports.
|
||||
|
||||
Looking Glass aims to achieve the lowest possible latency and as such it
|
||||
is important that you do not overload your system. The minimum recommended CPU
|
||||
to obtain a decent experience with Looking Glass is 6 cores or more, with
|
||||
Hyper-threading (>= 12 threads).
|
||||
Matching components
|
||||
Use the current client, IDD and OBS plugin from the same Looking Glass
|
||||
release. A protocol version mismatch is not supported. Legacy Host users
|
||||
must use the complete matching B7 stack described below.
|
||||
|
||||
PCIe bandwidth can also be a limiting factor, as such both GPUs should have a
|
||||
minimum of 8 lanes (x8) at PCIe3 speeds, or 4 lanes (x4) at PCIe4 speeds.
|
||||
|
||||
.. _connected_display:
|
||||
|
||||
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.
|
||||
The IDD can fall back to software processing if the Windows guest has no
|
||||
suitable render GPU. This is useful for compatibility, but hardware processing
|
||||
is strongly recommended for lower latency and higher frame rates. Software
|
||||
mode is SDR-only and does not provide the same performance as the GPU path.
|
||||
|
||||
.. _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
|
||||
efficiency cores).
|
||||
* a host CPU with eight cores and sixteen threads or better, with full
|
||||
performance cores around 3 GHz or faster;
|
||||
* KVMFR rather than a plain shared-memory file;
|
||||
* a host GPU and driver that support direct DMA imports;
|
||||
* a hardware render adapter in the Windows guest; and
|
||||
* enough memory bandwidth for the chosen resolution and refresh rate.
|
||||
|
||||
* 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).
|
||||
* NVIDIA brand GPU for the guest system (virtual machine).
|
||||
For a passed-through GPU, PCIe bandwidth can also limit performance. Use at
|
||||
least eight PCIe 3.0 lanes or four PCIe 4.0 lanes where practical.
|
||||
|
||||
AMD or Intel for the client
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
.. _connected_display:
|
||||
|
||||
AMD and Intel both support the `DMABUF` feature which enables offloading memory
|
||||
transfers to the GPU hardware. Please note that making use of this feature
|
||||
requires :doc:`loading the KVMFR kernel module <ivshmem_kvmfr>`.
|
||||
Physical display and dummy plugs
|
||||
--------------------------------
|
||||
|
||||
Additionally AMD GPUs suffer stability issues when operating as a passthrough
|
||||
device and as such we do not recommend their usage for such purposes. Models of
|
||||
note that have issues include but are not limited to the entire Polaris, Vega,
|
||||
Navi and BigNavi GPU series. Vega and Navi are notably the worst and should be
|
||||
avoided for virtualization usage.
|
||||
The recommended IDD does not require a physical display or dummy plug. It
|
||||
creates a virtual Windows monitor, including on systems without a
|
||||
passed-through display output.
|
||||
|
||||
NVIDIA for the guest
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
.. _igpu_kvmfr_recommended:
|
||||
|
||||
iGPUs should use DMABUF
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Host GPU notes
|
||||
--------------
|
||||
|
||||
While `DMABUF` with the :doc:`KVMFR module <ivshmem_kvmfr>` offers performance
|
||||
benefits for all users, for the often bandwidth-starved users with an iGPU on
|
||||
their host it's considered a requirement for a decent experience.
|
||||
AMD and Intel host GPUs commonly support the DMA-BUF path used by KVMFR. This
|
||||
can reduce CPU work and avoid an extra system-memory copy. It is particularly
|
||||
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
|
||||
shared memory to an intermediary buffer, then upload it from that buffer to the
|
||||
GPU's framebuffer. The KVMFR module will instead use Direct Memory Access (DMA)
|
||||
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.
|
||||
NVIDIA host GPUs require a driver configuration that supports DMA-BUF import.
|
||||
If direct import is unavailable, the client falls back to a software copy.
|
||||
Looking Glass still works, but uses more CPU and memory bandwidth.
|
||||
|
||||
An added benefit: since the upload is done with the iGPU, the CPU load is
|
||||
reduced as the upload does not use processor cores.
|
||||
Windows and HDR
|
||||
---------------
|
||||
|
||||
Windows 10 remains supported. Current HDR and wide-color-gamut display features
|
||||
depend on newer IddCx interfaces that the driver checks at runtime, so they are
|
||||
normally available only on a compatible Windows 11 installation. The IDD
|
||||
continues to use its SDR-compatible path when those interfaces are unavailable.
|
||||
|
||||
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
|
||||
know more about what's going on under the hood.
|
||||
This page explains a few implementation choices. It is not required for normal
|
||||
installation.
|
||||
|
||||
.. _ivshmemshared_ram:
|
||||
|
||||
IVSHMEM/Shared RAM
|
||||
------------------
|
||||
IVSHMEM and shared memory
|
||||
-------------------------
|
||||
|
||||
.. _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
|
||||
guest via a BAR (Base Address Register). It also has additional features
|
||||
such as interrupt triggering for synchronization however we do not use
|
||||
these.
|
||||
IVSHMEM maps the same reserved memory into QEMU, the Windows guest and Linux.
|
||||
KVMFR provides the Linux character-device interface used by the client and OBS
|
||||
and can export regions for direct GPU import.
|
||||
|
||||
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?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Why is the allocation larger than one image?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
One might assume that we are simply using the device for the captured
|
||||
frames, this, however, is not entirely accurate. Looking Glass also
|
||||
needs to capture mouse shape changes (the mouse cursor), and mouse
|
||||
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.
|
||||
In addition to three aligned images, the region contains LGMP queues and GPU
|
||||
resource alignment. Use :ref:`libvirt_determining_memory` rather than
|
||||
multiplying width and height once.
|
||||
|
||||
.. _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
|
||||
using a tablet, which does work, however, if you also want relative
|
||||
input for applications/games that require cursor capture, you need a
|
||||
relative input device such as a PS/2 mouse.
|
||||
Desktop interaction needs absolute positioning so the host and guest pointers
|
||||
stay aligned without capture. Games that lock the cursor need unbounded
|
||||
relative movement. The IDD exposes both and the client selects the appropriate
|
||||
path when capture mode changes.
|
||||
|
||||
The problem is, due to the design of QEMU or the Windows mouse subsystem
|
||||
(not sure which), when the VM has both devices attached (which is the
|
||||
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.
|
||||
SPICE fallback remains relative-only. Pointer position messages are also used
|
||||
to render the guest cursor independently from desktop frame updates.
|
||||
|
||||
.. _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
|
||||
clear that the performance, especially for high update rate mice was
|
||||
extremely poor. This may have improved in recent QEMU versions and
|
||||
perhaps should be re-evaluated at some point.
|
||||
Polling avoids the high overhead and batching behavior seen with virtual
|
||||
interrupts, especially for high-rate pointer updates. The polling intervals
|
||||
are configurable for diagnosis, but lowering them without evidence increases
|
||||
CPU usage and does not guarantee lower latency.
|
||||
|
||||
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
|
||||
###############
|
||||
|
||||
There are many different issues that can arise when setting up Looking
|
||||
Glass. Below is a list of known issues with potential solutions:
|
||||
Start with the symptom below. Avoid changing polling, synchronization or
|
||||
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 doesn't appear
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The Looking Glass monitor is missing in Windows
|
||||
-----------------------------------------------
|
||||
|
||||
Make sure you meet the :ref:`minimum requirements<minimum>` for using
|
||||
Looking Glass, especially regarding your guest GPU. See
|
||||
:ref:`connected_display` for more details.
|
||||
1. Confirm that the guest runs Windows 10 version 1803 or newer, or Windows 11.
|
||||
2. Confirm that the IDD installer completed and restart Windows if requested.
|
||||
3. Open the IDD helper and its log directory. See :ref:`idd_diagnostics`.
|
||||
4. In ``looking-glass-idd.txt``, confirm that IVSHMEM opened with the expected
|
||||
size and that at least one configured display mode fits.
|
||||
5. Increase IVSHMEM if every suitable mode was filtered. Restart the VM after
|
||||
changing its size.
|
||||
6. Ensure the legacy Host service is disabled. Only one 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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
----------------------------
|
||||
|
||||
- **Is clipboard synchronization enabled?**
|
||||
|
||||
@@ -29,7 +90,7 @@ The clipboard is not working
|
||||
|
||||
- The `SPICE Guest Tools
|
||||
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".
|
||||
|
||||
.. warning::
|
||||
@@ -46,7 +107,7 @@ The clipboard is not working
|
||||
.. _keyboard_shortcuts_not_captured_on_gnome_wayland:
|
||||
|
||||
Keyboard shortcuts are not captured on GNOME Wayland
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
-----------------------------------------------------
|
||||
|
||||
Capture mode may fail to capture compositor shortcuts like
|
||||
ALT+Tab or ALT+Middle Mouse - they go to GNOME instead of the guest VM.
|
||||
@@ -69,3 +130,23 @@ To verify the permission was set:
|
||||
|
||||
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
|
||||
------------
|
||||
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``
|
||||
options.
|
||||
looking-glass-client -f /dev/kvmfr1
|
||||
|
||||
Example: ``looking-glass-client --help``
|
||||
|
||||
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`
|
||||
Use ``looking-glass-client --help`` to see the options supported by the
|
||||
installed build. Command-line options override configuration files.
|
||||
|
||||
.. _client_key_bindings:
|
||||
|
||||
Default key bindings
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
--------------------
|
||||
|
||||
By default, Looking Glass uses the :kbd:`ScrLk` key as the escape key
|
||||
for commands, as well as the input :kbd:`capture` mode toggle; this can be
|
||||
changed using the ``-m`` switch if you desire a different key. Below are
|
||||
a list of current key bindings:
|
||||
Looking Glass uses :kbd:`ScrLk` as its escape key by default. Press it by
|
||||
itself to enter or leave capture mode. Hold it to display the available
|
||||
commands. Change it with ``input:escapeKey`` or ``-m`` if the keyboard does
|
||||
not have :kbd:`ScrLk`.
|
||||
|
||||
============================ =======================================================
|
||||
Command Description
|
||||
============================ =======================================================
|
||||
: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
|
||||
============================ =======================================================
|
||||
.. list-table:: Default client commands
|
||||
:widths: 35 65
|
||||
:header-rows: 1
|
||||
|
||||
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:
|
||||
|
||||
Configuration files
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
-------------------
|
||||
|
||||
By default, Looking Glass will load config files from
|
||||
the following locations:
|
||||
The client loads these files in order when they exist:
|
||||
|
||||
- ``/etc/looking-glass-client.ini``
|
||||
- ``~/.looking-glass-client.ini``
|
||||
- ``$XDG_CONFIG_HOME/looking-glass/client.ini`` (usually ``~/.config/looking-glass/client.ini``)
|
||||
* ``/etc/looking-glass-client.ini``
|
||||
* ``~/.looking-glass-client.ini``
|
||||
* ``$XDG_CONFIG_HOME/looking-glass/client.ini``
|
||||
|
||||
All config files are loaded in order. Duplicate entries override earlier ones.
|
||||
This means you can set a system-wide configuration in
|
||||
``/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:
|
||||
Later files override earlier files. The usual per-user path is
|
||||
``~/.config/looking-glass/client.ini``. Files use INI syntax:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[win]
|
||||
fullScreen=yes
|
||||
setGuestRes=yes
|
||||
|
||||
[input]
|
||||
autoCapture=yes
|
||||
|
||||
[spice]
|
||||
clipboard=yes
|
||||
audio=yes
|
||||
|
||||
[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
|
||||
files.
|
||||
.. code:: bash
|
||||
|
||||
looking-glass-client win:fullScreen=yes input:autoCapture=yes
|
||||
|
||||
.. _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:
|
||||
|
||||
Configuration widget
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
Interactive overlay
|
||||
-------------------
|
||||
|
||||
The configuration widget is accessible through the overlay mode. The
|
||||
widget has multiple tabs that allow setting a variety of modes and
|
||||
parameters for Looking Glass at runtime.
|
||||
Press :kbd:`ScrLk` + :kbd:`O` to make the overlay interactive. Press
|
||||
:kbd:`Esc` or the same binding to leave it. The overlay can:
|
||||
|
||||
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.
|
||||
Multiple graphs are available, and they will stack vertically.
|
||||
- *EGL*: Modify EGL settings, such as the algorithm used for scaling, and
|
||||
night vision mode.
|
||||
Widget positions and sizes are stored in
|
||||
``$XDG_CONFIG_HOME/looking-glass/imgui.ini``. EGL filter presets are stored in
|
||||
``$XDG_CONFIG_HOME/looking-glass/presets``. Do not edit either while the
|
||||
client is running.
|
||||
|
||||
Changes in the settings tab are not persistent, and will be reset back to
|
||||
their default values when the client is restarted.
|
||||
Runtime changes are not all written to the main client configuration. Put
|
||||
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
|
||||
post-processing filters. Each filter can be expanded to open its settings.
|
||||
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:
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
- *Downscaler*: Filter for downscaling the host resolution. Can be used to undo
|
||||
poor upscaling on the VM to better utilize AMD FSR (see below). The filter
|
||||
has a pixel-size setting that is used to set the effective downscaling ratio,
|
||||
and a configurable interpolation algorithm.
|
||||
|
||||
- *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
|
||||
input
|
||||
display
|
||||
audio
|
||||
performance
|
||||
options
|
||||
|
||||
@@ -1,11 +1,14 @@
|
||||
Anime4K
|
||||
backend
|
||||
backtrace
|
||||
BigNavi
|
||||
borderless
|
||||
Brindus
|
||||
cadence
|
||||
cgroups
|
||||
clang
|
||||
cmake
|
||||
compositor
|
||||
config
|
||||
CopySleep
|
||||
Debian
|
||||
@@ -22,6 +25,7 @@ downsampling
|
||||
downscaler
|
||||
downscaling
|
||||
evdev
|
||||
ExtraMode
|
||||
Flatpak
|
||||
framebuffer
|
||||
fullscreen
|
||||
@@ -31,6 +35,7 @@ gnif
|
||||
Guanzhong
|
||||
hypervisor
|
||||
i3
|
||||
IddCx
|
||||
ie
|
||||
imgui
|
||||
ini
|
||||
@@ -55,21 +60,29 @@ msys
|
||||
multisampling
|
||||
namespace
|
||||
Navi
|
||||
NvFBC
|
||||
Nvidia
|
||||
overlayed
|
||||
overrun
|
||||
pacman
|
||||
passthrough
|
||||
performant
|
||||
pre
|
||||
prebuilt
|
||||
protanope
|
||||
QEMU
|
||||
quadraphonic
|
||||
Quadro
|
||||
radeon
|
||||
realtime
|
||||
renderer
|
||||
repo
|
||||
resampler
|
||||
Rubenstein
|
||||
runtime
|
||||
scanout
|
||||
Scream
|
||||
scRGB
|
||||
shm
|
||||
spencercw
|
||||
submodule
|
||||
@@ -78,6 +91,7 @@ systemd
|
||||
th
|
||||
Threadripper
|
||||
toolchain
|
||||
tooltip
|
||||
tritanope
|
||||
tunable
|
||||
uaccess
|
||||
@@ -85,12 +99,14 @@ udev
|
||||
UEFI
|
||||
uncheck
|
||||
uncomment
|
||||
underrun
|
||||
Unigine
|
||||
unix
|
||||
upscaled
|
||||
upscaler
|
||||
upscales
|
||||
upscaling
|
||||
VirtIO
|
||||
VM
|
||||
vsync
|
||||
wayland
|
||||
|
||||
Reference in New Issue
Block a user