EGL_KHR_platform_wayland: Clarify requirements of eglSwapBuffers

[jadahl]

The EGL implementation attaching the front buffer, posting damage, and committing during the call to eglSwapBuffers(WithDamage)() is a well established requirement that EGL Wayland clients currently rely upon, thus should be explicitly documented.

---

I noticed EGL_EXT_platform_wayland already existing, but EGL_KHR_platform_wayland seems to be the one most recently updated. Should this perhaps be targeting that, and with the changes to the KHR variant being ported over?

[amshafer]

Should we maybe clarify that the EGL implementation is the one who will do these requests instead of just saying they "will be requested"? It seems like that's the way things like this are worded in some other extensions for clarity.

Suggested change

	During the call to eglSwapBuffers wl_surface.attach will be requested with
	During the call to eglSwapBuffers wl_surface.attach will be requested by the EGL implementation with

Not sure if we also need to call out things like explicit sync points being sent by the implementation as part of this commit? I guess what you have right now just specifies the minimum set of requests the implementation will do, so that could be fine.

[cubanismo]

It seems hard both to enumerate all the state ever needed and to write general language that implies the right amount of state.

Maybe for explicit sync:

"if the EGL implementation associated a wp_linux_drm_syncobj_surface_v1 object with the surface, an acquire and a release point will be associated with the surface prior to the commit as well."

For others state the implementation might need to set as part of a commit, hopefully it makes more sense to call it out in separate extensions? E.g., as an interaction with this extension in a present timing extension, an HDR extension, etc., or in the other direction for existing EGL extensions that necessitate additional wayland surface state?

[jadahl]

I reworded things a bit while still trying to make it more explicit, because adding "by the EGL implementation" to every "requested" would have been a bit much.

[jadahl]

Didn't add anything about explicit sync there, as it's not strictly needed, but could be added too I guess.

[jadahl]

"if the EGL implementation associated a wp_linux_drm_syncobj_surface_v1 object with the surface, an acquire and a release point will be associated with the surface prior to the commit as well."

Added this as well, thanks.

[amshafer]

Context on the motivation for this: https://gitlab.freedesktop.org/wayland/wayland/-/merge_requests/423

[fooishbar]

It might be better to call out that this must be synchronous within eglSwapBuffers and cannot be deferred to a thread.

[cubanismo]

To me this language already implies that, but you could say something like "Before the call to eglSwapBuffers() returns" or similar, rather than "During the call to." It could still happen in another thread, but has to happen before the call ends from the calling thread's perspective, rather than some mangled interpretation of the call's duration from the driver's point of view.

[jadahl]

Is that better? I left out mentioning threads, because I guess it's still technically possible to offload anything to a thread, as long as the thread calling eglSwapBuffers is blocked.

[fooishbar]

I like it. Thanks!

[cubanismo]

This version looks good to me.