mirror of
https://github.com/gnif/LookingGlass.git
synced 2024-11-09 16:18:20 +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:
parent
5b0ca835f8
commit
91e55b9d5f
@ -18,8 +18,8 @@
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'Looking Glass'
|
||||
copyright = '2021, Geoffrey McRae, quantum, xyenne, other contributors on GitHub.'
|
||||
author = 'Geoffrey McRae, quantum, xyenne, other contributors on GitHub.'
|
||||
copyright = '2021, Geoffrey McRae, quantum, xyenne, and other contributors'
|
||||
author = 'Geoffrey McRae, quantum, xyenne, and other contributors'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = 'B4'
|
||||
@ -34,7 +34,7 @@ extensions = [
|
||||
]
|
||||
|
||||
# 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.
|
||||
@ -52,4 +52,4 @@ html_theme = 'alabaster'
|
||||
# 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,
|
||||
# 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!
|
||||
=========================================
|
||||
|
||||
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::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
install
|
||||
troubleshooting
|
||||
obs
|
||||
faq
|
||||
tech_faq
|
||||
|
||||
More information:
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
* `Offical Website <https://looking-glass.io/>`_
|
||||
* `GitHub <https://github.com/gnif/LookingGlass>`_
|
||||
* `Discord <https://discord.gg/52SMupxkvt>`_
|
||||
* `Forum <https://forum.level1techs.com/c/software/lookingglass/142>`_
|
||||
* `Community wiki <https://looking-glass.io/wiki/>`_
|
||||
|
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 New Issue
Block a user