mirror of
https://github.com/gnif/LookingGlass.git
synced 2024-12-22 13:52:57 +00:00
[doc] Import from wiki
Imported Installation, FAQ, Troubleshooting, OBS, and Technical FAQ pages from wiki. Edits done to content as this is no longer a wiki, but versioned in-repo documentation
This commit is contained in:
Jonathan Rubenstein
Geoffrey McRae
parent
5b0ca835f8
commit
91e55b9d5f
9 changed files with 819 additions and 16 deletions
|
|
@ -18,8 +18,8 @@
|
||||||
# -- Project information -----------------------------------------------------
|
# -- Project information -----------------------------------------------------
|
||||||
|
|
||||||
project = 'Looking Glass'
|
project = 'Looking Glass'
|
||||||
copyright = '2021, Geoffrey McRae, quantum, xyenne, other contributors on GitHub.'
|
copyright = '2021, Geoffrey McRae, quantum, xyenne, and other contributors'
|
||||||
author = 'Geoffrey McRae, quantum, xyenne, other contributors on GitHub.'
|
author = 'Geoffrey McRae, quantum, xyenne, and other contributors'
|
||||||
|
|
||||||
# The full version, including alpha/beta/rc tags
|
# The full version, including alpha/beta/rc tags
|
||||||
release = 'B4'
|
release = 'B4'
|
||||||
|
|
@ -34,7 +34,7 @@ extensions = [
|
||||||
]
|
]
|
||||||
|
|
||||||
# Add any paths that contain templates here, relative to this directory.
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
templates_path = ['_templates']
|
# templates_path = ['_templates']
|
||||||
|
|
||||||
# List of patterns, relative to source directory, that match files and
|
# List of patterns, relative to source directory, that match files and
|
||||||
# directories to ignore when looking for source files.
|
# directories to ignore when looking for source files.
|
||||||
|
|
@ -52,4 +52,4 @@ html_theme = 'alabaster'
|
||||||
# Add any paths that contain custom static files (such as style sheets) here,
|
# Add any paths that contain custom static files (such as style sheets) here,
|
||||||
# relative to this directory. They are copied after the builtin static files,
|
# relative to this directory. They are copied after the builtin static files,
|
||||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||||
html_static_path = ['_static']
|
# html_static_path = ['_static']
|
||||||
|
|
|
||||||
199
doc/faq.rst
Normal file
199
doc/faq.rst
Normal file
|
|
@ -0,0 +1,199 @@
|
||||||
|
Frequently Asked Questions
|
||||||
|
##########################
|
||||||
|
|
||||||
|
General
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. _how_does_looking_glass_work:
|
||||||
|
|
||||||
|
How does Looking Glass work?
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Please see the following video that covers this:
|
||||||
|
|
||||||
|
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 gives the captured frames to OBS.
|
||||||
|
|
||||||
|
.. _why_is_my_ups_updates_per_second_so_low:
|
||||||
|
|
||||||
|
Why is my UPS (Updates Per Second) so low?
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
There are several reasons why this can happen, the most common is your
|
||||||
|
capture resolution. At the time of this writing, the windows capture
|
||||||
|
methods struggle to capture high resolutions under certain
|
||||||
|
circumstances, as a general rule of thumb anything greater than 1200p
|
||||||
|
(1920x1200) starts to suffer from performance issues.
|
||||||
|
|
||||||
|
Another cause can be how the game or application you are running is
|
||||||
|
configured. Because of the way windows integrate with the WDM (Windows
|
||||||
|
Desktop Manager) running applications in "Full Screen" mode may in some
|
||||||
|
cases cause a large performance penalty. Try switching to windowed
|
||||||
|
full-screen mode, the difference in performance can be like night and
|
||||||
|
day. Titles known to be affected by this are Fallout76, The BattleField
|
||||||
|
Series and SCUM.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. _is_my_gpu_supported:
|
||||||
|
|
||||||
|
Is my GPU supported?
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Your guest GPU almost certainly supports DXGI. Use DxDiag to confirm
|
||||||
|
that you have support for WDDM 1.2 or greater.
|
||||||
|
|
||||||
|
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 make the error go away by specifying
|
||||||
|
"-c DXGI"
|
||||||
|
|
||||||
|
.. _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?
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Note that without Spice, you will not be sending mouse/keyboard events
|
||||||
|
to the guest nor will you get clipboard Synchronization support.
|
||||||
|
|
||||||
|
.. _where_is_the_host_application_for_linux:
|
||||||
|
|
||||||
|
Where is the host application for 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
|
||||||
|
|
||||||
|
Mouse
|
||||||
|
-----
|
||||||
|
|
||||||
|
.. _the_mouse_is_jumpy_slow_laggy_when_using_spice:
|
||||||
|
|
||||||
|
The mouse is jumpy, slow, laggy when using SPICE
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Please be sure to install the SPICE guest tools from
|
||||||
|
https://www.spice-space.org/download.html#windows-binaries.
|
||||||
|
|
||||||
|
.. _how_to_enable_clipboard_synchronization_via_spice:
|
||||||
|
|
||||||
|
How to enable clipboard synchronization via SPICE
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Install the SPICE guest tools from
|
||||||
|
https://www.spice-space.org/download.html#windows-binaries.
|
||||||
|
|
||||||
|
Choose only one of the settings below (the one that applies to your
|
||||||
|
configuration):
|
||||||
|
|
||||||
|
- QEMU
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
-device virtio-serial-pci \
|
||||||
|
-chardev spicevmc,id=vdagent,name=vdagent \
|
||||||
|
-device virtserialport,chardev=vdagent,name=com.redhat.spice.0
|
||||||
|
|
||||||
|
- Virt Manager GUI
|
||||||
|
|
||||||
|
- Open Machine Properties > Add Hardware > Channel
|
||||||
|
- Set Name to ``com.redhat.spice.0`` and Device Type to
|
||||||
|
``Spice agent (spicevmc)`` and click Finish
|
||||||
|
- No need to add VirtIO Serial device, it will be added
|
||||||
|
automatically
|
||||||
|
|
||||||
|
- libvirt using virsh
|
||||||
|
|
||||||
|
- Edit the VM using virsh ``sudo virsh edit VIRTUAL_MACHINE_NAME``
|
||||||
|
- Paste the code from below right above (note the closing tag)
|
||||||
|
|
||||||
|
.. code:: xml
|
||||||
|
|
||||||
|
<!-- No need to add VirtIO Serial device, it will be added automatically -->
|
||||||
|
<channel type="spicevmc">
|
||||||
|
<target type="virtio" name="com.redhat.spice.0"/>
|
||||||
|
<address type="virtio-serial" controller="0" bus="0" port="1"/>
|
||||||
|
</channel>
|
||||||
|
|
||||||
|
.. _the_mouse_doesnt_stay_aligned_with_the_host.:
|
||||||
|
|
||||||
|
The mouse doesn't stay aligned with the host.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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)
|
||||||
|
|
||||||
|
Some other things to try:
|
||||||
|
|
||||||
|
- Have you tried pressing Scroll Lock to toggle mouse capture mode?
|
||||||
|
- Try keeping the client window the same size as the guest's
|
||||||
|
resolution.
|
||||||
|
|
||||||
|
.. _the_cursor_position_doesnt_update_until_i_click:
|
||||||
|
|
||||||
|
The cursor position doesn't update until I click
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Audio
|
||||||
|
-----
|
||||||
|
|
||||||
|
Looking Glass does not handle audio at all, nor will it ever. The preferred
|
||||||
|
solution is to pass through QEMU's audio to your host's audio system.
|
||||||
|
|
||||||
|
Another popular solution is to use
|
||||||
|
`Scream <https://github.com/duncanthrax/scream>`_, a virtual sound card which
|
||||||
|
pipes audio through the network. A guide for setting up scream is available on
|
||||||
|
the wiki: https://looking-glass.io/wiki/Using_Scream_over_LAN
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Windows
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. _nvfbc_nvidia_capture_api_doesnt_work:
|
||||||
|
|
||||||
|
NvFBC (NVIDIA Capture API) doesn't work
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Unfortunately, NVIDIA deemed fit to only allow owners of "Professional
|
||||||
|
Cards", and their own software (ShadowPlay) the right to use the NVIDIA
|
||||||
|
Capture API. There is little we can do about this other than to complain
|
||||||
|
to NVIDIA.
|
||||||
|
|
||||||
|
.. _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.
|
||||||
BIN
doc/images/Looking-Glass-OBS-Source-Add.png
Normal file
BIN
doc/images/Looking-Glass-OBS-Source-Add.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
BIN
doc/images/Looking-Glass-OBS-config.png
Normal file
BIN
doc/images/Looking-Glass-OBS-config.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 75 KiB |
|
|
@ -1,20 +1,27 @@
|
||||||
.. Looking Glass documentation master file, created by
|
|
||||||
sphinx-quickstart on Fri Mar 26 18:12:05 2021.
|
|
||||||
You can adapt this file completely to your liking, but it should at least
|
|
||||||
contain the root `toctree` directive.
|
|
||||||
|
|
||||||
Welcome to Looking Glass's documentation!
|
Welcome to Looking Glass's 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.
|
||||||
|
|
||||||
|
Categories:
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:caption: Contents:
|
|
||||||
|
|
||||||
|
install
|
||||||
|
troubleshooting
|
||||||
|
obs
|
||||||
|
faq
|
||||||
|
tech_faq
|
||||||
|
|
||||||
|
More information:
|
||||||
|
|
||||||
Indices and tables
|
* `Offical Website <https://looking-glass.io/>`_
|
||||||
==================
|
* `GitHub <https://github.com/gnif/LookingGlass>`_
|
||||||
|
* `Discord <https://discord.gg/52SMupxkvt>`_
|
||||||
* :ref:`genindex`
|
* `Forum <https://forum.level1techs.com/c/software/lookingglass/142>`_
|
||||||
* :ref:`modindex`
|
* `Community wiki <https://looking-glass.io/wiki/>`_
|
||||||
* :ref:`search`
|
|
||||||
|
|
|
||||||
350
doc/install.rst
Normal file
350
doc/install.rst
Normal file
|
|
@ -0,0 +1,350 @@
|
||||||
|
Installation
|
||||||
|
############
|
||||||
|
|
||||||
|
.. _looking_glass_client:
|
||||||
|
|
||||||
|
Looking Glass Client
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
This guide will step you through building the looking glass client from
|
||||||
|
source, before you attempt to do this you should have a basic
|
||||||
|
understanding of how to use the shell.
|
||||||
|
|
||||||
|
.. _building_the_application:
|
||||||
|
|
||||||
|
Building the Application
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. _installing_build_dependencies:
|
||||||
|
|
||||||
|
Installing Build Dependencies
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
These required libraries and tools should be installed first.
|
||||||
|
|
||||||
|
.. _required_dependencies:
|
||||||
|
|
||||||
|
Required Dependencies
|
||||||
|
'''''''''''''''''''''
|
||||||
|
|
||||||
|
- cmake
|
||||||
|
- gcc \| clang
|
||||||
|
- fonts-freefont-ttf
|
||||||
|
- libegl-dev
|
||||||
|
- libgl-dev
|
||||||
|
- libfontconfig1-dev
|
||||||
|
- libgmp-dev
|
||||||
|
- libsdl2-dev
|
||||||
|
- libsdl2-ttf-dev
|
||||||
|
- libspice-protocol-dev
|
||||||
|
- make
|
||||||
|
- nettle-dev
|
||||||
|
- pkg-config
|
||||||
|
|
||||||
|
.. _may_be_disabled:
|
||||||
|
|
||||||
|
May be disabled
|
||||||
|
<<<<<<<<<<<<<<<
|
||||||
|
|
||||||
|
These dependencies are required by default, but may be omitted if their
|
||||||
|
feature is disabled when running :ref:`cmake <client_building>`.
|
||||||
|
|
||||||
|
- Disable with ``cmake -DENABLE_BACKTRACE=no``
|
||||||
|
|
||||||
|
- binutils-dev
|
||||||
|
|
||||||
|
- Disable with ``cmake -DENABLE_X11=no``
|
||||||
|
|
||||||
|
- libx11-dev
|
||||||
|
- libxfixes-dev
|
||||||
|
- libxi-dev
|
||||||
|
- libxss-dev
|
||||||
|
|
||||||
|
- Disable with ``cmake -DENABLE_WAYLAND=no``
|
||||||
|
|
||||||
|
- libwayland-bin
|
||||||
|
- libwayland-dev
|
||||||
|
- wayland-protocols
|
||||||
|
|
||||||
|
You can fetch these dependencies on Debian systems with the following command:
|
||||||
|
|
||||||
|
``apt-get install binutils-dev cmake fonts-freefont-ttf libfontconfig1-dev
|
||||||
|
libsdl2-dev libsdl2-ttf-dev libspice-protocol-dev libx11-dev nettle-dev
|
||||||
|
wayland-protocols``
|
||||||
|
|
||||||
|
Downloading
|
||||||
|
^^^^^^^^^^^
|
||||||
|
|
||||||
|
Either visit the site at `Looking Glass Download
|
||||||
|
Page <https://looking-glass.io/downloads>`_
|
||||||
|
|
||||||
|
Or pull the lastest **bleeding-edge version** using the **git** command.
|
||||||
|
|
||||||
|
**Note: If you are using the latest bleeding-edge from the master branch
|
||||||
|
you MUST download/use the corresponding host application**
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
git clone --recursive https://github.com/gnif/LookingGlass.git
|
||||||
|
|
||||||
|
.. _client_building:
|
||||||
|
|
||||||
|
Building
|
||||||
|
^^^^^^^^
|
||||||
|
|
||||||
|
If you downloaded the file via the web link then you should have a 'zip'
|
||||||
|
file. Simply unzip and cd into the new directory. If you used 'git' then
|
||||||
|
cd into the 'LookingGlass' directory.
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
mkdir client/build
|
||||||
|
cd client/build
|
||||||
|
cmake ../
|
||||||
|
make
|
||||||
|
|
||||||
|
NOTE: The most common compile error is related to backtrace support. This can be disabled by adding the following option to the cmake command: **-DENABLE_BACKTRACE=0**, however, if you disable this and need support for a crash please be sure to use gdb to obtain a backtrace manually or there is nothing that can be done to help you.
|
||||||
|
|
||||||
|
Should this all go well you should be left with the file
|
||||||
|
**looking-glass-client**. Before you run the client you will first need
|
||||||
|
to configure either Libvirt or Qemu (whichever you prefer) and then set
|
||||||
|
up the Windows side service.
|
||||||
|
|
||||||
|
You can call the client from the build directory; or, you can make it
|
||||||
|
callable generally by adding the directory to your path or issuing
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
ln -s $(pwd)/looking-glass-client /usr/local/bin/
|
||||||
|
|
||||||
|
from the build directory.
|
||||||
|
|
||||||
|
.. _libvirt_configuration:
|
||||||
|
|
||||||
|
libvirt Configuration
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
This article assumes you already have a fully functional libvirt VM with
|
||||||
|
PCI Passthrough working on a dedicated monitor. If you do not please
|
||||||
|
ensure this is configured before you proceed.
|
||||||
|
|
||||||
|
If you use virt-manager, this guide also applies to you, since it uses
|
||||||
|
libvirt.
|
||||||
|
|
||||||
|
**If you are using QEMU directly, this does not apply to you.**
|
||||||
|
|
||||||
|
Add the following to the libvirt machine configuration inside the
|
||||||
|
'devices' section by running "virsh edit VM" where VM is the name of
|
||||||
|
your virtual machine.
|
||||||
|
|
||||||
|
.. code:: xml
|
||||||
|
|
||||||
|
<shmem name='looking-glass'>
|
||||||
|
<model type='ivshmem-plain'/>
|
||||||
|
<size unit='M'>32</size>
|
||||||
|
</shmem>
|
||||||
|
|
||||||
|
The memory size (show as 32 in the example above) may need to be
|
||||||
|
adjusted as per the :ref:`Determining Memory <determining_memory>` section.
|
||||||
|
|
||||||
|
.. _spice_server:
|
||||||
|
|
||||||
|
Spice Server
|
||||||
|
^^^^^^^^^^^^
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
- Find your ``<video>`` device, and set ``<model type='none'/>``
|
||||||
|
|
||||||
|
- If you can't find it, make sure you have a ``<graphics>``
|
||||||
|
device, save and edit again
|
||||||
|
- On older libvirt versions, just disable the device in Windows
|
||||||
|
Device Manager
|
||||||
|
|
||||||
|
- Remove the ``<input type='tablet'/>`` device, if you have one
|
||||||
|
- Create an ``<input type='mouse'/>`` device, if you don't already have one
|
||||||
|
- Create an ``<input type='keyboard' bus='virtio'/>`` device to improve
|
||||||
|
keyboard usage
|
||||||
|
|
||||||
|
- This requires the *vioinput* driver from
|
||||||
|
`virtio-win <https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/>`_
|
||||||
|
to be installed in the guest
|
||||||
|
|
||||||
|
If you want clipboard synchronization please see
|
||||||
|
:ref:`how_to_enable_clipboard_synchronization_via_spice`
|
||||||
|
|
||||||
|
AppArmor
|
||||||
|
^^^^^^^^
|
||||||
|
|
||||||
|
For libvirt versions before **5.10.0**, if you are using AppArmor, you
|
||||||
|
need to add permissions for QEMU to access the shared memory file. This
|
||||||
|
can be done by adding the following to
|
||||||
|
*/etc/apparmor.d/abstractions/libvirt-qemu*.
|
||||||
|
|
||||||
|
``/dev/shm/looking-glass rw,``
|
||||||
|
|
||||||
|
.. _qemu_commands:
|
||||||
|
|
||||||
|
Qemu Commands
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
**If you are using virt manager/libvirt then this does not apply to
|
||||||
|
you.**
|
||||||
|
|
||||||
|
Add the following to the commands to your QEMU command line, adjusting
|
||||||
|
the bus to suit your particular configuration:
|
||||||
|
|
||||||
|
.. 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
|
||||||
|
|
||||||
|
The memory size (show as 32 in the example above) may need to be
|
||||||
|
adjusted as per :ref:`Determining Memory <determining_memory>` section.
|
||||||
|
|
||||||
|
.. _determining_memory:
|
||||||
|
|
||||||
|
Determining Memory
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
You will need to adjust the memory size to a value that is suitable for
|
||||||
|
your desired maximum resolution using the following formula:
|
||||||
|
|
||||||
|
``width x height x 4 x 2 = total bytes``
|
||||||
|
|
||||||
|
``total bytes / 1024 / 1024 = total megabytes + 2``
|
||||||
|
|
||||||
|
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 + 2 = 17.82``
|
||||||
|
|
||||||
|
You must round this value up to the nearest power of two, which with the
|
||||||
|
above example would be 32MB
|
||||||
|
|
||||||
|
Note: This formula may be out of date. A 1440p display requires 64mb
|
||||||
|
shared memory.
|
||||||
|
|
||||||
|
The shared memory file will be located in /dev/shm/looking-glass and
|
||||||
|
will need to be created on every boot otherwise it will have incorrect
|
||||||
|
permissions. Looking glass will not be able to run unless it has
|
||||||
|
permissions to this file. You can create the shared memory file
|
||||||
|
automatically by adding the following config file:
|
||||||
|
|
||||||
|
``touch /etc/tmpfiles.d/10-looking-glass.conf``
|
||||||
|
|
||||||
|
Add the following content to the file::
|
||||||
|
|
||||||
|
#Type Path Mode UID GID Age Argument
|
||||||
|
|
||||||
|
f /dev/shm/looking-glass 0660 user kvm -
|
||||||
|
|
||||||
|
Be sure to set the UID to your local user.
|
||||||
|
|
||||||
|
.. _looking_glass_service_windows:
|
||||||
|
|
||||||
|
Looking Glass Service (Windows)
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
You must first run the Windows VM with the changes noted above in either
|
||||||
|
the :ref:`libvirt_configuration` or :ref:`qemu_commands` sections.
|
||||||
|
|
||||||
|
.. _installing_the_ivshmem_driver:
|
||||||
|
|
||||||
|
Installing the IVSHMEM Driver
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Windows will not prompt for a driver for the IVSHMEM device, instead, it
|
||||||
|
will use a default null (do nothing) driver for the device. To install
|
||||||
|
the IVSHMEM driver you will need to go into the device manager and
|
||||||
|
update the driver for the device "PCI standard RAM Controller" under the
|
||||||
|
"System Devices" node.
|
||||||
|
|
||||||
|
A signed Windows 10 driver can be obtained from Red Hat for this device
|
||||||
|
from the below address:
|
||||||
|
|
||||||
|
https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/upstream-virtio/
|
||||||
|
|
||||||
|
Please note that you must obtain version 0.1.161 or later
|
||||||
|
|
||||||
|
If the installation of the driver results in warnings or errors about
|
||||||
|
driver signatures, ensure secure boot is turned off for the virtual
|
||||||
|
machine bios/uefi.
|
||||||
|
|
||||||
|
.. _a_note_about_ivshmem_and_scream_audio:
|
||||||
|
|
||||||
|
A note about IVSHMEM and Scream Audio
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
Using IVSHMEM with Scream may interfere with Looking Glass, as they may try
|
||||||
|
to use the same device.
|
||||||
|
|
||||||
|
Please do not use the IVSHMEM plugin for Scream.
|
||||||
|
Use the default network transfer method. The IVSHMEM method induces
|
||||||
|
additional latency that is built into its implementation. When using
|
||||||
|
VirtIO for a network device the VM is already using a highly optimized
|
||||||
|
memory copy anyway so there is no need to make another one.
|
||||||
|
|
||||||
|
If you insist on using IVSHMEM for Scream—despite its inferiority to the
|
||||||
|
default network implementation—the Windows Host Application can be told
|
||||||
|
what device to use. Create a ``looking-glass-host.ini`` file in the same
|
||||||
|
directory as the looking-glass-host.exe file. In it, you can use the
|
||||||
|
``os:shmDevice`` option like so:
|
||||||
|
|
||||||
|
.. code:: INI
|
||||||
|
|
||||||
|
[os]
|
||||||
|
shmDevice=1
|
||||||
|
|
||||||
|
.. _using_the_windows_host_application:
|
||||||
|
|
||||||
|
Using the Windows Host Application
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Start by downloading the correct version for your release from
|
||||||
|
https://looking-glass.io/downloads. You can either choose between
|
||||||
|
**Official Releases**, which are stable; or **Release Candidates**, new versions
|
||||||
|
about to be stable, but haven't passed validation.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
If your **looking-glass-client** was created by building from the **master
|
||||||
|
branch** you have to pick the **Bleeding Edge** version.
|
||||||
|
|
||||||
|
Next, use `7-Zip <7-zip.org/>`_ to extract the zip archive using the commit
|
||||||
|
hash for the password. Then, run the ``looking-glass-host-setup.exe`` installer
|
||||||
|
and click through it. By default, the installer will install a service that
|
||||||
|
automatically starts the host application at boot. The installer can
|
||||||
|
also be installed in silent mode with the ``/S`` switch. Other command
|
||||||
|
line options for the installer are documented by running it with the
|
||||||
|
``/h`` switch. There is also an unofficial Chocolatey package available,
|
||||||
|
install with ``choco install looking-glass-host --pre``.
|
||||||
|
|
||||||
|
The windows host application captures the windows desktop and stuffs the
|
||||||
|
frames into the shared memory via the shared memory virtual device,
|
||||||
|
without this Looking Glass will not function. It is critical that the
|
||||||
|
version of the host application matches the version of the client
|
||||||
|
application, as differing versions can be, and usually are,
|
||||||
|
incompatible.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
As of 2020-10-23, Microsoft Defender is known to mark the
|
||||||
|
Looking-Glass host executable as a virus and in some cases will
|
||||||
|
automatically delete the file.
|
||||||
|
|
||||||
|
.. _running_the_client:
|
||||||
|
|
||||||
|
Running the Client
|
||||||
|
------------------
|
||||||
|
|
||||||
|
The client command is the binary file: **looking-glass-client**. This
|
||||||
|
command should run after the Windows Host Application has started.
|
||||||
|
|
||||||
|
For an updated list of arguments visit:
|
||||||
|
https://github.com/gnif/LookingGlass/blob/master/client/README.md
|
||||||
|
|
||||||
|
Common options include ``-s`` for disabling spice, ``-S`` for disabling the
|
||||||
|
screen saver, and ``-F`` to automatically enter full screen.
|
||||||
89
doc/obs.rst
Normal file
89
doc/obs.rst
Normal file
|
|
@ -0,0 +1,89 @@
|
||||||
|
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' experience watching your stream, and
|
||||||
|
allows you to use your host without them seeing.
|
||||||
|
|
||||||
|
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 <looking_glass_client>`.
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The OBS plugin requires the following extra dependencies alongside the
|
||||||
|
:ref:`client's build
|
||||||
|
dependencies <installing_build_dependencies>`.
|
||||||
|
|
||||||
|
- libobs-dev
|
||||||
|
|
||||||
|
Please install this package or the equivalent in your package manager... code:: bash
|
||||||
|
|
||||||
|
apt-get install libobs-dev
|
||||||
|
|
||||||
|
|
||||||
|
.. _obs_building:
|
||||||
|
|
||||||
|
Building
|
||||||
|
^^^^^^^^
|
||||||
|
|
||||||
|
These instructions are the same as when building the
|
||||||
|
:ref:`client <client_building>`.
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
mkdir obs/build
|
||||||
|
cd obs/build
|
||||||
|
cmake ../
|
||||||
|
make
|
||||||
|
|
||||||
|
Installation
|
||||||
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The resulting liblooking-glass-obs.so file should be placed in your OBS
|
||||||
|
plugin directory.
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
mkdir -p ~/.config/obs-studio/plugins/looking-glass-obs/bin/64bit
|
||||||
|
cp liblooking-glass-obs.so ~/.config/obs-studio/plugins/looking-glass-obs/bin/64bit
|
||||||
|
|
||||||
|
Setup
|
||||||
|
~~~~~
|
||||||
|
|
||||||
|
Once installed, you can select the *"Looking Glass Client"* source from
|
||||||
|
the OBS sources menu. The configuration only requires the IVSHMEM file
|
||||||
|
that is 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/
|
||||||
|
|
||||||
|
It's available under most distributions as *obs-studio* or just *obs*.
|
||||||
|
|
||||||
|
Screenshots
|
||||||
|
~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. figure:: images/Looking-Glass-OBS-Source-Add.png
|
||||||
|
:alt: Adding the plugin as a video source
|
||||||
|
|
||||||
|
Adding the plugin as a video source
|
||||||
|
|
||||||
|
.. figure:: images/Looking-Glass-OBS-config.png
|
||||||
|
:alt: Plugin configuration settings
|
||||||
|
|
||||||
|
Plugin configuration settings
|
||||||
66
doc/tech_faq.rst
Normal file
66
doc/tech_faq.rst
Normal file
|
|
@ -0,0 +1,66 @@
|
||||||
|
Technical FAQ
|
||||||
|
#############
|
||||||
|
|
||||||
|
This FAQ is targetted at developers or technical people that want to
|
||||||
|
know more about what's going on under the hood.
|
||||||
|
|
||||||
|
.. _ivshmemshared_ram:
|
||||||
|
|
||||||
|
IVSHMEM/Shared RAM
|
||||||
|
------------------
|
||||||
|
|
||||||
|
.. _what_exactly_is_the_ivshmem_device:
|
||||||
|
|
||||||
|
What exactly 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.
|
||||||
|
|
||||||
|
.. _what_is_the_ivshmem_device_being_used_for:
|
||||||
|
|
||||||
|
What is the IVSHMEM device being used for?
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. _why_do_you_need_the_mouse_positional_information:
|
||||||
|
|
||||||
|
Why do you need the mouse positional information?
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. _why_does_lg_poll_for_updates_instead_of_using_interrupts:
|
||||||
|
|
||||||
|
Why does LG poll for updates instead of using interrupts?
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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.
|
||||||
92
doc/troubleshooting.rst
Normal file
92
doc/troubleshooting.rst
Normal file
|
|
@ -0,0 +1,92 @@
|
||||||
|
Troubleshooting
|
||||||
|
###############
|
||||||
|
|
||||||
|
There are many different issues that can arise when setting up Looking
|
||||||
|
Glass. Below is a list of known issues with potential solutions:
|
||||||
|
|
||||||
|
.. _when_launching_looking_glass_the_desktop_doesnt_appear:
|
||||||
|
|
||||||
|
When Launching Looking Glass the Desktop Doesn't Appear
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
- **Using an AMD GPU?**
|
||||||
|
|
||||||
|
- After the end of the Radeon HD Series AMD started incorporating a
|
||||||
|
feature into their GPU's that effectively puts the card to sleep
|
||||||
|
when no display is connected. For this reason one of two
|
||||||
|
conditions need to be met.
|
||||||
|
|
||||||
|
#. The GPU needs to remain plugged into a monitor (this is good for
|
||||||
|
testing & troubleshooting).
|
||||||
|
#. The GPU needs to have a plug like the ones used in GPU Crypto mining
|
||||||
|
installed to trick the card into thinking that a display is
|
||||||
|
connected.
|
||||||
|
|
||||||
|
.. _the_clipboard_is_not_working:
|
||||||
|
|
||||||
|
The Clipboard is not Working
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
- **Did you enable it?**
|
||||||
|
|
||||||
|
- Before you can Copy/Paste content between the Guest and the Host
|
||||||
|
you must `Enable Clipboard
|
||||||
|
Synchronization <https://looking-glass.hostfission.com/wiki/FAQ#How_to_enable_clipboard_synchronization_via_SPICE>`_
|
||||||
|
|
||||||
|
- **Did you install the Spice Guest Tools?**
|
||||||
|
|
||||||
|
- Before you can Copy/Paste content between the Guest and the Host
|
||||||
|
you must install the `SPICE Guest Tools
|
||||||
|
driver <https://www.spice-space.org/download.html>`_. The
|
||||||
|
download is labeled as "spice-guest-tools".
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
**NOTE: Do make sure that you do NOT install the QEMU Guest
|
||||||
|
Tools driver. These are not the same.**
|
||||||
|
|
||||||
|
- **Are you using Wayland?**
|
||||||
|
|
||||||
|
- Clipboard functionality is not compatible with Wayland. If you are
|
||||||
|
using it you need to disable it for the clipboard to work.
|
||||||
|
|
||||||
|
.. _followed_installation_instructions_but_looking_glass_still_doesnt_launch:
|
||||||
|
|
||||||
|
Followed Installation Instructions but Looking Glass Still Doesn't Launch
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
At times depending on your distribution circumstances can cause Looking
|
||||||
|
Glass to still not run. Below is a list of known issues that can prevent
|
||||||
|
Looking Glass from running properly.
|
||||||
|
|
||||||
|
AppArmor
|
||||||
|
^^^^^^^^
|
||||||
|
|
||||||
|
AppArmor is a security application that can prevent Looking Glass from
|
||||||
|
running. How to add security exceptions may vary on your distribution:
|
||||||
|
|
||||||
|
Debian(Ubuntu)
|
||||||
|
''''''''''''''
|
||||||
|
|
||||||
|
Start by opening the file ``/etc/apparmor.d/abstractions/libvirt-qemu``.
|
||||||
|
Now locate and edit the following lines to represent how they appear in
|
||||||
|
the example:
|
||||||
|
|
||||||
|
.. code:: text
|
||||||
|
|
||||||
|
# for usb access
|
||||||
|
/dev/bus/usb/** rw,
|
||||||
|
/etc/udev/udev.conf r,
|
||||||
|
/sys/bus/ r,
|
||||||
|
/sys/class/ r,
|
||||||
|
/run/udev/data/* rw,
|
||||||
|
/dev/input/* rw,
|
||||||
|
|
||||||
|
# Looking Glass
|
||||||
|
/dev/shm/looking-glass rw,
|
||||||
|
|
||||||
|
Save, exit, and restart AppArmor:
|
||||||
|
|
||||||
|
.. code:: text
|
||||||
|
|
||||||
|
sudo systemctl restart apparmor
|
||||||
Loading…
Reference in a new issue