mirror of
https://github.com/gnif/LookingGlass.git
synced 2026-08-22 15:11:31 +00:00
[docs] guide: document current Looking Glass features
This commit is contained in:
Geoffrey McRae
177
doc/obs.rst
177
doc/obs.rst
@@ -1,105 +1,120 @@
|
||||
.. _obs_plugin:
|
||||
.. _open_broadcaster_software:
|
||||
|
||||
OBS plugin
|
||||
##########
|
||||
|
||||
You can add a Looking Glass video feed
|
||||
to OBS as a video source with the included OBS plugin. This provides a
|
||||
lower-latency alternative to capturing the Looking Glass client window
|
||||
with a Screen or Window Capture source.
|
||||
|
||||
This may help improve your viewers' watching experience, and
|
||||
allows you to use your host privately.
|
||||
|
||||
Build instructions
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The OBS plugin is included in the main source tree of Looking Glass. The
|
||||
building process is very similar to the
|
||||
:ref:`client's <build_client_section>`.
|
||||
|
||||
Dependencies
|
||||
^^^^^^^^^^^^
|
||||
|
||||
The OBS plugin requires the following extra dependencies alongside the
|
||||
:ref:`client's build
|
||||
dependencies <installing_build_dependencies>`.
|
||||
|
||||
- ``libobs-dev``
|
||||
|
||||
Install this package with ``apt-get``
|
||||
|
||||
.. code:: bash
|
||||
|
||||
apt-get install libobs-dev
|
||||
The Looking Glass OBS plugin reads video from LGMP directly instead of
|
||||
capturing the client window. The client can stay hidden or show overlays
|
||||
without adding them to the OBS source. This source does not provide audio or
|
||||
input; add the required audio source separately in OBS.
|
||||
|
||||
Use an OBS plugin from the same Looking Glass release as the IDD and client.
|
||||
The shared-memory protocol is versioned and mismatched components will not
|
||||
connect.
|
||||
|
||||
.. _obs_building:
|
||||
|
||||
Building
|
||||
^^^^^^^^
|
||||
Build and install
|
||||
-----------------
|
||||
|
||||
These instructions are similar to building the
|
||||
:ref:`client <client_building>`.
|
||||
On Debian-based systems, install the OBS headers and the small set of build
|
||||
dependencies used by the plugin:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
mkdir obs/build
|
||||
apt-get install cmake gcc libobs-dev libdw-dev libunwind-dev make pkg-config
|
||||
|
||||
Use ``-DENABLE_BACKTRACE=no`` when configuring if ``libdw-dev`` and
|
||||
``libunwind-dev`` are intentionally omitted.
|
||||
|
||||
From the Looking Glass source directory, build the plugin for the current
|
||||
user:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
mkdir -p obs/build
|
||||
cd obs/build
|
||||
cmake -DUSER_INSTALL=1 ../
|
||||
make
|
||||
|
||||
Alternatively, if you would like to install the plugin for all users:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
mkdir obs/build
|
||||
cd obs/build
|
||||
cmake ../
|
||||
make
|
||||
|
||||
Installation
|
||||
~~~~~~~~~~~~
|
||||
|
||||
You can install the plugin by running ``make install``.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
make install
|
||||
|
||||
If you've opted to install the plugin for all users, you will need to run
|
||||
this command as ``root``.
|
||||
For a system-wide installation, omit ``-DUSER_INSTALL=1`` and run
|
||||
``sudo make install``.
|
||||
|
||||
.. code:: bash
|
||||
Add the source
|
||||
--------------
|
||||
|
||||
sudo make install
|
||||
1. Start OBS after installing the plugin.
|
||||
2. In **Sources**, select **Add** and then **Looking Glass Client**.
|
||||
3. Set **SHM File** to the same KVMFR device or shared-memory file used by the
|
||||
VM.
|
||||
4. Enable **Hide mouse cursor** if OBS should omit the guest pointer.
|
||||
5. Leave **Use DMABUF import** enabled with KVMFR unless the OBS log reports
|
||||
that the host graphics driver cannot import it.
|
||||
|
||||
Setup
|
||||
~~~~~
|
||||
|
||||
Once installed, you can select the *"Looking Glass Client"* source from
|
||||
the OBS sources menu. Configuration requires the IVSHMEM file
|
||||
used by the VM, and this is pre-populated with the default
|
||||
filename for Looking Glass.
|
||||
|
||||
.. _open_broadcaster_software:
|
||||
|
||||
|
||||
Open Broadcaster Software
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The plugin is made for OBS, an open source streaming and recording
|
||||
studio. Find out more at https://obsproject.com/
|
||||
|
||||
OBS is available under most distributions as *obs-studio* or just *obs*.
|
||||
|
||||
Screenshots
|
||||
~~~~~~~~~~~
|
||||
The OBS process needs read and write access to ``/dev/kvmfr0``. Use the same
|
||||
udev rule as the Looking Glass client; see :ref:`ivhsmem_kvmfr_permissions`.
|
||||
|
||||
.. figure:: images/Looking-Glass-OBS-Source-Add.png
|
||||
:alt: Adding the plugin as a video source
|
||||
:alt: Adding a Looking Glass source in OBS
|
||||
|
||||
Adding the plugin as a video source
|
||||
Adding the Looking Glass source
|
||||
|
||||
.. figure:: images/Looking-Glass-OBS-config.png
|
||||
:alt: Plugin configuration settings
|
||||
DMA-BUF and CPU copy
|
||||
--------------------
|
||||
|
||||
Plugin configuration settings
|
||||
DMA-BUF import is available with OBS 27 or newer and is enabled by default.
|
||||
It imports KVMFR into the GPU and makes a full-frame GPU snapshot into
|
||||
OBS-owned storage before releasing the shared frame. It avoids the CPU upload,
|
||||
but it is not a zero-copy path to the final OBS texture. If import or the
|
||||
snapshot fails, the plugin falls back to a CPU copy and records the failure in
|
||||
the OBS log. A plain POSIX shared-memory file always uses the CPU path.
|
||||
|
||||
Disabling DMA-BUF is useful for diagnosis, but it increases CPU and memory
|
||||
bandwidth use at high resolutions.
|
||||
|
||||
HDR
|
||||
---
|
||||
|
||||
HDR-aware OBS color-space support requires OBS 28 or newer. The plugin reports
|
||||
the source color space from the IDD frame, but OBS must also be configured with
|
||||
an HDR canvas and a suitable recording or streaming output. An SDR OBS project
|
||||
will not become HDR merely because the guest frame is HDR.
|
||||
|
||||
Frame rate and multiple clients
|
||||
-------------------------------
|
||||
|
||||
An active OBS source requests the global frame rate configured under **OBS
|
||||
Settings > Video**. There is no separate FPS control in the Looking Glass
|
||||
source. The IDD uses the fastest request among all active consumers, so a 120
|
||||
Hz client can raise the producer cadence while OBS records at 60 FPS. Each
|
||||
consumer still selects the newest frame for its own deadline.
|
||||
|
||||
The OBS source releases its cadence request while it is inactive or hidden.
|
||||
IDD log lines that report acquired, skipped and published frames are expected:
|
||||
frames newer than the previous publication may be acquired and superseded
|
||||
without copying all of them through IVSHMEM.
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
||||
No source image
|
||||
Check KVMFR permissions, the selected device and component versions. The
|
||||
OBS log reports both expected protocol versions when they do not match.
|
||||
|
||||
High CPU use
|
||||
Confirm that DMA-BUF stayed enabled and that import succeeded. Also check
|
||||
whether OBS and the client are both performing expensive scaling.
|
||||
|
||||
Jitter when another client starts
|
||||
Confirm OBS is using a current matching plugin. Current cadence support
|
||||
allows consumers with different refresh rates without forcing OBS to
|
||||
display every frame requested by the fastest client.
|
||||
|
||||
HDR looks washed out
|
||||
Check the OBS canvas color space, output format and the guest HDR state. Do
|
||||
not apply the client's HDR-to-SDR settings to the independent OBS source.
|
||||
|
||||
OBS is available from https://obsproject.com/ and is packaged by most Linux
|
||||
distributions as ``obs-studio`` or ``obs``.
|
||||
|
||||
Reference in New Issue
Block a user