mirror of
https://github.com/gnif/LookingGlass.git
synced 2026-08-22 07:01:30 +00:00
121 lines
4.3 KiB
ReStructuredText
121 lines
4.3 KiB
ReStructuredText
.. _obs_plugin:
|
|
.. _open_broadcaster_software:
|
|
|
|
OBS plugin
|
|
##########
|
|
|
|
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:
|
|
|
|
Build and install
|
|
-----------------
|
|
|
|
On Debian-based systems, install the OBS headers and the small set of build
|
|
dependencies used by the plugin:
|
|
|
|
.. code:: bash
|
|
|
|
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
|
|
make install
|
|
|
|
For a system-wide installation, omit ``-DUSER_INSTALL=1`` and run
|
|
``sudo make install``.
|
|
|
|
Add the source
|
|
--------------
|
|
|
|
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.
|
|
|
|
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 a Looking Glass source in OBS
|
|
|
|
Adding the Looking Glass source
|
|
|
|
DMA-BUF and CPU copy
|
|
--------------------
|
|
|
|
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``.
|