From a5e6065d3908cce879195b5224cf8b689eea609b Mon Sep 17 00:00:00 2001 From: Geoffrey McRae Date: Sun, 18 Sep 2022 20:27:03 +1000 Subject: [PATCH] [doc] added host usage documentation for DXGI and NvFBC --- doc/usage.rst | 183 +++++++++++++++++++++++++++++++++++++++++++++++++- doc/words.txt | 4 ++ 2 files changed, 185 insertions(+), 2 deletions(-) diff --git a/doc/usage.rst b/doc/usage.rst index 39637877..cba9f0ec 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -1,7 +1,7 @@ .. _client_usage: -Usage ------ +Client Usage +------------ **looking-glass-client** [\-\-help] [\-f] [\-F] [\-s] [\-S] [options...] @@ -398,3 +398,182 @@ The following is a complete list of options accepted by this application +-----------------------+-------+-------+-------------------------+ | wayland:fractionScale | | yes | Enable fractional scale | +-----------------------+-------+-------+-------------------------+ + +.. _host_usage: + +Host Usage +---------- + +By default the host application will simply work however there are some +configurable options available. While the host application will accept command +line arguments just as the client will it is more convenient to create the +`looking-glass-host.ini` file with the desired configuration options. + +This file must be placed in the same directory that the Looking Glass host +application was installed for it to be found and used by the application + +.. _host_capture: + +Capture Interface +~~~~~~~~~~~~~~~~~ + +.. note:: + Currently we only provide support for the Windows host application, Linux + options are not currently documented. + +Currently under windows there are two capture interfaces available for use, +by default the most compatible and commonly supported interface is selected +however this can be changed via the ini file with the following configuration: + +.. code:: ini + + [app] + capture= + +Where `` is one of `dxgi` or `nvfbc` + +.. _host_capture_dxgi: + +Microsoft DXGI Desktop Duplication +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface (DXGI) is the default and most compatible capture interface for +windows, unfortunately though it does suffer from several drawbacks over other +options. DXGI capture can operate in two modes, DirectX 11 (default) or the +experimental and unofficial DirectX 12 mode. + +Due to the design of Microsoft's DXGI API and the decision made to roll +hardware cursor updates into the capture stream this interface can suffer from +microstutters when the mouse is being moved/updated. This issue only affects +guest applications that make use of the hardware cursor instead of compositing +the cursor directly, as such titles that do not use a mouse (most FPV games) +are not affected. + +The other drawback of this API is the overall system overhead, however this can +be mitigated by using the DirectX 12 back end. Please be aware though that this +back end is not experimental because it's new, but rather it's a slight +abuse/misuse of the DXGI API and allows us to bypass some windows internals. + +To enable the DirectX 12 back end the following configuration needs to be added +to the `looking-glass-host.ini` configuration: + +.. code:: ini + + [app] + capture=dxgi + + [dxgi] + copyBackend=d3d12 + d3d12CopySleep=5 + disableDamage=false + +The option `d3d12CopySleep` is to work around the lack of locking this misuse +of the API allows and you will need to tune this value to what suits your +hardware best. The default value is 5ms as this should work for most, lowing +it below 2ms is doubtful to be of practical use to anyone. If this value is too +low you may see screen corruption which is usually most evident while dragging +a window around on the Windows desktop. + +.. note:: + Lowering d3d12CopySleep can improve the UPS however the UPS metric makes + little sense when using the d3d12 back end as if this value is too low + unchanged frames will be doubled up. + +The `disableDamage` option may be needed to avoid screen corruption however +please note that this will increase the bandwidth required and in turn the +overall load on your system. + +The DXGI capture interface also offers a feature that allows downsampling the +captured frames in the guest GPU before transferring them to shared memory. +This feature is very useful if you are super scaling for better picture quality +and wish to reduce system memory pressure. + +The configuration for this is fairly straight forward and is defined as set of +rules to determine when to perform this downsampling. The format is as follows: + +.. code:: ini + + [dxgi] + downssample=RULE1,RULE2,RULE3 + +The rules are written as follows: + +.. code:: + + (>|>=)(WIDTH)x(HEIGHT):(LEVEL) + +The `LEVEL` is the fractional scale level where 1 = 50%, 2 = 25%, 3 = 12.5%. + +**Examples:** + +.. code:: ini + + [dxgi] + ; Downsample anything greater then 1920x1080 to 50% of it's original size + downsample=>1920:1080:1 + + ; Downsample exactly 1920x1080 to 25% of it's original size, and anything greater + ; then 1920x1080 to 50% of it's original size. + downsample=1920x1080:1,>1920x1080:2 + + ; Downsample anything greater or equal to 1920x1080 to 50% of it's original size + downsample=>=1920x1080:1 + +.. _host_capture_nvfbc: + +NVIDIA Frame Buffer Capture +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Due to the NVIDIA SDK License agreement this GPU feature is only available on +professional/workstation GPUs such as the Quadro series. It is known however +that **all** NVIDIA GPUs are capable of this as both GeForce Experience and +Steam are able to make use of it. + +If you are able to make use/enable this this feature it offers lower overall +system load and lower latency capture, and does not suffer from the mouse +motion stutter issues that DXGI suffers from. + +To enable it's usage use the following configuration in the +`looking-glass-host.ini` file: + +.. code:: ini + + [app] + capture=nvfbc + +If this feature is unavailable to you the host application will fail to start +and the host log will contain an error stating that the feature is not +available. + +The NVFBC capture interface also offers a feature much like DXGI to allow +downsampling the captured frames in the guest GPU before transferring them to +shared memory. However unlike DXGI which is limited to fractional scaling, +NvFBC is able to scale to any arbitrary resolution. + +The configuration for this is fairly straight forward and is defined as set of +rules to determine when to perform this downsampling. The format is as follows: + +.. code:: ini + + [nvfbc] + downssample=RULE1,RULE2,RULE3 + +The rules are written as follows: + +.. code:: + + (>|>=)(WIDTH)x(HEIGHT):(TARGET WIDTH)x(TARGET HEIGHT) + +**Examples:** + +.. code:: ini + + [nvfbc] + ; Downsample exactly 3840x2160 to 1920x1080 + downsample=3840x2160:1920x1080 + + ; Downsample anything greater then 1920x1080 to 1920x1080 + downsample=>1920x1080:1920x1080 + + ; Downsample 3840x2160 to 1920x1080, or 3840x2400 to 1920x1200 + downsample=3840x2160:1920x1080,3840x2400:1920x1200 diff --git a/doc/words.txt b/doc/words.txt index f7fce2d9..ca034456 100644 --- a/doc/words.txt +++ b/doc/words.txt @@ -5,15 +5,18 @@ cgroups clang cmake config +CopySleep Debian dejavu deuteranope dev dir +DirectX distros dmabuf downscaler downscaling +downsampling fullscreen gcc gnif @@ -42,6 +45,7 @@ passthrough pre protanope QEMU +Quadro radeon realtime renderer