Skip to content

surface-suspension: Add surface suspension protocol

Autumn Ashton requested to merge frog/wayland-protocols:surface-suspension into main

Description

This protocol provides the ability for clients to know when their surfaces are suspended or restored.

Many Wayland compositors suspend a client's windows' buffers when their associated windows are fully occluded (hidden).

If a client does not have occlusion information, they will hang on their presentation thread when trying to acquire a buffer when suspended. This is problematic as it can lead to apps/games hanging indefinitely until they are unoccluded and their buffers get restored.

This is still problematic even for graphics APIs' WSIs that have a timeout for image acquisition as the majority of games and apps simply set the timeout to be infinite as it was not designed to indicate or be affected by window occlusion. Even in cases where the timeout is not infinite, hanging the presentation thread in this way is not ideal.

There is no advantage to suspending the app's presentation thread in this way as there could be potentially other threads still working in parallel -- by providing a better mechanism to indicate suspension, the client can be smarter and additional work can be avoided.

The solution this protocol provides is a pair of events indicating surface buffer suspension and restoration.

Client apps and their windowing/graphics APIs can listen to these events and handle surface suspension accordingly.

This solves the acquire-blocking problem, in addition to allowing clients to free their buffers (and potentially other resources dependent on their buffers) to save memory and suspend rendering work on other threads.

In a Vulkan implementation, this may look like vkAcquireNextImageKHR returning VK_OUT_OF_DATE_KHR with vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface returning a maxImageExtent of (0, 0) [1].

Footnotes

[1] https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VkSwapchainCreateInfoKHR

Implementations

Clients:

Compositors:

Final Notes

Mesa is definitely not the only client that would benefit from this protocol, frameworks such as glfw (for glfwGetFramebufferSize to return (0, 0)) and SDL would too.

Browsers, games and other apps would be able to consume this protocol either directly for their surfaces or from the suspension information given by maxImageExtent in vkGetPhysicalDeviceSurfaceCapabilitiesKHR to suspend additional rendering work and free resources.

Closes: #38 (closed)

Edited by Daniel Stone

Merge request reports