Skip to content

wayland: opt-in render control with partial damage - #1448

Open
bbedward wants to merge 12 commits into
quickshell-mirror:masterfrom
bbedward:render-control
Open

bbedward wants to merge 12 commits into
quickshell-mirror:masterfrom
bbedward:render-control

Conversation

@bbedward

@bbedward bbedward commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Describe your changes

Adds an opt-in RenderControl pragma that renders windows through QQuickRenderControl instead of Qt's render loop. This is Wayland and OpenGL only, and lets quickshell own presentation when enabled.

Details and descisions

There are two parts:

  1. RenderControl: each Wayland window gets a QQuickRenderControl instead of Qt's loop. Quickshell drives polish, sync, and render itself. Renders into a dmabuf-backed texture and commits the buffer to the wl_surface directly with explicit damaged rectangles. If dmabuf or OpenGL is unavailable then the window falls back to Qt's render loop.

  2. Damage tracker: A QSGAbstractRenderer is attached to the scene graph as a second renderer. It receives node change notifications but doesn't draw anything. It caches subtrees and measures geometry (that it understands) including textures, frag shader effects, and glyphas. Geometry it doesnt understand falls back to full surface damage.

Why a damage tracker?
Since I've seen before in quickshell discussions things like "QT already tracks the damage but doesnt report it". In my research into the QT renderer, that isn't exactly accurate in the hardware path.

QT tracks dirty nodes and computes geometry bounds for things like overlap checks. It does not maintain a surface damage region that tracks what changed since the last frame. So there isnt an existing region we can just forward to the compositor or eglSwapBuffersWithDamageKHR

The software renderer does support partial updates, but not ShaderEffect .

Qt's own EGL path calls eglSwapBuffers instead of eglSwapBuffersWithDamageKHR (so no damage passed). Owning the frame commits lets us submit the region ourselves.

Without the tracker we would own the frame presentation but still not be able to report partial damage which is more or less the entire point of this change

Why not eglSwapBuffersWithDamageKHR

My initial approach used it. Quickshell exported its own eglSwapBuffers symbol to intercept Qt's calls, using symbol interposition. The wrapper passed the tracker's damage to eglSwapBuffersWithDamageKHR.

That kept Qt's render loop, but the hook only ran at presentation, after Qt had already rendered the frame. With QQuickRenderControl, we can also skip rendering when there's no damage and nothing else requires a render, then submit the buffer and damage together when there is.

Open concerns

  1. This adds tracking work and relies on Qt private ABIs. Quickshell already depends on private ABIs, but with this it depends on more:
  • QSGAbstractRenderer
  • QQuickWindowPrivate::renderer, fireFrameSwapped, pendingFontUpdate, visualizationMode
  • QSGMaterialShaderPrivate
  • QSGRenderLoop::animationDriver() and QSGContext::isVSyncDependent()
  • QWaylandWindow::safeCommit, surfaceSize, clientSideMargins, decoration
  • QWaylandBuffer
  • QWaylandAbstractDecoration
  • QPA QPlatformWindow::hasPendingUpdateRequest / deliverUpdateRequest

These ABIs havent changed in a very, very long time. So hopefully there's minimal risk of backwards incompatible changes anytime soon.

  1. It only works with the OpenGL backend, not Vulkan. I think the render control approach makes adding Vulkan fairly straight forward, but since OpenGL is default I'd rather try to land this first and do Vulkan as a follow up (if wanted)

  2. View3D has a vertical mirroring issue with RenderControl enabled. This looks related to how Qt Quick 3D sets up its viewport. Since it's opt-in and most quickshell projects are probably not using View3D my personal opinion is to accept the gap for now. It is visible in the manual QML test.

Metrics

Measured with rendercontrol-qt.qml and rendercontrol-enabled.qml, niri, AMD 890m. Each run was 140s.

Qt render loop RenderControl change
quickshell CPU time 3.38 s 3.04 s -10%
quickshell instructions 4.36 G 3.83 G -12%
quickshell GPU time 1.52 s 1.28 s -16%
compositor (niri) GPU time 1.08 s 0.87 s -19%

Since the test is large windows animating every frame, it isn't exactly indicative of typical use - but of a more extreme scene example.

This is the script I ran to test, it's basic but demonstrates there is some improvement

export QS_RENDERCONTROL_START=$(( $(date +%s%3N) + 5000 ))
qs -p src/window/test/manual/rendercontrol-qt.qml &   # or rendercontrol-enabled.qml
QS=$!; WM=$(pgrep -x niri)
sleep 5

perf stat -e task-clock,instructions:u -p $QS -- sleep 140 &

gfx() { awk '/drm-client-id/{id=$2} /drm-engine-gfx/{ns[id]=$2} END{s=0; for (i in ns) s+=ns[i]; print s}' /proc/$1/fdinfo/*; }
q0=$(gfx $QS); w0=$(gfx $WM); sleep 140; q1=$(gfx $QS); w1=$(gfx $WM)
echo "quickshell gpu $(( (q1-q0)/1000000 )) ms, compositor gpu $(( (w1-w0)/1000000 )) ms"
wait

Participation

I researched, planned, implemented, and tested 2 different approaches before this one (3 total)

  1. First attempt was to try to leverage transientParent to create subsurfaces within windows. This requires a QML component like Subsurface {} and just didn't work that nicely - it created way too many surfaces for something like a simple bar.
  2. Second attempt was intercepting eglSwapBuffers as mentioned above
  3. Third and current attempt is what was more or less described at a high-level in quickshell development channel, QQuickRenderControl backed windows

LLM Disclosure
I designed and wrote the base implementation myself, so I have a thorough understanding of the code and accept responsibility for it.

LLMs were used to help write the code as it is in this PR. My initial work had gaps, certain things wrong, etc. Also used LLMs to help with CPU and GPU profiling, and to implement some of the manual QML test cases.

I've been working on this for over a month, I left my local commit tree in tact instead of squashing it just to show the general process and bugs fixed along the way. Have been using with DMS basically exclusively for the entire month, havent ran into any problems for awhile so felt confident to open the PR.

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.

2 participants