diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 5e761f31..dee3729d 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,73 +1,84 @@ --- name: Bug report -about: Report bugs in Looking Glass (only confirmed bugs and feature requests please) - +about: Report a reproducible Looking Glass fault --- -### Issues are for Bug Reports and Feature Requests Only! +## Before reporting -If you are looking for help or support please use one of the following methods +Use the forum or Discord for setup help: -Create a New Topic on the Level1Tech's forum under the Looking Glass category: -* https://forum.level1techs.com/c/software/lookingGlass/142 +- https://forum.level1techs.com/c/software/lookingGlass/142 +- https://discord.gg/52SMupxkvt -Ask for help in the Looking Glass discord server -* https://discord.gg/52SMupxkvt +Use GitHub issues for reproducible bugs and feature requests. Check the current +documentation and existing issues first. Do not report a protocol mismatch +until the client, IDD and OBS plugin have been updated to the same release. -*Issues that are not bug reports or feature requests will be closed & ignored* +## Describe the fault -### Errors that are not bugs - -Some errors generated by the LG client are not bugs, but rather issues with your -system's configuration and/or timing. Please do not report these, but rather use -one of the above resources to ask for advice/help. - -* `LGMP_ERR_QUEUE_UNSUBSCRIBED` - Failure to heed advice on things such as -using `isolcpus` and CPU pinning may result in this message, especially if you -are over-taxing your CPU. - -* `Could not create an SDL window: *` - Failure to create a SDL window is not an -issue with Looking Glass but rather a more substantial issue with your system, -such as missing hardware support for the RGBA32 pixmap format, or missing -required OpenGL EGL features. - -* `The host application is not compatible with this client` - The Looking Glass - Host application in Windows is the incorrect version and is not compatible, -you need to make sure you run matching versions of both the host and client -applications. - -### Bug Report Required Information - -The entire (not truncated) output from the client application (if applicable). -To obtain this run `looking-glass-client` in a terminal. +What happened, what did you expect, and what exact steps reproduce it? ``` -PASTE CLIENT OUTPUT HERE +DESCRIPTION AND STEPS ``` -The entire (not truncated) log file from the host application (if applicable). -Normally, this is found on the guest system at: - - %ProgramData%\Looking Glass (host)\looking-glass-host.txt - -This log may be quite long, please delete the file first and then proceed to -launch the host and reproduce the issue so that the log only contains the -pertinent information. - +Does it reproduce every time? If not, how often? ``` -PASTE HOST LOG FILE CONTENTS HERE +REPRODUCTION RATE ``` -If the client is unexpectedly exiting without a backtrace, please provide one via -gdb with the command `thread apply all bt`. If you are unsure how to do this -please watch the video below on how to perform a Debug build and generate this -backtrace. +## Versions and system -https://www.youtube.com/watch?v=EqxxJK9Yo64 +- Looking Glass Client version: +- Looking Glass IDD or legacy Host version: +- OBS plugin version, if applicable: +- Linux distribution and kernel: +- X11 or Wayland, and compositor: +- Host GPU and driver: +- Guest GPU and driver, or IDD software mode: +- Guest resolution and refresh rate: +- Primary transport (`lgmp` or `spice`): +- DMA enabled and successfully imported: +## Client output + +Run `looking-glass-client` from a terminal, reproduce the fault and include its +complete output from startup. Do not include only the final error. ``` -PASTE FULL BACKTRACE HERE +PASTE COMPLETE CLIENT OUTPUT ``` +## Windows logs + +For the IDD, use its notification-area helper to open +`C:\ProgramData\Looking Glass (IDD)` and attach the current files plus rotated +files from the affected run: + +- `looking-glass-idd.txt` +- `looking-glass-input.txt` +- `looking-glass-idd-service.txt` +- `looking-glass-idd-helper.txt` + +For the legacy Host Application, attach: + +- `C:\ProgramData\Looking Glass (host)\looking-glass-host.txt` +- `C:\ProgramData\Looking Glass (host)\looking-glass-host-service.txt` + +## Crash backtrace + +For a client crash without a complete built-in trace, run the client under +`gdb`, reproduce it, then run: + +``` +thread apply all bt full +``` + +Attach that output and keep the matching `looking-glass-client.debug` file +available. + +## Additional evidence + +Attach screenshots, timing graphs, OBS logs or short recordings when they make +the fault clearer. State which settings differ from their defaults. diff --git a/README.md b/README.md index ea194c0c..6ac5a6c8 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,27 @@ # Looking Glass -An extremely low latency KVMFR (KVM FrameRelay) implementation for guests with -VGA PCI Passthrough. +Looking Glass lets you use a Windows virtual machine from Linux with very low +display and input latency. The current recommended setup uses the Looking Glass +Indirect Display Driver (IDD) in the Windows guest and the Looking Glass Client +on the Linux host. * Project Website: https://looking-glass.io * Documentation: https://looking-glass.io/docs -## Documentation +## Start here + +The Linux client is currently distributed as source code and must be built +before it can be installed. The end-user guide covers the complete process: + +1. Build the Linux client. +2. Configure shared memory for the virtual machine. +3. Install the Looking Glass IDD in Windows. +4. Install and run the client. + +See the [Looking Glass documentation](https://looking-glass.io/docs) for the +current requirements and setup guide. + +## Source archives ❕❕❕ **IMPORTANT** ❕❕❕ @@ -16,7 +31,7 @@ Glass, please download the source archive from the website instead: https://looking-glass.io/downloads -Source code for the documentation can be found in the `/doc` directory. +Source code for the documentation can be found in the `doc` directory. You may view this locally as HTML by running `make html` with `python3-sphinx` and `python3-sphinx-rtd-theme` installed. diff --git a/client/DEBUGGING.md b/client/DEBUGGING.md index d51e06d2..59e07614 100644 --- a/client/DEBUGGING.md +++ b/client/DEBUGGING.md @@ -1,32 +1,49 @@ # Debugging the Looking Glass Client -If you are asked to provide debugging information to resolve an issue please -follow the following procedure. +Start by running `looking-glass-client` in a terminal and retain its complete +output from startup through the fault. It records the selected transport, +renderer, display server, import method and audio backend. -## If you're experiencing a crash: +## Crashes -Run the program under the `gdb` debugger (you may need to install gdb), for -example: +Run the matching binary under `gdb`: - gdb ./looking-glass-client +```text +gdb ./looking-glass-client +``` -If you need to set any arguments, do so now by running `set args ARGS`, for -example: +Set arguments when needed: - set args -F -k +```text +set args -F -k +``` -Now start the program by typing `r`. When the application crashes you will be -dumped back into the debugger, the application may appear to be frozen. Run -the following command: +Start with `run`. After the crash, collect every thread and local variable: - thread apply all bt +```text +thread apply all bt full +``` -Once you have this information please pastebin the log from looking-glass as -well as the information resulting from this command. +Provide that output together with the complete client log. Keep +`looking-glass-client.debug` from the same build; installed builds place it in +the standard `bin/.debug` location. -## If you're experencing high CPU load and/or poor performance. +## Hangs or high CPU use -The steps here are identical to the above, except instead of waiting for the -program to crash, in the debugger press `CTRL+C` while the program is -exhibiting the problem, then run `thread apply all bt` and pastebin your log -and the results of the command. +Run under `gdb` as above. While the fault is visible, press `Ctrl+C` in the +debugger and collect: + +```text +thread apply all bt full +``` + +For an intermittent stall, collect several samples rather than one. Include +the frame-timing graph when it helps identify the affected stage. + +## IDD faults + +Use the Windows IDD helper to open +`C:\ProgramData\Looking Glass (IDD)`. Collect the IDD, input, service and helper +logs, including rotated `.1` through `.4` files when the fault happened before +the latest restart. See the end-user IDD diagnostics page for the exact file +names. diff --git a/client/src/audio.c b/client/src/audio.c index 39b858a9..2c83ad51 100644 --- a/client/src/audio.c +++ b/client/src/audio.c @@ -2305,9 +2305,9 @@ static PlaybackDataResult playbackData(const void * data, size_t frameCount, const int maxPeriodFrames = max(audio.playback.deviceMaxPeriodFrames, sourceData->devPeriodFrames); /* The device period, delivery jitter, packet phase, and resampler delay - * define the minimum viable latency. latencyOffset is strictly an additive - * user offset over that same minimum for both startup and steady state. */ - const double latencyOffsetFrames = + * define the minimum viable latency. Provider feedback directly controls + * the source rate, so latencyOffset only applies to local rate control. */ + const double latencyOffsetFrames = providerRateControl ? 0.0 : max(g_params.audioLatencyOffset, 0) * audio.playback.sampleRate / 1000.0; const double arrivalReserveFrames = diff --git a/client/transports/SPICE/spice.c b/client/transports/SPICE/spice.c index 54d08696..c35dd919 100644 --- a/client/transports/SPICE/spice.c +++ b/client/transports/SPICE/spice.c @@ -86,9 +86,9 @@ static void spiceSetup(void) { .module = "spice", .name = "usbAudio", - .description = "Use USB redirection for SPICE audio playback", + .description = "Use the emulated USB audio device", .type = OPTION_TYPE_BOOL, - .value.x_bool = false + .value.x_bool = true }, {0} }; diff --git a/doc/audio.rst b/doc/audio.rst new file mode 100644 index 00000000..780f54ad --- /dev/null +++ b/doc/audio.rst @@ -0,0 +1,131 @@ +.. _client_audio: + +Audio and microphone +#################### + +The client selects audio independently from video and input. The current LGMP +transport does not provide audio, so SPICE normally supplies it in an IDD +setup. Selecting SPICE as the primary video transport also uses its audio +provider. + +.. warning:: + + Do not use Scream for a Looking Glass setup. Use the built-in classic SPICE + or USB audio path. Scream over IVSHMEM can also conflict with the shared + device used for Looking Glass frames. + +Looking Glass offers two SPICE audio paths: + +USB audio (recommended) + Presents an emulated Looking Glass USB Audio Class 2 device to Windows over + a SPICE USB channel. It supports stereo, quadraphonic, 5.1 and 7.1 playback + using 24-bit PCM at up to 192 kHz. It also provides asynchronous playback + feedback and a lower-latency clock relationship with supported Linux audio + backends. This path is enabled by default when it is available. + +Classic SPICE audio + Uses a virtual guest sound card and SPICE playback and record channels. + QEMU limits it to stereo, 16-bit samples at 48 kHz. Use it as a compatibility + fallback when the emulated USB audio device is not available. + +Set ``spice:audio=no`` to disable both paths. + +.. _client_usb_audio: + +USB audio setup +--------------- + +USB audio requires: + +* a client built with ``libusbredirparser-0.5`` version 0.7.1 or newer; +* at least one unused SPICE USB redirection channel in the VM; and +* a working client playback backend. + +For libvirt, add a USB redirection device: + +.. code:: xml + + + +In virt-manager, this is a **USB Redirector** device using the SPICE channel. +It is dedicated to the virtual Looking Glass audio device while USB audio is +active. + +The emulated USB audio device is enabled by default. Its settings are: + +.. code-block:: ini + + [spice] + audio=yes + usbAudio=yes + +Playback supports stereo, quadraphonic, 5.1 and 7.1 speaker layouts using +24-bit PCM at sample rates up to 192 kHz. Recording supports stereo at up to +192 kHz. + +After the device connects, select the Looking Glass USB Audio speakers as the +Windows output device. + +If USB audio could not be created at startup, the client falls back to classic +SPICE audio and logs the reason. A working USB audio device also requires the +SPICE USB redirection channel to connect; if the channel is absent, add it to +the VM rather than reinstalling the Windows endpoint. + +Classic SPICE setup +------------------- + +Add an Intel HDA sound device and a SPICE audio backend to the VM as shown in +:ref:`libvirt_spice_server`, then select the classic path: + +.. code-block:: ini + + [spice] + audio=yes + usbAudio=no + +QEMU's classic SPICE audio implementation exposes a fixed stereo format: two +channels, 16-bit samples at 48 kHz. Use the emulated USB audio device when +other sample rates, sample formats or channel layouts are required. + +Microphone access +----------------- + +PipeWire supports playback and recording. The current PulseAudio backend does +not provide microphone recording. Press :kbd:`ScrLk` + :kbd:`E` to toggle +recording when it is available. + +When a guest application opens the microphone, ``audio:micDefault`` controls +the response: + +``prompt`` + Ask before sending microphone audio. This is the default. + +``allow`` + Allow requests automatically. + +``deny`` + Refuse requests automatically. + +Press :kbd:`ScrLk` + :kbd:`C` to cycle this policy. Keep +``audio:micShowIndicator=yes`` to show when recording is active. + +Latency settings +---------------- + +``audio:periodSize`` requests the audio backend period in samples. The default +is 512; 0 requests a 10 ms period. Smaller values may reduce latency but also +make underruns more likely. + +``audio:latencyOffset`` applies only to classic SPICE audio. It adds safety +margin to the calculated minimum buffer; the default is 6 ms. Reduce it only +after confirming that classic SPICE playback remains free of dropouts under +load. + +``audio:resampler`` also applies only to classic SPICE audio. The default +``auto`` setting chooses the appropriate path; the other choices are +``libsamplerate`` and ``backend``. The emulated USB audio device instead uses +feedback to adjust the Windows packet rate. + +Set ``audio:debug=yes`` to log ring-buffer level, backend delay, clock feedback +and underrun or overrun counts. Disable it after diagnosis to keep the normal +log concise. diff --git a/doc/build.rst b/doc/build.rst index 91719370..ac1e0cea 100644 --- a/doc/build.rst +++ b/doc/build.rst @@ -1,11 +1,11 @@ .. _building: -Building -######## +Build the Linux client +###################### -The following instructions will help you build Looking Glass from source code. -Before attempting this, you should have a basic understanding of -how to use the shell. +The Looking Glass Client is currently distributed as source code. Building it +is a normal part of installation, not an optional developer step. These +instructions require basic familiarity with a Linux shell. .. _download_source: @@ -32,8 +32,10 @@ Developers can clone the source code repo with ``git``. .. note:: - When using the latest bleeding-edge client version, - you *MUST* download and install the corresponding host application. + The current client, IDD and OBS plugin must come from the same Looking Glass + release. Bleeding-edge builds must be paired with their matching + bleeding-edge components. Legacy Host users must instead use the complete + matching B7 stack described in :ref:`legacy_host_policy`. .. _build_client_section: @@ -75,6 +77,7 @@ Required dependencies - ``libfontconfig-dev`` - ``libgmp-dev`` - ``libspice-protocol-dev`` +- ``libxkbcommon-dev`` - ``make`` - ``nettle-dev`` - ``pkg-config`` @@ -101,10 +104,10 @@ feature is disabled when running :ref:`cmake `. - ``libxss-dev`` - ``libxcursor-dev`` - ``libxpresent-dev`` + - ``libxrandr-dev`` - Disable with ``cmake -DENABLE_WAYLAND=no ..`` - - ``libxkbcommon-dev`` - ``libwayland-bin`` - ``libwayland-dev`` @@ -113,6 +116,7 @@ feature is disabled when running :ref:`cmake `. - ``libpipewire-0.3-dev`` - ``libpulse-dev`` - ``libsamplerate0-dev`` + - ``libusbredirparser-dev`` - Disable with ``cmake -DENABLE_PIPEWIRE=no ..`` @@ -122,6 +126,10 @@ feature is disabled when running :ref:`cmake `. - ``libpulse-dev`` +- Disable USB audio with ``cmake -DENABLE_USB_AUDIO=no ..`` + + - ``libusbredirparser-dev`` version 0.7.1 or newer + ``libsamplerate0-dev`` is required whenever audio support remains enabled. .. _client_deps_recommended: @@ -141,20 +149,21 @@ You can fetch these dependencies with the following command: .. warning:: - Do not just blindly install the list below, check if you are using PipeWire - or PulseAudio and adjust the list accordingly. Installing PipeWire libraries - on a PulseAudio system will result in a broken partial PipeWire install. - - If you are not already using PipeWire we highly recommend you upgrade, - Looking Glass does not support audio input (microphone) with PulseAudio. + The command below builds both PipeWire and PulseAudio playback backends. + Omit one development package only when also disabling its backend in CMake. + Microphone recording requires PipeWire; the current PulseAudio backend is + playback-only. .. code:: bash - apt-get install binutils cmake fonts-dejavu-core libdw-dev libfontconfig-dev \ - libunwind-dev gcc g++ pkg-config libegl-dev libgl-dev libgles-dev \ - libspice-protocol-dev nettle-dev libx11-dev libxcursor-dev libxi-dev libxinerama-dev \ - libxpresent-dev libxss-dev libxkbcommon-dev libwayland-dev \ - libpipewire-0.3-dev libpulse-dev libsamplerate0-dev + apt-get install binutils cmake make fonts-dejavu-core libdw-dev \ + libfontconfig-dev libgmp-dev libunwind-dev gcc g++ pkg-config \ + libegl-dev libgl-dev libgles-dev libspice-protocol-dev nettle-dev \ + libx11-dev libxcursor-dev libxfixes-dev libxi-dev libxinerama-dev \ + libxpresent-dev libxrandr-dev libxss-dev libxkbcommon-dev \ + libwayland-bin libwayland-dev \ + libpipewire-0.3-dev libpulse-dev libsamplerate0-dev \ + libusbredirparser-dev You may omit some dependencies if you disable the feature which requires them when running :ref:`cmake `. @@ -219,8 +228,15 @@ it directly from the build directory: .. _host_building: -Host Application ----------------- +Legacy Host Application build +----------------------------- + +.. warning:: + + The Host Application is a legacy frame producer. New installations should + use the prebuilt :doc:`Looking Glass IDD `. These build + instructions are retained for the complete matching B7 stack described in + :ref:`legacy_host_policy`. .. note:: diff --git a/doc/conf.py b/doc/conf.py index 90371259..1469681f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -22,7 +22,7 @@ from lgrelease import release # -- Project information ----------------------------------------------------- project = 'Looking Glass' -copyright = '2024, Looking Glass team' +copyright = '2026, Looking Glass team' author = 'Geoffrey McRae and the Looking Glass team' rst_prolog = """ @@ -55,7 +55,7 @@ else: spelling_word_list_filename = [os.path.join(os.path.dirname(__file__), 'words.txt')] # Add any paths that contain templates here, relative to this directory. -# templates_path = ['_templates'] +templates_path = ['templates/'] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -78,10 +78,15 @@ html_unescape_onlyinclude = [] # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' +html_theme = 'lookingglass' + +html_theme_path = [ + 'theme/', +] html_theme_options = { 'logo_only': True, + 'prev_next_buttons_location': 'both', 'style_nav_header_background': '#343131', } diff --git a/doc/css/lg-custom.css b/doc/css/lg-custom.css index 9f03ac49..d88fdec3 100644 --- a/doc/css/lg-custom.css +++ b/doc/css/lg-custom.css @@ -1,17 +1,9 @@ -/* Center content in the RTD theme */ -@media screen and (min-width: 1100px) { - .wy-nav-content-wrap { - margin-left: auto; - } - - .wy-nav-content { - margin: auto; - } -} - -@media screen and (min-width:769px) and (max-width:1420px) { +/* Align content with the navigation menu */ +@media screen and (min-width: 769px) { .wy-nav-content-wrap { + background: #edf0f2; margin-left: 300px; + padding-left: 12px; } .wy-nav-content { @@ -19,6 +11,31 @@ } } +/* Allow documentation tables to wrap long descriptions */ +.wy-table-responsive table td, +.wy-table-responsive table th { + white-space: normal; +} + +/* Keep cryptocurrency donation addresses compact and copyable */ +.donation-address { + margin: .5em 0; +} + +.donation-address summary { + cursor: pointer; +} + +.donation-address code { + display: block; + margin-top: .5em; + overflow-wrap: anywhere; + padding: .5em; + user-select: all; + white-space: normal; + word-break: break-all; +} + /* Make look like a key */ kbd { background-color: #eee; @@ -32,3 +49,340 @@ kbd { padding: 2px 4px; white-space: nowrap; } + +/* Follow the system colour preference */ +@media screen and (prefers-color-scheme: dark) { + html { + color-scheme: dark; + } + + body, + .wy-body-for-nav, + .wy-nav-content-wrap { + background: #0d1117; + color: #c9d1d9; + } + + .wy-nav-content { + background: #161b22; + } + + h1, + h2, + h3, + h4, + h5, + h6, + .rst-content .toc-backref, + .rst-content code.xref, + .rst-content tt.xref { + color: #f0f6fc; + } + + .rst-content a { + color: #58a6ff; + } + + .rst-content a:visited { + color: #bc8cff; + } + + .rst-content a:hover, + .rst-content a:focus { + color: #79c0ff; + } + + hr { + border-color: #30363d; + } + + footer, + .rst-content table.docutils.footnote, + html.writer-html4 .rst-content table.docutils.citation, + html.writer-html5 .rst-content aside.footnote, + html.writer-html5 .rst-content aside.footnote-list aside.footnote, + html.writer-html5 .rst-content div.citation-list > div.citation, + html.writer-html5 .rst-content dl.citation, + html.writer-html5 .rst-content dl.footnote { + color: #8b949e; + } + + .btn-neutral, + .btn-neutral:visited { + background-color: #21262d !important; + color: #f0f6fc !important; + } + + .btn-neutral:hover { + background-color: #30363d !important; + color: #fff !important; + } + + label, + .wy-checkbox, + .wy-radio, + .wy-text-neutral { + color: #c9d1d9 !important; + } + + input, + select, + textarea, + .wy-side-nav-search input[type="text"] { + background-color: #0d1117; + border-color: #484f58; + box-shadow: inset 0 1px 3px #010409; + color: #f0f6fc; + } + + input[disabled], + input[readonly], + select[disabled], + select[readonly], + textarea[disabled], + textarea[readonly] { + background-color: #21262d !important; + color: #8b949e; + } + + .wy-nav-side, + .wy-side-scroll { + background: #161b22; + } + + .wy-menu-vertical li.current { + background: #21262d; + } + + .wy-menu-vertical li.current a { + border-color: #30363d; + color: #c9d1d9; + } + + .wy-menu-vertical li.current a:hover, + .wy-menu-vertical li.current > a, + .wy-menu-vertical li.on a, + .wy-menu-vertical li.current > a:hover, + .wy-menu-vertical li.on a:hover { + background: #30363d; + color: #f0f6fc; + } + + .wy-menu-vertical li.toctree-l1.current > a { + border-color: #484f58; + } + + .wy-menu-vertical li.toctree-l2.current > a, + .wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a, + .wy-menu-vertical li.toctree-l3.current > a, + .wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a { + background: #262c36; + color: #f0f6fc; + } + + .wy-menu-vertical li.current > a button.toctree-expand, + .wy-menu-vertical li.on a button.toctree-expand, + .wy-menu-vertical li button.toctree-expand { + color: #8b949e; + } + + .wy-dropdown-menu, + .wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu { + background: #21262d; + border-color: #484f58; + } + + .wy-dropdown-menu > dd > a { + color: #c9d1d9; + } + + .wy-dropdown-menu > dd.call-to-action, + .wy-dropdown-menu > dd.call-to-action:hover { + background: #30363d; + } + + .rst-content code, + .rst-content code.literal, + .rst-content tt, + code, + .donation-address code { + background: #0d1117; + border-color: #30363d; + color: #ff7b72; + } + + .rst-content a code, + .rst-content a tt { + color: inherit; + } + + .rst-content div[class^="highlight"], + .rst-content pre.literal-block { + background: #0d1117; + border-color: #30363d; + } + + .rst-content div.highlight span.linenos { + border-color: #30363d; + } + + .rst-content .admonition, + .rst-content .admonition-todo, + .rst-content .attention, + .rst-content .caution, + .rst-content .danger, + .rst-content .error, + .rst-content .hint, + .rst-content .important, + .rst-content .note, + .rst-content .seealso, + .rst-content .tip, + .rst-content .warning, + .wy-alert { + background: #21262d; + } + + .rst-content .admonition-title, + .wy-alert-title { + background: #1f6feb; + color: #fff; + } + + .rst-content .danger .admonition-title, + .rst-content .danger .wy-alert-title, + .rst-content .error .admonition-title, + .rst-content .error .wy-alert-title { + background: #b62324; + } + + .rst-content .admonition-todo .admonition-title, + .rst-content .admonition-todo .wy-alert-title, + .rst-content .attention .admonition-title, + .rst-content .attention .wy-alert-title, + .rst-content .caution .admonition-title, + .rst-content .caution .wy-alert-title, + .rst-content .warning .admonition-title, + .rst-content .warning .wy-alert-title { + background: #9a6700; + } + + .rst-content .hint .admonition-title, + .rst-content .hint .wy-alert-title, + .rst-content .important .admonition-title, + .rst-content .important .wy-alert-title, + .rst-content .tip .admonition-title, + .rst-content .tip .wy-alert-title { + background: #238636; + } + + .rst-content .admonition table, + .rst-content .admonition table td, + .rst-content .admonition table th { + border-color: #484f58 !important; + } + + .rst-content table.docutils caption, + .rst-content table.field-list caption, + .wy-table caption, + .rst-content table.docutils thead, + .rst-content table.field-list thead, + .wy-table thead { + color: #f0f6fc; + } + + .rst-content table.docutils, + .rst-content table.docutils td, + .rst-content table.docutils th, + .wy-table-bordered, + .wy-table-bordered-all, + .wy-table-bordered-all td, + .wy-table-bordered-rows td, + .wy-table-horizontal td, + .wy-table-horizontal th, + html.writer-html5 .rst-content table.docutils th { + border-color: #30363d; + } + + .rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td, + .wy-table-backed, + .wy-table-odd td, + .wy-table-striped tr:nth-child(2n-1) td { + background-color: #1c2128; + } + + .rst-content .sidebar { + background: #21262d; + border-color: #30363d; + } + + .rst-content .sidebar .sidebar-title { + background: #30363d; + } + + #search-results .search li { + border-color: #30363d; + } + + .rst-content .highlighted { + background: #9a6700; + box-shadow: 0 0 0 2px #9a6700; + color: #fff; + } + + .rst-content .guilabel, + .rst-content .menuselection, + html.writer-html4 .rst-content dl:not(.docutils) > dt, + html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt { + background: #21262d; + border-color: #388bfd; + color: #79c0ff; + } + + html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt, + html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt { + background: #1c2128; + border-color: #484f58; + color: #c9d1d9; + } + + .rst-content dl dt .headerlink, + .rst-content .descclassname, + .rst-content .descname, + .rst-content .sig-name, + .rst-content .optional { + color: #f0f6fc !important; + } + + .rst-content table.docutils.footnote code, + .rst-content table.docutils.footnote tt, + html.writer-html4 .rst-content table.docutils.citation code, + html.writer-html4 .rst-content table.docutils.citation tt, + html.writer-html5 .rst-content aside.footnote code, + html.writer-html5 .rst-content aside.footnote tt, + html.writer-html5 .rst-content div.citation-list > div.citation code, + html.writer-html5 .rst-content div.citation-list > div.citation tt, + html.writer-html5 .rst-content dl.citation code, + html.writer-html5 .rst-content dl.citation tt, + html.writer-html5 .rst-content dl.footnote code, + html.writer-html5 .rst-content dl.footnote tt { + color: #8b949e; + } + + .rst-content :not(dl.option-list) > :not(dt):not(kbd):not(.kbd) > .kbd, + .rst-content :not(dl.option-list) > :not(dt):not(kbd):not(.kbd) > kbd, + kbd { + background-color: #21262d; + border-color: #484f58; + box-shadow: 0 1px 0 #0d1117; + color: #f0f6fc; + } + + span[id*="MathJax-Span"] { + color: #c9d1d9; + } + + .breadcrumb-item:before, + .wy-breadcrumbs-extra { + color: #8b949e; + } +} diff --git a/doc/display.rst b/doc/display.rst new file mode 100644 index 00000000..47f29ef3 --- /dev/null +++ b/doc/display.rst @@ -0,0 +1,95 @@ +.. _client_display: + +Display and image quality +######################### + +The EGL renderer is the supported client renderer and is selected +automatically. The older OpenGL renderer is deprecated, does not provide direct +DMA imports or native HDR, and should only be used to diagnose a compatibility +problem. + +Wayland and X11 are both built by default. Automatic selection prefers Wayland +when ``WAYLAND_DISPLAY`` is set, then X11 when ``DISPLAY`` is set. To force X11 +from a Wayland session for diagnosis, preserve ``DISPLAY`` and unset +``WAYLAND_DISPLAY`` for the client process. + +Window and guest resolution +--------------------------- + +With the IDD, ``win:setGuestRes=yes`` asks Windows to match the client viewport +when its size changes. Press :kbd:`ScrLk` + :kbd:`=` to request the current +size immediately. The IDD creates this as its dynamic ExtraMode using the +default refresh configured in the IDD helper. + +If a requested resolution does not fit in IVSHMEM, the IDD refuses it and the +helper reports the required size. See :ref:`libvirt_determining_memory`. + +Useful window options include: + +``win:autoResize`` + Resize the client window when the guest resolution changes. + +``win:keepAspect`` + Preserve the guest aspect ratio while resizing. + +``win:fullScreen`` + Start in borderless full-screen mode. + +``win:rotate`` + Rotate the image by 0, 90, 180 or 270 degrees. + +Scaling and filters +------------------- + +The overlay's **EGL filters** page controls scaling, sharpening and custom +processing. Filters run from top to bottom and can be reordered. Save useful +combinations as named presets, then select one at startup with ``egl:preset``. + +The built-in filters include: + +* a configurable downscaler; +* AMD FidelityFX Super Resolution (FSR); and +* AMD FidelityFX Contrast Adaptive Sharpening (CAS). + +The ``egl:scale`` option selects automatic, nearest-neighbor or linear +scaling when a filter does not provide the required scaling. Additional +mpv-style GLSL shaders may be loaded from ``eglFilter:glslPath``. The +`Anime4K `_ project provides compatible +GLSL filters. + +.. _client_hdr: + +HDR +--- + +The IDD exposes HDR only when the Windows runtime provides the required IddCx +interfaces and the IDD is using a hardware render adapter. This normally means +a compatible Windows 11 guest. Windows 10 and IDD software processing remain +on the SDR path. + +Native HDR output on Linux requires all of the following: + +* the EGL renderer; +* a Wayland compositor with ``color-management-v1`` support; +* an HDR-capable monitor and output configuration; and +* a host graphics driver that can present the required color format. + +With ``egl:mapHDRtoSDR=yes`` the client tone-maps HDR frames for an SDR desktop. +Use ``egl:peakLuminance`` to describe the SDR display target and +``egl:maxCLL`` to limit the assumed content light level. + +X11 presentation is SDR. The EGL renderer tone-maps HDR to SDR there by +default. Native Wayland PQ output also requires compositor support for ST 2084 +and BT.2020, while scRGB requires compositor scRGB support. + +Presentation latency +-------------------- + +The defaults favor low latency rather than conventional buffered rendering. +Do not enable ``egl:vsync`` or ``egl:doubleBuffer`` merely to chase a reported +frame-rate number; either can add presentation delay. Use the timing graphs to +confirm the result on the actual compositor and GPU. + +``win:jitRender`` delays rendering toward the expected presentation deadline. +It can reduce the age of a frame at display time, but depends on stable timing. +Leave it disabled while diagnosing stalls or an unstable refresh cadence. diff --git a/doc/faq.rst b/doc/faq.rst index 6299e254..a78878f9 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -9,271 +9,183 @@ General How does Looking Glass work? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This YouTube video featured created by the author features a detailed -explanation: +The Windows IDD creates a virtual monitor and places completed frames in an +IVSHMEM region shared with Linux. The client imports the newest frame, renders +it and returns input through the available transport. The image is not encoded +as a video stream, which avoids codec latency and quality loss. -https://www.youtube.com/watch?v=U44lihtNVVM +See :doc:`overview` for the current components. A detailed video explanation +is also available at https://www.youtube.com/watch?v=U44lihtNVVM. .. _can_i_feed_the_vm_directly_into_obs: Can I feed the VM directly into OBS? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Looking Glass now features a functional :doc:`OBS plugin `, which acts as -another Looking Glass client, but instead feeds the captured frames into OBS. +Yes. The :doc:`OBS plugin ` is an independent frame consumer and does not +capture the client window. .. _why_is_my_ups_so_low: -Why is my UPS (Updates Per Second) so low? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Why is UPS lower than the guest refresh rate? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are several reasons why this can happen, the most common are your -capture resolution, or refresh rate. The windows capture methods currently -struggle to capture high resolutions under certain circumstances. +UPS counts frames delivered to that consumer, not every frame Windows may +render. The IDD publishes to the deadline requested by the fastest active +client and can skip guest frames that have already been superseded. This saves +memory bandwidth without deliberately adding a frame of latency. -Some titles do some strange things at early initialization that cause -capture performance issues. One such title is the Unigine Valley -benchmark where the capture rate is limited to 1/2 the actual rate. For -an unknown reason to both myself and the Unigine developers a simple -task switch (alt+tab) in and out resolves the issue. This is not a -Looking Glass bug. +If UPS is below the active consumer's requested rate, use +:ref:`client_performance` to locate the slow stage. High resolution, software +processing, memory bandwidth, host scheduling and compositor presentation can +all impose a lower limit. .. _is_my_gpu_supported: -Is my GPU supported? -~~~~~~~~~~~~~~~~~~~~ +Is a passed-through GPU required? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Your guest GPU almost certainly supports DXGI. Use DxDiag to confirm -that you have support for WDDM 1.2 or greater. +No. The IDD can create an SDR display using software processing when it cannot +use a Windows render adapter. A hardware adapter is strongly recommended for +lower latency, higher refresh rates, HDR and cadence scheduling. -The server-side (guest) probing error "Capture is not possible, -unsupported device or driver" indicates NVidia duplication has failed, -not that DXGI has failed. You can fix the error by specifying -``-c DXGI`` +The Linux client still needs an EGL-capable host graphics driver. Direct +DMA-BUF import depends on the host GPU and driver; the client falls back to a +copy when it is unavailable. .. _why_do_i_need_spice_if_i_dont_want_a_spice_display_device: -Why do I need Spice if I don't want a Spice display device? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Do I need SPICE? +~~~~~~~~~~~~~~~~ -You don't need Display Spice enabled. Looking Glass has a Spice client -built in to provide some conveniences, but you can disable it with the -"-s" argument. +SPICE is not required for the primary IDD video or direct input paths. It is +still useful for clipboard, audio, input fallback and automatic video fallback. +These services are selected independently. -.. note:: - - Without Spice, Looking Glass cannot send mouse/keyboard input to the guest - and clipboard synchronization is disabled. +Set ``spice:enable=no`` or use ``-s`` to disable SPICE completely. Disable an +individual service with ``spice:input``, ``spice:clipboard`` or +``spice:audio`` instead when the other services are still wanted. .. _where_is_the_host_application_for_linux: -Where is the host application for Linux? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Which application runs on Linux? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The "Windows host application" is actually the display server, which -runs in the guest VM. The only thing that needs to run in your Linux -host OS is the ``looking-glass-client`` application. +The Looking Glass Client runs on the Linux host operating system. The IDD runs +inside the Windows guest. The older product named the **Host Application** is +a legacy Windows producer; “Host” in that name does not mean the Linux host +OS. -You can :ref:`build ` a version of the host for Linux as -well. +Input and window system +----------------------- .. _gnome_wayland_decorations: -Why is there no title bar on GNOME? / Why can't I resize the window on GNOME? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Why is there no title bar on GNOME Wayland? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This happens because GNOME on Wayland doesn't support the `standard protocol`_ -for server-side decorations, and Looking Glass doesn't implement its own -decorations. +GNOME does not implement the standard Wayland server-side decoration +protocol. Build Looking Glass with libdecor support: -The easiest solution is to build Looking Glass with `libdecor`_ support. -Install the ``libdecor-0-dev`` package. If your distribution lacks this package -or any equivalents, you must build it from `source code `_. +.. code:: bash -You can then build the the client with libdecor support by passing -``-DENABLE_LIBDECOR=ON`` to ``cmake``. + cmake -DENABLE_LIBDECOR=ON ../ -An alternative solution is to hold down the Super key (Windows key on most -keyboards), then right click Looking Glass. This should bring up a menu, -which will allow you to move the window and resize it. - -.. warning:: - Libdecor support is provided for the convenience of our Wayland users on - GNOME, however it is not a priority feature and may break, please seek - alternatives if you require stable operation. - -.. _standard protocol: https://wayland.app/protocols/xdg-decoration-unstable-v1 -.. _libdecor: https://gitlab.freedesktop.org/libdecor/libdecor - -Mouse ------ +Install ``libdecor-0-dev`` first on Debian-based systems. Alternatively, hold +the Super key and right-click the window to use the compositor's move and +resize menu. .. _the_mouse_is_jumpy_slow_laggy_when_using_spice: -The mouse is jumpy, slow, laggy when using SPICE +Why is SPICE fallback mouse movement different? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Please be sure to install the SPICE guest tools from -https://www.spice-space.org/download.html#windows-binaries. +The IDD's direct input path uses absolute positioning for normal desktop use +and relative movement in capture mode. SPICE input is relative-only, so guest +mouse acceleration can change its feel or cause temporary position error. -.. _mouse_desync_when_entering: - -The mouse position is wrong when entering the window -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is due to windows mouse acceleration, it can be disabled by -following one of these methods: - -- Disabling pointer precision (Control Panel > Mouse > Pointer Options - > Uncheck Enhance pointer precision) -- By changing the acceleration behavior with the following registry - magic: - http://donewmouseaccel.blogspot.com.au/2010/03/markc-windows-7-mouse-acceleration-fix.html - (Contrary to the title this works just fine on Windows 10) +Use the direct IDD input path when available. For a game, use capture mode and +consider ``input:rawMouse=yes``. .. _the_cursor_position_doesnt_update_until_i_click: -The cursor position doesn't update until I click -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Should I add a virtual tablet? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Make sure you have removed the Virtual Tablet Device from the Virtual -Machine. Due to the design of Windows, absolute pointing devices break -applications/games that require cursor capture, and as such Looking Glass -does not support them. +No. Looking Glass does not require an additional virtio tablet, mouse or +keyboard. Direct IDD input provides its own absolute and relative devices, and +SPICE fallback uses the VM's default PS/2 input devices. Audio ----- -As of B6 Looking Glass supports audio input and output via SPICE. +Does Looking Glass support microphone input and surround sound? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _faq_win: +Yes. The recommended emulated USB Audio 2.0 device provides stereo, +quadraphonic, 5.1 and 7.1 playback plus stereo recording at rates up to +192 kHz. Classic SPICE audio also provides playback and recording. Client +microphone recording currently requires the PipeWire backend. See +:doc:`audio`. -Windows -------- +Legacy Host Application +----------------------- -.. _nvfbc_nvidia_capture_api_doesnt_work: - -NvFBC (NVIDIA Capture API) doesn't work -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -NvFBC is only supported on professional-grade GPUs, and will not function on -consumer-grade cards like those from the GeForce series. - -If you have a supported card, you can enable NVFBC by adding the following -to the host ini file, found at -``%ProgramFiles%\Looking Glass (host)\looking-glass-host.ini`` -(create one if it doesn't exist): - -.. code:: INI - - [app] - capture=nvfbc - -.. _the_screen_stops_updating_when_left_idle_for_a_time: - -The screen stops updating when left idle for a time -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Windows is likely turning off the display to save power, you can prevent -this by adjusting the ``Power Options`` in the control panel. +The sections below apply only to the legacy Windows Host Application. New +installations should use the IDD. See :ref:`legacy_host_policy`. .. _faq_host: -Host ----- +Where is the legacy Host log? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Where is the log? -~~~~~~~~~~~~~~~~~ +The application log is: -The log file for the host application is located at:: +``%ProgramData%\Looking Glass (host)\looking-glass-host.txt`` - %ProgramData%\Looking Glass (host)\looking-glass-host.txt +The service log is: -You can also open the log file by right clicking on the Looking Glass -system tray icon, then clicking *Open Log File*. This opens the log -file in Notepad. - -The log file for the looking glass service is located at:: - - %ProgramData%\Looking Glass (host)\looking-glass-host-service.txt - -This is useful for troubleshooting errors related to the host -application not starting. - -High priority capture using DXGI and Secure Desktop (UAC) capture support -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default Windows gives priority to the foreground application for any -GPU work which causes issues with capture if the foreground application -is consuming 100% of the available GPU resources. The looking glass host -application is able to increase the kernel GPU thread to realtime -priority which fixes this, but in order to do so it must run as the -``SYSTEM`` user account. To do this, Looking Glass needs to run as a -service. This can be accomplished by either using the NSIS installer -which will do this for you, or you can use the following command to -Install the service manually: - -:: - - looking-glass-host.exe InstallService - -To remove the service use the following command: - -:: - - looking-glass-host.exe UninstallService - -This will also enable the host application to capture the secure desktop -which includes things like the lock screen and UAC prompts. +``%ProgramData%\Looking Glass (host)\looking-glass-host-service.txt`` .. _faq_host_admin_privs: -Why does the host require Administrator privileges? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Why does the legacy Host require administrator privileges? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is intentional for several reasons. +The legacy capture APIs use privileged functions for GPU scheduling, NvFBC +setup and secure-desktop capture. The installer runs it as a Windows service +under the SYSTEM account. This is not how the current IDD is configured. -1. NvFBC requires a system wide hook to correctly obtain the cursor - position as NVIDIA decided to not provide this as part of the cursor - updates. -2. NvFBC requires administrator level access to enable the interface in - the first place. -3. General capture performance is boosted by taking advantage of high priority - scheduling with SYSTEM level privileges. +.. _nvfbc_nvidia_capture_api_doesnt_work: -NvFBC (NVIDIA Frame Buffer Capture) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Why does NvFBC not work? +~~~~~~~~~~~~~~~~~~~~~~~~ -Why can't I compile NvFBC support into the host? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +NvFBC is a legacy Host capture method and requires supported NVIDIA hardware +and SDK licensing. It is not part of the IDD path. -You must download and install the NVidia Capture SDK. Please note that -by doing so you will be agreeing to NVIDIA's SDK License agreement. +.. _the_screen_stops_updating_when_left_idle_for_a_time: + +Why does a legacy captured display stop when idle? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Windows may turn off the physical or dummy display captured by the legacy +Host. Disable display sleep for that monitor. The IDD virtual-monitor path does +not require a physical display. .. _a_note_about_ivshmem_and_scream_audio: -Why doesn't Looking Glass work with Scream over IVSHMEM? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Can Scream and Looking Glass share IVSHMEM? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. warning:: - Using IVSHMEM with Scream may interfere with Looking Glass, as they may try - to use the same device. +Do not use Scream with Looking Glass. Use the built-in classic SPICE or USB +audio path instead. In particular, Scream's IVSHMEM transport can select or +interfere with the shared device used for Looking Glass frames. -Please do not use the IVSHMEM plugin for Scream. -To fix this issue, use the default network transfer method. -The IVSHMEM method induces additional latency that is built into its -implementation. When using VirtIO for a network device the VM is already using -a highly optimized memory copy anyway so there is no need to make another one. +Technical details +----------------- -If you insist on using IVSHMEM for Scream—despite its inferiority to the -default network implementation—the Windows Host Application can be told -what device to use. Edit the file -``%ProgramFiles%\Looking Glass (host)\looking-glass-host.ini``, -(create one if it doesn't exist) -then, you can add the ``os:shmDevice`` option like so: - -.. code:: INI - - [os] - shmDevice=1 +.. toctree:: + :maxdepth: 1 + tech_faq diff --git a/doc/host_usage.rst b/doc/host_usage.rst new file mode 100644 index 00000000..bb83fe89 --- /dev/null +++ b/doc/host_usage.rst @@ -0,0 +1,89 @@ +.. _host_usage: + +Legacy Host configuration +######################### + +.. warning:: + + This page applies only to the legacy Windows Host Application. New + installations should use the IDD. B7 is the last recommended complete stack + when non-capture mouse input through the Host Application is required. + +The legacy Host normally selects a compatible frame path automatically. Its +persistent configuration file is: + +``C:\Program Files\Looking Glass (host)\looking-glass-host.ini`` + +Use options from the same release as the Host binary. Do not copy a current +Host configuration into B7 or combine a B7 Host with a current client. + +.. _host_capture: + +Capture interface +----------------- + +The legacy Host captures an existing Windows display through Desktop +Duplication or NvFBC. It does not use Windows Graphics Capture. Select an +interface only when automatic selection fails: + +.. code-block:: ini + + [app] + capture=d12 + +.. _host_capture_d12: + +D12 + The preferred Direct3D 12 Desktop Duplication path on supported systems. It + can copy directly toward shared memory and supports damage tracking. + +.. _host_capture_dxgi: + +DXGI + The Direct3D 11 Desktop Duplication compatibility path. It may require an + additional staging copy and can show cursor-related capture jitter. + +.. _host_capture_nvfbc: + +NvFBC + An NVIDIA SDK path available only with supported hardware and licensing. + It is not required by the IDD or the normal legacy D12 path. + +The exact capture-interface options can change between releases. Consult the +binary's help and the configuration comments supplied with that release. + +.. _host_select_ivshmem: + +Select an IVSHMEM device +------------------------ + +The legacy Host selects the first IVSHMEM device by default. When the VM has +more than one, ``os:shmDevice`` selects by zero-based device order: + +.. code-block:: ini + + [os] + shmDevice=1 + +Check the Host log after changing it; the selected device is marked with an +asterisk. This option is for the legacy Host and is not an IDD helper setting. + +.. _host_downsampling: + +Downsampling +------------ + +The legacy Host can reduce a captured resolution before transport. Rules use +``source:target`` syntax and may match resolutions greater than a threshold: + +.. code-block:: ini + + ; Downsample exactly 3840x2160 to 1920x1080 + downsample=3840x2160:1920x1080 + + ; Downsample anything larger than 1920x1080 + downsample=>1920x1080:1920x1080 + +This saves transport bandwidth but does not reduce the guest application's +rendering work. IDD users should request the required virtual monitor +resolution instead. diff --git a/doc/idd_configuration.rst b/doc/idd_configuration.rst new file mode 100644 index 00000000..3208d7f7 --- /dev/null +++ b/doc/idd_configuration.rst @@ -0,0 +1,87 @@ +.. _idd_configuration: + +Configure the IDD +################# + +Right-click the **Looking Glass (IDD)** icon in the Windows notification area +and select **Open configuration**. The icon and its tooltip also show whether +the driver is using GPU acceleration or software processing. + +Display modes +------------- + +The mode list controls the resolutions and refresh rates that Windows may use +for the Looking Glass monitor. + +* Select a mode to edit its width, height or refresh rate, then select + **Update**. +* Select ****, enter a mode in the fields below the list and select + **Update** to add it. +* Select **Delete** to remove the selected mode. +* Select **Load default** to replace the working list with the standard modes. +* Enable **prefer** on the mode that Windows should prefer. Only one mode can + be preferred. + +Refresh rates may contain up to three decimal places. For example, enter +``119.970`` rather than rounding it to 120 Hz. Accepted values range from +23.900 Hz to 1000.000 Hz. Width may range from 640 to 16384 pixels and height +from 480 to 16384 pixels. + +Edits to the mode list are not applied immediately. Select **Save & reload +driver** when the list is ready. This saves the list, removes and recreates the +virtual monitor, and can make the display blink briefly. **Revert** discards +unsaved mode and default-refresh changes. + +Default refresh +--------------- + +**Default refresh** is used when the client asks the IDD to create a dynamic +resolution. It also supplies the refresh rate when **Load default** rebuilds +the standard mode list. + +Changing this value does not rewrite refresh rates already saved in the normal +mode list. On reload, an existing dynamic mode keeps its resolution and adopts +the new default refresh rate. + +The client option ``win:setGuestRes`` enables automatic dynamic resolution +requests when the client window changes size. The default is enabled when the +producer supports it. Press the client's escape key together with ``=`` to +request the current window resolution manually. + +Preferences +----------- + +Make LG the only monitor + Makes the Looking Glass display the only active Windows monitor. This is + enabled by default and the helper restores the topology when required. + Disable it if you intentionally use other guest displays at the same time. + Disabling it stops future enforcement but does not automatically restore + displays that Windows has already disabled. + +Disable no GPU warning + Suppresses the notification shown when the IDD has fallen back to software + processing. It does not enable GPU acceleration or change the active + adapter. + +Unlike mode-list edits, preference checkboxes are saved when clicked. + +Software processing +------------------- + +If no suitable Windows render adapter is available, the IDD can use software +processing. This provides a display but is slower, cannot provide predictable +high-rate cadence and is limited to SDR. Check the IDD log to see which render +adapter was selected and whether software processing is active. + +Modes that do not fit in shared memory +-------------------------------------- + +At startup the IDD removes modes that cannot fit in the configured IVSHMEM +region. If every suitable mode is filtered, the monitor cannot start. A +dynamic resolution request that is too large is refused and the helper reports +the minimum power-of-two IVSHMEM size needed. + +Increase the IVSHMEM size in the VM configuration and restart the VM. The IDD +reads the new capacity when it starts; another helper reload is not normally +required. Allocating more shared memory than required does not improve +performance; it only reserves additional host RAM. diff --git a/doc/idd_diagnostics.rst b/doc/idd_diagnostics.rst new file mode 100644 index 00000000..791c5b4e --- /dev/null +++ b/doc/idd_diagnostics.rst @@ -0,0 +1,71 @@ +.. _idd_diagnostics: + +IDD status and logs +################### + +The IDD helper in the Windows notification area is the first place to check +when the virtual display is missing or slow. Its icon and tooltip report +whether the driver is using GPU acceleration or software processing. + +Right-click the helper and open the log directory. The files are stored in: + +``C:\ProgramData\Looking Glass (IDD)`` + +Collect these files when reporting an IDD fault: + +* ``looking-glass-idd.txt`` -- display creation, GPU selection, modes, + transport and frame scheduling; +* ``looking-glass-input.txt`` -- direct keyboard and mouse device activity; +* ``looking-glass-idd-service.txt`` -- service and driver control requests; +* ``looking-glass-idd-helper.txt`` -- configuration, topology and user + notifications. + +Each log rotates through suffixes ``.1`` to ``.4``. Include the current file +and rotated files when the problem happened before the most recent restart. + +Useful IDD lines +---------------- + +Render adapter + Shows the Windows GPU selected by the IDD. A software-processing warning + explains why HDR, cadence and high frame rates are unavailable. + +IVSHMEM size + Confirms which device was opened and its capacity. Compare this with the VM + configuration and :ref:`libvirt_determining_memory`. + +Filtered mode + A configured mode was omitted because its frame buffers do not fit. Increase + IVSHMEM or remove the oversized mode. + +IddCx capabilities + Shows whether the runtime HDR and wide-color-gamut interfaces are + available. Their absence on Windows 10 is expected and does not prevent SDR + use. + +Frame schedule owner + Reports the fastest active client's requested rate, guest acquisition rate + and how many frames were published or skipped. Skipping excess guest frames + is expected; it saves memory bandwidth while preserving the newest frame + needed by the client. + +Input owner + Identifies the client currently allowed to send direct input. Only one + client can own it at a time. + +Client information +------------------ + +Run the client from a terminal and retain its complete output. Include: + +* the client, IDD and OBS versions; +* Linux distribution and kernel; +* X11 or Wayland and the compositor name; +* host and guest GPU models and drivers; +* whether ``lgmp:allowDMA`` is enabled; +* the guest resolution and refresh rate; and +* exact steps that reproduce the fault. + +Do not copy only the final error line. Startup output records the selected +transport, renderer, display server, audio backend and import method, which are +often needed to explain it. diff --git a/doc/index.rst b/doc/index.rst index 4849f7a8..836a61e1 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,23 +1,25 @@ Looking Glass |release| documentation ===================================== -Looking Glass is an open-source application that allows the use of a KVM -(Kernel-based Virtual Machine) configured for VGA PCI Pass-through -without an attached physical monitor, keyboard or mouse. This is the -final step required to move away from dual booting with other operating -systems for legacy programs that require high-performance graphics. +Looking Glass is an open-source, low-latency way to use a Windows virtual +machine from Linux. The current setup uses a virtual display in the Windows +guest, shared memory for frames, and a native Linux client for display and +input. .. toctree:: :maxdepth: 2 + overview requirements + quickstart + build install + usage troubleshooting obs faq - tech_faq .. toctree:: :hidden: @@ -39,6 +41,20 @@ Donate: * `Ko-Fi `_ * `Patreon `_ * `PayPal `_ -* BTC - 14ZFcYjsKPiVreHqcaekvHGL846u3ZuT13 -* ETH - 0x6f8aEe454384122bF9ed28f025FBCe2Bce98db85 -* XMR - 47xM4zG7b2tEj4mnSywHve4ydZzn3wzhf22snDRB7aSEcXrgUBpoT2Z4phTnyFMi1sMyQtHbdufMYRQ2PzMn3PGUJAE1dpc + +Expand a cryptocurrency address to copy it: + +.. raw:: html + +
+ Bitcoin (BTC) + 14ZFcYjsKPiVreHqcaekvHGL846u3ZuT13 +
+
+ Ethereum (ETH) + 0x6f8aEe454384122bF9ed28f025FBCe2Bce98db85 +
+
+ Monero (XMR) + 47xM4zG7b2tEj4mnSywHve4ydZzn3wzhf22snDRB7aSEcXrgUBpoT2Z4phTnyFMi1sMyQtHbdufMYRQ2PzMn3PGUJAE1dpc +
diff --git a/doc/input.rst b/doc/input.rst new file mode 100644 index 00000000..2b2c2e6c --- /dev/null +++ b/doc/input.rst @@ -0,0 +1,101 @@ +.. _client_input: + +Keyboard and mouse input +######################## + +The current IDD provides keyboard and mouse input directly over LGMP. It uses +absolute positioning for normal desktop use and relative movement in capture +mode. SPICE remains available as a fallback when direct input is unavailable. + +The client changes input provider automatically. If the displayed video has +fallen back to SPICE, the client also uses SPICE input so that the picture and +pointer always refer to the same guest. + +Only one LGMP client controls direct input at a time. Starting another client +does not give both clients simultaneous control. Disconnecting or restarting +the IDD releases held keys and buttons before ownership changes. + +Normal input +------------ + +Move the pointer into the guest view to use absolute desktop input. This keeps +the guest pointer aligned without requiring capture. + +Direct IDD input supports the keyboard, media keys and up to 32 mouse buttons. +SPICE fallback uses relative mouse input and supports fewer extra buttons. + +Capture mode +------------ + +Press the escape key, :kbd:`ScrLk` by default, to capture the mouse. Capture +mode confines the pointer and sends relative motion, which is appropriate for +games and applications that lock the cursor. Press the escape key again to +leave capture mode. + +Common capture options are: + +``input:captureOnFocus`` + Enter capture mode whenever the client receives focus. + +``input:captureOnStart`` + Start captured. + +``input:captureOnly`` + Disable guest input outside capture mode. + +``input:rawMouse`` + Use raw relative mouse input in capture mode. This is usually best for + games. + +``input:mouseSens`` + Adjust relative sensitivity from -9 to 9. The default is 0. + +``input:hideCursor`` + Hide the host cursor while Looking Glass renders the guest cursor. + +Automatic keyboard capture +-------------------------- + +Set ``input:autoCapture=yes`` to grab the keyboard when the pointer enters the +guest view. Looking Glass predicts when the next mouse movement would leave +the guest area and releases the keyboard before that movement. This makes it +possible to move naturally between Looking Glass and the Linux desktop without +using the escape key for the keyboard. + +Automatic keyboard capture is disabled by ``input:captureOnly=yes``. It also +keeps the keyboard grabbed while a mouse button is held so that dragging does +not unexpectedly leave the guest. + +This is separate from full mouse capture: the pointer remains in normal +absolute mode. Use regular capture mode when an application requires relative +mouse input. + +``input:grabKeyboardOnFocus`` instead keeps the keyboard grabbed while the +guest view is active. ``input:grabKeyboard`` controls whether full capture +mode grabs the keyboard. + +SPICE fallback +-------------- + +Keep ``spice:input=yes`` when SPICE input fallback is wanted. It uses the VM's +default PS/2 keyboard and mouse, so no additional virtio input devices or +tablet are required. + +To disable all SPICE input while keeping SPICE audio or clipboard services: + +.. code-block:: ini + + [spice] + input=no + +If direct input is also unavailable, the client will display video without +being able to control the guest. + +Evdev capture +------------- + +Advanced users may list Linux evdev devices in ``input:evdev``. They become +active whenever Looking Glass grabs the keyboard, including capture mode and +automatic keyboard capture. The client user must be allowed to read those +devices. Keep ``input:evdevExclusive=yes`` unless duplicate input from the +window system is specifically required. diff --git a/doc/install.rst b/doc/install.rst index 750f3d1f..a6505cf6 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -3,8 +3,16 @@ Installation ############ +The Linux client must currently be built from source before it can be +installed. Follow the pages below in order for a new setup: + +Configure the VM and shared memory, install the IDD in Windows, then install +the Linux client. The legacy Host page is an alternative for old workflows; +do not install both Windows producers. + .. toctree:: - + install_libvirt - install_host + install_idd install_client + install_host diff --git a/doc/install_client.rst b/doc/install_client.rst index 63284f22..51f5c062 100644 --- a/doc/install_client.rst +++ b/doc/install_client.rst @@ -8,15 +8,21 @@ Client Application Installation For Linux --------- -The Looking Glass client receives frames from the :ref:`host ` to -display on your screen. It also handles input, and can optionally share the -system clipboard with your guest OS through SPICE. +The Looking Glass Client receives frames from the Windows producer and displays +them on Linux. It also handles input, audio, overlays and optional SPICE +services. -First you must build the client from source, see :ref:`building`. Once you have -built the client, you can install it. Run the following as root:: +There are currently no Linux distribution packages for the client. First +:ref:`build it from source `, then run the following from +the client build directory as root:: make install -To install for the local user only, run:: +To install for the current user only, configure the build with a user-local +prefix before installing:: - cmake -DCMAKE_INSTALL_PREFIX=~/.local .. && make install + cmake -DCMAKE_INSTALL_PREFIX="$HOME/.local" .. + make install + +Ensure ``$HOME/.local/bin`` is in your ``PATH`` when using the user-local +installation. diff --git a/doc/install_host.rst b/doc/install_host.rst index ca0f1d53..4521b0f5 100644 --- a/doc/install_host.rst +++ b/doc/install_host.rst @@ -1,17 +1,26 @@ .. _installing_host: +.. _host_install: -Host Application Installation -############################# +Legacy Host Application installation +#################################### -The Looking Glass Host application captures frames from the guest OS using a +.. warning:: + + The Host Application is a legacy frame producer. New installations should + use the :doc:`Looking Glass IDD `. + + B7 is the last recommended release when non-capture mouse input through the + Host Application is required. Use the matching B7 client and documentation + for that workflow. Do not combine a B7 Host with current components. + +The legacy Looking Glass Host Application captures frames from the guest using a capture API, and sends them to the :ref:`client `—be it on the host OS (hypervisor) or another Virtual Machine—through a low-latency transfer protocol over shared memory. You can get the host program in two ways: -- Download a pre-built binary from https://looking-glass.io/downloads - (**Recommended**) +- Download a matching legacy binary from https://looking-glass.io/downloads - Download the source code as described in :ref:`building`, then :ref:`build the host `. @@ -79,3 +88,11 @@ Command line users can run ``looking-glass-host-setup.exe /S`` to execute a silent install with default options selected. Further configuration from the command line can be done with flags. You can list all available flags by running ``looking-glass-host-setup.exe /?``. + +Legacy configuration +~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + host_usage diff --git a/doc/install_idd.rst b/doc/install_idd.rst new file mode 100644 index 00000000..4775a948 --- /dev/null +++ b/doc/install_idd.rst @@ -0,0 +1,85 @@ +.. _installing_idd: + +Looking Glass IDD +################# + +.. _install_idd: + +The Looking Glass IDD is the recommended Windows frame producer. Download the +``looking-glass-idd-setup.exe`` installer that matches the client release, run +it as an administrator inside the Windows guest and follow the installer. + +The installer includes the display driver, direct input driver and IDD helper. +It can also install the IVSHMEM driver. If the legacy Host service is present, +allow the installer to disable it so that only one Looking Glass producer is +active. + +The display may briefly disappear while Windows installs or reloads the +driver. Restart Windows if the installer requests it. + +Install +------- + +1. Download the IDD installer from the same release as the client source. +2. Run ``looking-glass-idd-setup.exe`` as an administrator in Windows. +3. Select **IVSHMEM Driver** if a suitable IVSHMEM driver is not already + installed in the guest. +4. Leave **Indirect Display Driver (IDD)** selected. +5. If offered, leave **Disable old host app** selected. Running two producers + against the same shared-memory device is not supported. +6. Complete the installation and restart Windows if requested. + +After installation, Windows should show a display named Looking Glass and the +IDD helper should appear in the notification area. The helper icon reports +whether the IDD is using GPU acceleration or software processing. + +The IDD installer also installs its direct input driver. There is no separate +input package to install. + +Upgrade +------- + +Close active clients and OBS sources, then run the new matching IDD installer +over the existing installation. Upgrade the Linux client and OBS plugin to the +same release before using them again. + +Windows may briefly remove and recreate the virtual display. Restart Windows +when the installer reports that a restart is required. + +Uninstall +--------- + +Remove **Looking Glass (IDD)** from Windows **Installed apps** or **Programs +and Features**. This removes both the display and input drivers and deletes +custom IDD modes and preferences. The optional IVSHMEM files are removed from +the Looking Glass installation directory, but an IVSHMEM driver package that +was already installed in Windows is not uninstalled. + +If you are returning to the legacy Host Application, re-enable or reinstall +its service only after the IDD has been removed. + +Silent installation +------------------- + +The installer accepts these options for managed installations: + +``/S`` + Install silently. The uppercase spelling is required. + +``/ivshmem`` + Install the bundled IVSHMEM driver when it is present in the installer. + +``/D=path`` + Change the installation directory. This must be the final option and must + not be quoted. + +Configuration and diagnostics +----------------------------- + +.. toctree:: + :maxdepth: 1 + + idd_configuration + +For faults, the helper can open the IDD log directory directly. See +:ref:`idd_diagnostics` for the files to collect. diff --git a/doc/install_libvirt.rst b/doc/install_libvirt.rst index f31446ff..05b543ba 100644 --- a/doc/install_libvirt.rst +++ b/doc/install_libvirt.rst @@ -3,85 +3,64 @@ libvirt/QEMU Installation ######################### -This article assumes you already have a fully functional `libvirt` domain with -PCI passthrough working. If you use `virt-manager`, this guide also applies to -you, since virt-manager uses `libvirt` as its back end. +This article assumes you already have a working `libvirt` Windows virtual +machine. If you use `virt-manager`, this guide also applies because +`virt-manager` uses `libvirt` as its back end. A passed-through or virtual GPU +is strongly recommended, but the IDD can start in software mode without one. .. _libvirt_determining_memory: Determining memory ^^^^^^^^^^^^^^^^^^ -You will first need to calculate the memory size to be suitable for your desired -maximum resolution using the following formula: +Calculate the base IVSHMEM requirement as: .. math:: - \text{WIDTH} \times \text{HEIGHT} \times \text{BPP} \times 2 = \text{frame size in bytes} + \text{BASE SIZE} = + \left(\left\lceil\frac{\text{WIDTH} \times 4}{256}\right\rceil + \times 256\right) \times \text{HEIGHT} \times 3 - \text{frame size in bytes} \div 1024 \div 1024 = \text{ frame size in MiB} +Additional shared memory is required for protocol metadata and alignment. The +values below include that requirement and are rounded up to a power of two. - \text{frame size in MiB} + 10 = \text{ required size in MiB} - - 2^{\lceil \log_2(\text {required size in MiB}) \rceil} = \text{ total MiB} - -Where `BPP` is 4 for 32-bit RGB (SDR) or 8 for 64-bit -(HDR :ref:`* `). - -.. hint:: - The final step in this calculation is simply rounding the value up to the - nearest power of two. - -For example, for a resolution of 1920x1080 (1080p) SDR: - -.. math:: - - 1920 \times 1080 \times 4 \times 2 = 16,588,800 \text{ bytes} - - 16,588,800 \div 1024 \div 1024 = 15.82 \text{ MiB} - - 15.82 \text{ MiB} + 10 \text{ MiB} = 25.82 \text{ MiB} - - 2^{\lceil \log_2(25.82) \rceil} = 32 \text { MiB} - - -Failure to provide enough memory will cause Looking Glass to truncate the -bottom of the screen and will trigger a message popup to inform you of the size -you need to increase the value to. +If a configured mode does not fit, the IDD omits it from the Windows mode list. +If a client-requested dynamic resolution does not fit, the helper refuses it +and reports the minimum power-of-two size to configure. The current IDD does +not publish a truncated frame. .. note:: - Increasing this value beyond what you need does not yield any performance - improvements, it simply will block access to that RAM making it unusable by - your system. + Increasing this value beyond what you need does not improve performance. It + only reserves more host RAM for the VM. -.. list-table:: Common Values - :widths: 50 25 25 - :header-rows: 1 +.. list-table:: Common IDD values + :widths: 60 40 + :header-rows: 1 - * - Resolution - - Standard Dynamic Range - - High Dynamic Range (HDR) :ref:`* ` - * - 1920x1080 (1080p) - - 32 - - 64 - * - 1920x1200 (1200p) - - 32 - - 64 - * - 2560x1440 (1440p) - - 64 - - 128 - * - 3840x2160 (2160p/4K) - - 128 - - 256 + * - Maximum resolution + - Total IVSHMEM size (MiB) + * - 1920x1080 (1080p) + - 64 + * - 1920x1200 + - 64 + * - 2560x1440 (1440p) + - 128 + * - 3440x1440 + - 128 + * - 3840x2160 (4K) + - 256 + * - 5120x1440 + - 128 + * - 5120x2880 (5K) + - 256 + * - 7680x4320 (8K) + - 512 .. _libvirt_determining_memory_hdr: -.. warning:: - While Looking Glass can capture and display HDR, at the time of writing - neither Xorg or Wayland can make use of it and it will be converted by the - GPU drivers/hardware to SDR. Additionally using HDR doubles the amount of - memory, bandwidth, and CPU load and as such should generally not be used - unless you have a special reason to do so. +HDR uses the same 32-bit IDD transport allocation as SDR, so it does not double +the IVSHMEM requirement. Native Linux HDR presentation has separate compositor +and display requirements; see :ref:`client_hdr`. .. _libvirt_ivshmem: @@ -95,7 +74,7 @@ Looking Glass to use your GPUs DMA engine to transfer the frame data. .. toctree:: :maxdepth: 1 - + ivshmem_kvmfr ivshmem_shm @@ -109,36 +88,24 @@ Looking Glass to use your GPUs DMA engine to transfer the frame data. Keyboard/mouse/display/audio ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Looking Glass makes use of the SPICE protocol to provide keyboard and mouse -input, audio input and output, and display fallback. +The IDD provides the primary video, keyboard and mouse paths directly over +LGMP. SPICE is optional, but is recommended for display fallback, clipboard +and audio services. .. note:: - The default configuration that libvirt uses is not optimal and must be - adjusted. Failure to perform these changes will cause input issues along - with failure to support 5 button mice. + The current client owns its SPICE connection and service settings. The + canonical options are ``spice:enable``, ``spice:input``, + ``spice:clipboard``, ``spice:audio`` and ``spice:usbAudio``. -If you would like to use SPICE to give you keyboard and mouse input -along with clipboard sync support, make sure you have a -```` device, then: +Keep a ```` device if you want these services. For a +usable display fallback, set the VM's ``