Skip to content

fix: Resolve minimum_fps_target related issues on all platforms#4967

Open
psyke83 wants to merge 2 commits intoLizardByte:masterfrom
psyke83:min_fps_target_fixes
Open

fix: Resolve minimum_fps_target related issues on all platforms#4967
psyke83 wants to merge 2 commits intoLizardByte:masterfrom
psyke83:min_fps_target_fixes

Conversation

@psyke83
Copy link
Copy Markdown
Contributor

@psyke83 psyke83 commented Apr 9, 2026

Description

Multiples changes that affects all platforms, aimed at resolving issues related to the minimum_fps_target setting. During testing of both portalgrab and kmsgrab, certain streaming conditions can be observed to cause the stream framerate cap to be violated, which is resolved by these changes.

Revert "fix(linux/xdgportal): avoid duplicate frame insertion

This reverts commit 99d4e05.

fix(video): avoid minimum_fps_target violations

Resolves stream framerate violations by avoiding insertion of a
single duplicate frame immediately after encoding a real frame, thus
giving the platform capture thread some breathing room if frame
processing time runs longer than usual.

Screenshot

Issues Fixed or Closed

Fixes #4906

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 psyke83 force-pushed the min_fps_target_fixes branch from 3a84519 to 3bac8e3 Compare April 9, 2026 19:29
@psyke83 psyke83 changed the title Min fps target fixes fix: Resolve minimum_fps_target related issues on all platforms; kmsgrab improvements Apr 9, 2026
@psyke83
Copy link
Copy Markdown
Contributor Author

psyke83 commented Apr 9, 2026

The basic issue that this PR aims to solve is framerate violations that occur when frame processing latency is a bit higher than usual. This can happen with any capture method, but a solid Linux testcase that can be replicated for the issue against master is the following:

  • Host running KDE, making sure that the hardware cursor plane is enabled (i.e., make sure KWIN_FORCE_SW_CURSOR=1 is not set in your environment)
  • Keep minimum_fps_target as the default (0) or unset.
  • Capture using kmsgrab + vaapi or vulkan.
  • Stream the desktop with active content that is rendering at the full stream framerate; for example, open https://www.vsynctester.com/ and leave it running.
  • Repeatedly hover the mouse over elements on the desktop that will rapidly trigger cursor shape changes, such as moving from the browser's address URL bar to the tab selection/window decorations so that the cursor toggles between the selection cursor and pointer. Avoid moving too fast, as you can trigger the "shake" cursor effect on KDE, which switches to a software cursor that is not affected by the issue.

Result on master:

  • During cursor shape changes, the decoding framerate violates the stream limit (bursting to 70+ on a 60fps stream) and frame queue delay becomes very high. This results in noticeable stuttering.

Results with PR:

  • The stream no longer violates the limit or has noticeable stuttering, and the minimum_fps_target still works as expected.

Requesting a test from @andygrundman and @oryschakj-personal if it's not too much trouble.

@ReenigneArcher I've also added two additional commits. One implements snapshot timeout + duplicate filtering on kmsgrab, and the other reverts the portalgrab workaround related to the same issue that this PR should hopefully solve. If you want we can split these into separate PRs, but I think it's helpful to test all three changes together as a first step.

@psyke83 psyke83 marked this pull request as ready for review April 9, 2026 20:03
@codecov
Copy link
Copy Markdown

codecov bot commented Apr 9, 2026

Bundle Report

Bundle size has no change ✅

@codecov
Copy link
Copy Markdown

codecov bot commented Apr 9, 2026

Codecov Report

❌ Patch coverage is 0% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 18.17%. Comparing base (d3330d1) to head (48e6847).
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
src/video.cpp 0.00% 6 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##           master    #4967      +/-   ##
==========================================
- Coverage   18.20%   18.17%   -0.03%     
==========================================
  Files         108      108              
  Lines       23409    23409              
  Branches    10330    10331       +1     
==========================================
- Hits         4261     4254       -7     
- Misses      14152    14917     +765     
+ Partials     4996     4238     -758     
Flag Coverage Δ
Archlinux 11.62% <0.00%> (+<0.01%) ⬆️
FreeBSD-14.3-aarch64 ?
FreeBSD-14.3-amd64 13.79% <0.00%> (ø)
Homebrew-ubuntu-22.04 13.94% <0.00%> (+<0.01%) ⬆️
Linux-AppImage 12.50% <0.00%> (+<0.01%) ⬆️
Windows-AMD64 14.90% <0.00%> (-0.01%) ⬇️
Windows-ARM64 13.22% <0.00%> (+<0.01%) ⬆️
macOS-arm64 19.02% <0.00%> (-0.01%) ⬇️
macOS-x86_64 18.37% <0.00%> (-0.01%) ⬇️

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

Files with missing lines Coverage Δ
src/platform/common.h 33.01% <ø> (+0.61%) ⬆️
src/platform/linux/portalgrab.cpp 9.55% <ø> (+0.02%) ⬆️
src/video.cpp 32.28% <0.00%> (-0.20%) ⬇️

... and 28 files with indirect coverage changes


Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d3330d1...48e6847. Read the comment docs.

Resolves stream framerate violations by avoiding insertion of a
single duplicate frame immediately after encoding a real frame, thus
giving the platform capture thread some breathing room if frame
processing time runs longer than usual.
@psyke83 psyke83 force-pushed the min_fps_target_fixes branch from 3bac8e3 to 48e6847 Compare April 9, 2026 23:21
@psyke83 psyke83 changed the title fix: Resolve minimum_fps_target related issues on all platforms; kmsgrab improvements fix: Resolve minimum_fps_target related issues on all platforms Apr 9, 2026
@psyke83
Copy link
Copy Markdown
Contributor Author

psyke83 commented Apr 9, 2026

I've backed out the kmsgrab duplicate detection change as it was triggering some false timeouts. I'll check if that can be fixed later and send in a separate PR if so. The testcase and fix I described for kmsgrab still applies to this PR in its current state, however.

I'm still testing this PR with portalgrab to make 100% sure that it solves the issue of runaway framerate bursting; it's more difficult to reproduce consistently, so it may take some time to see if there's a regression.

@sonarqubecloud
Copy link
Copy Markdown

sonarqubecloud bot commented Apr 9, 2026

@oryschakj-personal
Copy link
Copy Markdown

I got the build installed (48e6847) but can't get either VA-API or Vulkan running on my 5090. Is the fix still applicable to nvenc?

@psyke83
Copy link
Copy Markdown
Contributor Author

psyke83 commented Apr 10, 2026

I got the build installed (48e6847) but can't get either VA-API or Vulkan running on my 5090. Is the fix still applicable to nvenc?

Yes. You can still try the test case as long as you test with the kmsgrab capture method, the encoder shouldn't matter. This PR should resolve your issue reported in #4906 (but make sure the hardware cursor is enabled in kwin and set minimum_fps_target back to the default if you want to trigger the stutter issue properly).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Mouse movement spikes CPU usage with KMS

2 participants