feat(linux/xdgportal): implement event-driven capture

[psyke83]

Description

feat(linux/xdgportal): implement event-driven capture

Summary of changes:
* Synchronized capture:
  - Move frame_cv wait to beginning of loop as a more efficient way to
    wait for a new buffer whilst ensuring that unintentional buffer
    reuse doesn't occur.
* Improved duplicate detection:
  - Transition to duplicate detection logic using a combination
    of SPA_META_Header (PTS) and SPA_META_VideoDamage metadata.
  - Drop frames when PTS delta is zero and no damage is reported;
    this helps to smoothen out stuttering unique to KWin.

Additional fixes:

fix(linux/xdgportal): fix pipewire teardown logic, GNOME XDG stop icon

* Destroying the core and context during a reinit can cause a deadlock
which can be reproduced when PW_STREAM_FLAG_RT_PROCESS is set. Fix
by ensuring that full teardown is only done in pipewire destructor.
* Add a delay before sending the interrupt signal, as the GNOME
XDG portal needs time to detect changes, otherwise Sunshine will
crash when the users manually stops the stream on mutter.

Screenshot

Issues Fixed or Closed

Roadmap Issues

Type of Change

• feat: New feature (non-breaking change which adds functionality)
• fix: Bug fix (non-breaking change which fixes an issue)
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.)
• refactor: Code change that neither fixes a bug nor adds a feature
• perf: Code change that improves performance
• test: Adding missing tests or correcting existing tests
• build: Changes that affect the build system or external dependencies
• ci: Changes to CI configuration files and scripts
• chore: Other changes that don't modify src or test files
• revert: Reverts a previous commit
• BREAKING CHANGE: Introduces a breaking change (can be combined with any type above)

Checklist

• Code follows the style guidelines of this project
• Code has been self-reviewed
• Code has been commented, particularly in hard-to-understand areas
• Code docstring/documentation-blocks for new or existing methods/components have been added or updated
• Unit tests have been added or updated for any new or modified functionality

AI Usage

• None: No AI tools were used in creating this PR
• Light: AI provided minor assistance (formatting, simple suggestions)
• Moderate: AI helped with code generation or debugging specific parts
• Heavy: AI generated most or all of the code changes

[psyke83]

I'm marking this ready for review, but I'd appreciate if some other folks could test and verify it works OK on their configuration before considering this for merging.

I've tested on GNOME and KDE 6.6.0 via Fedora 43. The updated duplication logic solves a few issues:

• intermittent stuttering when host rate = stream rate (i.e. 60 -> 60), especially seen in KWin, seems to be completely gone.
• When min_fps_target is set to 1, the stream will still go idle, but ramping from ~1fps to 60fps is instantaneous. This means that there's no obvious stuttering in KWin's animations when transitioning between idle to active due to the damage tracking properly tracking when new frames actually have changes.
• Streaming 30fps host content on a 60fps stream no longer jumps erratically between 30-60; the damage+pts delta tracking ensures that the framerate is accurate, so it remains at a solid ~30fps (or whatever rate the host is rendering). The only exception is when the host cursor is visible, which shows that damage tracking is working as expected, as the cursor updates can run faster than the content.

[codecov]

Bundle Report

Bundle size has no change ✅

[codecov]

Codecov Report

❌ Patch coverage is 0% with 71 lines in your changes missing coverage. Please review.
✅ Project coverage is 15.32%. Comparing base (c7bca41) to head (aa9a821).
⚠️ Report is 8 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/platform/linux/portalgrab.cpp	0.00%	68 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4768      +/-   ##
==========================================
- Coverage   15.37%   15.32%   -0.05%     
==========================================
  Files          97       97              
  Lines       20668    20712      +44     
  Branches     9472     9499      +27     
==========================================
- Hits         3178     3175       -3     
+ Misses      13815    13716      -99     
- Partials     3675     3821     +146     

Flag	Coverage Δ
Archlinux	11.03% <0.00%> (-0.04%)	⬇️
FreeBSD-14.3-aarch64	?
FreeBSD-14.3-amd64	13.00% <0.00%> (-0.06%)	⬇️
Homebrew-ubuntu-22.04	13.23% <0.00%> (-0.04%)	⬇️
Linux-AppImage	11.44% <0.00%> (-0.04%)	⬇️
Windows-AMD64	13.49% <ø> (ø)
Windows-ARM64	12.35% <ø> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/platform/linux/graphics.h	0.00% <ø> (ø)
src/platform/linux/portalgrab.cpp	3.56% <0.00%> (-0.20%)	⬇️

... and 55 files with indirect coverage changes

[neatnoise]

Works ok for me. I haven't noticed the difference to the previous portalgrab state though. Tested on the up to date CachyOS with KDE, AMD GPU

[ReenigneArcher]

I'm marking this ready for review, but I'd appreciate if some other folks could test and verify it works OK on their configuration before considering this for merging.

Do you want to ask for more volunteers on Discord? There is a tester-linux role we could tag.

[psyke83]

Do you want to ask for more volunteers on Discord? There is a tester-linux role we could tag.

Perhaps. I've refreshed the PR to make the check less strict as I've identified that stuttering with KWin may actually be a bug on the compositor side related to XWayland applications. It's either this bug, or a variation of the same issue that only applies to screencasting.

If testing this PR (or portalgrab on master) with Steam games, you're going to see stuttering in games due to Proton using XWayland by default. An effective workaround is to use a Proton fork such as Proton GE or Proton-cachyos, and enable the Wayland driver via this launch argument for your games:

PROTON_ENABLE_WAYLAND=1 %command%

This will currently break Steam's overlay, but it does resolve all stuttering when streaming via KWin (at least on my system).

This workaround doesn't seem to be necessary on GNOME/mutter, but it may be worth trying to yield improved latency and/or performance.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud