[doc]: a bunch of consistency fixes

This commit is contained in:
Tudor Brindus 2022-09-18 20:38:03 -04:00 committed by Geoffrey McRae
parent 0c63a901be
commit 6a9075b412
8 changed files with 214 additions and 212 deletions

View file

@ -66,17 +66,17 @@ Required dependencies
Depends: or Recommends: from another listed package is not allowed.
All required packages must be listed.
- cmake
- gcc, g++ \| clang
- libegl-dev
- libgl-dev
- libgles-dev
- libfontconfig-dev
- libgmp-dev
- libspice-protocol-dev
- make
- nettle-dev
- pkg-config
- ``cmake``
- ``gcc``, ``g++`` \| ``clang``
- ``libegl-dev``
- ``libgl-dev``
- ``libgles-dev``
- ``libfontconfig-dev``
- ``libgmp-dev``
- ``libspice-protocol-dev``
- ``make``
- ``nettle-dev``
- ``pkg-config``
.. _client_deps_may_be_disabled:
@ -88,41 +88,41 @@ feature is disabled when running :ref:`cmake <client_building>`.
- Disable with ``cmake -DENABLE_BACKTRACE=no ..``
- binutils-dev
- ``binutils-dev``
- Disable with ``cmake -DENABLE_X11=no ..``
- libx11-dev
- libxfixes-dev
- libxi-dev
- libxinerama-dev
- libxss-dev
- libxcursor-dev
- libxpresent-dev
- ``libx11-dev``
- ``libxfixes-dev``
- ``libxi-dev``
- ``libxinerama-dev``
- ``libxss-dev``
- ``libxcursor-dev``
- ``libxpresent-dev``
- Disable with ``cmake -DENABLE_WAYLAND=no ..``
- libxkbcommon-dev
- libwayland-bin
- libwayland-dev
- wayland-protocols
- ``libxkbcommon-dev``
- ``libwayland-bin``
- ``libwayland-dev``
- ``wayland-protocols``
- Disable with ``cmake -DENABLE_PIPEWIRE=no ..``
- libpipewire-0.3-dev
- libsamplerate0-dev
- ``libpipewire-0.3-dev``
- ``libsamplerate0-dev``
- Disable with ``cmake -DENABLE_PULSEAUDIO=no ..``
- libpulse-dev
- libsamplerate0-dev
- ``libpulse-dev``
- ``libsamplerate0-dev``
.. _client_deps_recommended:
Recommended
<<<<<<<<<<<
- fonts-dejavu-core (This is the default UI font, but a random font will
- ``fonts-dejavu-core`` (This is the default UI font, but a random font will
be chosen if not available).
.. _client_fetching_with_apt:
@ -140,7 +140,7 @@ You can fetch these dependencies with the following command:
libxpresent-dev libxss-dev libxkbcommon-dev libwayland-dev wayland-protocols \
libpipewire-0.3-dev libpulse-dev libsamplerate0-dev
You may omit some dependencies, if you disable the feature which requires them
You may omit some dependencies if you disable the feature which requires them
when running :ref:`cmake <client_building>`.
(See :ref:`client_deps_may_be_disabled`)
@ -160,7 +160,7 @@ into the *LookingGlass* directory.
cmake ../
make
This will build the **looking-glass-client** binary, which is used to display
This will build the ``looking-glass-client`` binary, which is used to display
frames from the guest.
You can then :ref:`continue installing Looking Glass <client_install>`, or run
@ -172,12 +172,12 @@ it directly from the build directory:
.. seealso::
- :ref:`Client Installation <client_install>`
- :ref:`Client Usage <client_usage>`
- :ref:`Client installation <client_install>`
- :ref:`Client usage <client_usage>`
.. note::
For users running GNOME on Wayland, you may want to enable libdecor when
For users running GNOME on Wayland, you may want to enable ``libdecor`` when
building.
.. code:: bash
@ -195,7 +195,7 @@ it directly from the build directory:
cmake -DENABLE_BACKTRACE=0 ../
If you disable this and need support for crash, use ``gdb`` to obtain a
If you disable this and need support for a crash, use ``gdb`` to obtain a
backtrace manually.
.. _host_building:

View file

@ -1,4 +1,4 @@
Frequently Asked Questions
Frequently asked questions
##########################
General

View file

@ -5,8 +5,8 @@ Installation
.. _libvirt:
libvirt/QEMU configuration:
---------------------------
libvirt/QEMU configuration
--------------------------
This article assumes you already have a fully functional libvirt domain with
PCI passthrough working.
@ -52,7 +52,7 @@ your virtual machine.
-object memory-backend-file,id=ivshmem,share=on,mem-path=/dev/shm/looking-glass,size=32M
The memory size (show as 32 in the example above) may need to be
adjusted as per the :ref:`Determining Memory <libvirt_determining_memory>`
adjusted as per the :ref:`Determining memory <libvirt_determining_memory>`
section.
.. warning::
@ -85,10 +85,10 @@ For example, for a resolution of 1920x1080 (1080p):
``1920 x 1080 x 4 x 2 = 16,588,800 bytes``
``16,588,800 / 1024 / 1024 = 15.82 MB + 10 = 25.82 MB``
``16,588,800 / 1024 / 1024 = 15.82 MiB + 10 = 25.82 MiB``
You must round this value up to the nearest power of two, which for the
provided example is 32MB.
provided example is 32 MiB.
.. note::
Increasing this value beyond what you need does not yield any performance
@ -133,14 +133,14 @@ The shared memory file used by IVSHMEM is found in ``/dev/shm/looking-glass``.
By default, it is owned by QEMU, and does not give read/write permissions to
your user, which are required for Looking Glass to run properly.
You can use `systemd-tmpfiles` to create the file before running your VM,
You can use ``systemd-tmpfiles`` to create the file before running your VM,
granting the necessary permissions which allow Looking Glass to use the file
properly.
Create a new file ``/etc/tmpfiles.d/10-looking-glass.conf``, and populate it
with the following::
#Type Path Mode UID GID Age Argument
# Type Path Mode UID GID Age Argument
f /dev/shm/looking-glass 0660 user kvm -
@ -149,18 +149,18 @@ own.
.. _libvirt_spice_server:
Keyboard/Mouse/Display/Sound
Keyboard/mouse/display/audio
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Looking Glass makes use of the SPICE protocol to provide keyboard and mouse
input, sound input and output, and display fallback.
input, audio input and output, and display fallback.
.. 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.
If you would like to use Spice to give you keyboard and mouse input
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:
@ -180,7 +180,7 @@ along with clipboard sync support, make sure you have a
`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
To enable audio support add a standard Intel HDA audio device to your
configuration as per below:
.. code:: xml
@ -306,7 +306,7 @@ Host application
The Looking Glass Host application captures frames from the guest OS using a
capture API, and sends them to the
:ref:`Client <client_install>`—be it on the host OS (hypervisor) or another
:ref:`client <client_install>`—be it on the host OS (hypervisor) or another
Virtual Machine—through a low-latency transfer protocol over shared memory.
You can get the host program in two ways:
@ -386,9 +386,9 @@ running ``looking-glass-host-setup.exe /?``.
Client application
------------------
The Looking Glass Client receives frames from the :ref:`Host <host_install>` to
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.
system clipboard with your guest OS through SPICE.
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::

View file

@ -12,7 +12,7 @@ memory device on the host machine that supports dmabuf.
Prerequisites
-------------
The linux kernel headers for your kernel version are required for building.
The Linux kernel headers for your kernel version are required for building.
Install them with ``apt-get``
.. code:: bash
@ -53,11 +53,11 @@ To install the module into DKMS, run
Loading
~~~~~~~
For VM → VM, simply modprobe the module::
For VM → VM, simply ``modprobe`` the module::
modprobe kvmfr
For VM → host with dmabuf, modprobe with the parameter
For VM → host with dmabuf, ``modprobe`` with the parameter
``static_size_mb``:
.. code:: bash
@ -88,7 +88,7 @@ For VM → VM mode, run:
For VM → host mode with dmabuf, instead of creating a shared memory file,
load this module with the parameter ``static_size_mb``. For example, a
32 MB shared memory device can be created with:
32 MiB shared memory device can be created with:
.. code:: bash
@ -96,7 +96,7 @@ load this module with the parameter ``static_size_mb``. For example, a
Multiple devices can be created by separating the sizes with commas. For
example, ``static_size_mb=128,64`` would create two kvmfr devices:
``kvmfr0`` would be 128 MB and ``kvmfr1`` would be 64 MB.
``kvmfr0`` would be 128 MB and ``kvmfr1`` would be 64 MiB.
.. note::
@ -238,7 +238,7 @@ We can use the ``systemd-modules-load.service(8)`` service for this task.
Create the file ``/etc/modules-load.d/kvmfr.conf`` with the following
contents::
#KVMFR Looking Glass module
# KVMFR Looking Glass module
kvmfr
This will now run the next time you start your machine.

View file

@ -23,7 +23,7 @@ The OBS plugin requires the following extra dependencies alongside the
:ref:`client's build
dependencies <installing_build_dependencies>`.
- libobs-dev
- ``libobs-dev``
Install this package with ``apt-get``

View file

@ -26,7 +26,7 @@ The clipboard is not working
- **Is clipboard synchronization enabled?**
- Before you can copy or paste content between the Guest and Host,
- Before you can copy or paste content between the guest and host,
:ref:`clipboard
synchronization <libvirt_clipboard_synchronization>`
must be enabled.

View file

@ -3,7 +3,7 @@
Client usage
------------
**looking-glass-client** [\-\-help] [\-f] [\-F] [\-s] [\-S] [options...]
**``looking-glass-client``** ``[--help] [-f] [-F] [-s] [-S] [options...]``
.. _client_cli_options:
@ -97,9 +97,9 @@ Configuration files
By default, Looking Glass will load config files from
the following locations:
- /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`` (usually ``~/.config/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
@ -108,7 +108,7 @@ 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.
``$XDG_CONFIG_HOME/looking-glass/`` if it does not yet exist.
The format of config files is the commonly known INI format, for example::
@ -135,13 +135,13 @@ These include:
(see :ref:`client_config_widget`)
You can also reposition and resize enabled widgets, like the FPS/UPS Display,
and Performance Metrics.
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
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.
@ -151,52 +151,52 @@ as your changes may be discarded.
Configuration widget
~~~~~~~~~~~~~~~~~~~~
The Configuration Widget is accessible through the Overlay Mode. The
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.
Settings tab
^^^^^^^^^^^^
- Performance Metrics: A toggle for the Performance Metrics Widget.
- *Performance Metrics*: A toggle for the performance metrics widget.
Multiple graphs are available, and they will stack vertically.
- EGL: Modify EGL features, such as the algorithm used for scaling, and
- *EGL*: Modify EGL settings, such as the algorithm used for scaling, and
night vision mode.
Changes in the Settings tab are not persistent, and will change back to
Changes in the settings tab are not persistent, and will be reset back to
their default values when the client is restarted.
EGL filters tab
^^^^^^^^^^^^^^^
The EGL Filters tab contains options for toggling, configuring, and ordering
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, e.g 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:
from top to bottom. Keep this in mind when ordering them -- for example,
applying CAS before FSR might have different results than the reverse. Users
are encouraged to experiment with the order and parameters to achieve optimal
results. The currently available filters include:
- Downscaler: Filter for downscaling the host resolution. Can be used to undo
- *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
- *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
- *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
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::
@ -213,7 +213,7 @@ the "Preset name" pull down. Presets are persistent and are stored on disk at
All command line options
~~~~~~~~~~~~~~~~~~~~~~~~
The following is a complete list of options accepted by this application
.. code-block::
+------------------------+-------+------------------------+-----------------------------------------------------------------------------------------+
| Long | Short | Value | Description |
@ -343,7 +343,7 @@ 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 just as the client will it is more convenient to create the
`looking-glass-host.ini` file with the desired configuration options.
``looking-glass-host.ini`` file with the desired configuration options.
This file must be placed in the same directory that the Looking Glass host
application was installed for it to be found and used by the application
@ -366,7 +366,7 @@ however this can be changed via the ini file with the following configuration:
[app]
capture=<INTERFACE>
Where `<INTERFACE>` is one of `dxgi` or `nvfbc`
Where ``<INTERFACE>`` is one of ``dxgi`` or ``nvfbc``
.. _host_capture_dxgi:
@ -386,12 +386,12 @@ 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, however this can
be mitigated by using the DirectX 12 back end. Please be aware though that this
back end is not experimental because it's new, but rather it's a slight
abuse/misuse of the DXGI API and allows us to bypass some windows internals.
be mitigated by using the DirectX 12 backend. Please be aware though that this
backend is not experimental because it's new, but rather it's a slight
abuse/misuse of the DXGI API and allows us to bypass some Windows internals.
To enable the DirectX 12 back end the following configuration needs to be added
to the `looking-glass-host.ini` configuration:
To enable the DirectX 12 backend the following configuration needs to be added
to the ``looking-glass-host.ini`` configuration:
.. code:: ini
@ -403,7 +403,7 @@ to the `looking-glass-host.ini` configuration:
d3d12CopySleep=5
disableDamage=false
The option `d3d12CopySleep` is to work around the lack of locking this misuse
The option ``d3d12CopySleep`` is to work around the lack of locking this misuse
of the API allows and you will need to tune this value to what suits your
hardware best. The default value is 5ms as this should work for most, lowing
it below 2ms is doubtful to be of practical use to anyone. If this value is too
@ -412,25 +412,25 @@ a window around on the Windows desktop.
.. note::
Lowering d3d12CopySleep can improve the UPS however the UPS metric makes
little sense when using the d3d12 back end as if this value is too low
little sense when using the d3d12 backend as if this value is too low
unchanged frames will be doubled up.
The `disableDamage` option may be needed to avoid screen corruption however
please note that this will increase the bandwidth required and in turn the
overall load on your system.
The ``disableDamage`` option may be needed to avoid screen corruption. Note
that this will increase the bandwidth required and in turn the overall load on
your system.
The DXGI capture interface also offers a feature that allows downsampling the
captured frames in the guest GPU before transferring them to shared memory.
This feature is very useful if you are super scaling for better picture quality
and wish to reduce system memory pressure.
The configuration for this is fairly straight forward and is defined as set of
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:: ini
[dxgi]
downssample=RULE1,RULE2,RULE3
downsample=RULE1,RULE2,RULE3
The rules are written as follows:
@ -438,7 +438,7 @@ The rules are written as follows:
(>|>=)(WIDTH)x(HEIGHT):(LEVEL)
The `LEVEL` is the fractional scale level where 1 = 50%, 2 = 25%, 3 = 12.5%.
The ``LEVEL`` is the fractional scale level where 1 = 50%, 2 = 25%, 3 = 12.5%.
**Examples:**
@ -470,7 +470,7 @@ system load and lower latency capture, and does not suffer from the mouse
motion stutter issues that DXGI suffers from.
To enable it's usage use the following configuration in the
`looking-glass-host.ini` file:
``looking-glass-host.ini`` file:
.. code:: ini
@ -492,7 +492,7 @@ rules to determine when to perform this downsampling. The format is as follows:
.. code:: ini
[nvfbc]
downssample=RULE1,RULE2,RULE3
downsample=RULE1,RULE2,RULE3
The rules are written as follows:
@ -515,5 +515,5 @@ The rules are written as follows:
downsample=3840x2160:1920x1080,3840x2400:1920x1200
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
it's usage however is unavailable.
environment variable ``NVFBC_PRIV_DATA`` if it has been set, documentation on
its usage however is unavailable.

View file

@ -1,3 +1,4 @@
backend
backtrace
borderless
BigNavi
@ -31,6 +32,7 @@ libvirt
linux
LookingGlass
memballoon
MiB
microstutters
mingw
mipmapping