diff --git a/doc/conf.py b/doc/conf.py index cb4f323d..f66cbfb0 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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'] \ No newline at end of file +# html_static_path = ['_static'] diff --git a/doc/faq.rst b/doc/faq.rst new file mode 100644 index 00000000..d42606e4 --- /dev/null +++ b/doc/faq.rst @@ -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 `, 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 + + + + +
+ + +.. _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 `_, 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. diff --git a/doc/images/Looking-Glass-OBS-Source-Add.png b/doc/images/Looking-Glass-OBS-Source-Add.png new file mode 100644 index 00000000..78a0b0d1 Binary files /dev/null and b/doc/images/Looking-Glass-OBS-Source-Add.png differ diff --git a/doc/images/Looking-Glass-OBS-config.png b/doc/images/Looking-Glass-OBS-config.png new file mode 100644 index 00000000..2f42a2b6 Binary files /dev/null and b/doc/images/Looking-Glass-OBS-config.png differ diff --git a/doc/index.rst b/doc/index.rst index bed92f3a..9a1b59f7 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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 `_ +* `GitHub `_ +* `Discord `_ +* `Forum `_ +* `Community wiki `_ diff --git a/doc/install.rst b/doc/install.rst new file mode 100644 index 00000000..37d45453 --- /dev/null +++ b/doc/install.rst @@ -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 `. + +- 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 `_ + +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 + + + + 32 + + +The memory size (show as 32 in the example above) may need to be +adjusted as per the :ref:`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 +```` device, then: + +- Find your ``