At the same time, most of this post really is just a rant essentially saying that a low-level library is so flexible that using it directly results in code so verbose it can hardly be read. Yes, that's how good low-level designs always are.

You can turn a generic portable asynchronous ANSI C interface into a simple, blocking and platform-specific one with an abstraction layer. You can integrate it with all sorts of existing event loops and programming frameworks. You can customize it all you like but using it directly in an application will cost you a lot of patience. At the same time, you can't go in the opposite direction; from a "simple" blocking black-box interface to something that can reasonably host a complex GUI toolkit. If you're after simplicity, go higher-level.

I've been struggling with this initially as well, it's pretty poorly explained in docs. Short explanation:

Wayland-client library implements a queues over the socket. So to get it, you have to think about when is the socket read from and written to, and when are the queues pulled from or pushed to. There is always a default queue, but for example EGL+OpenGL creates it's own queue, which further makes it more confusing.

- `wl_display_dispatch_pending()` only pulls messages from default queue to callbacks

- `wl_display_dispatch()` also tries to do blocking read on the socket if no messages are in queue

- quite recently `wl_display_dispatch_queue_timeout()` was finally added, so you can do non-blocking read from the socket. earlier you had to hack the function yourself

- `wl_display_flush()` writes enqueued messages in queue to socket

- `wl_display_roundtrip()` sends a ping message and does blocking wait for response. the purpose is that you also send all enqueued requests and receive and process all responses. for example during init you call it to create registry and enumerate the objects, and you call it for second time to enumerate further protocol objects that got registered in registry callback, such as seat

- `eglSwapBuffers()` operates on its own queue, but reading from socket also enqueues to default queue, so you should always call `wl_display_dispatch_pending()` (on default queue) afterwards

There is also a way to get around being stuck in `eglSwapBuffers()` during window inhibition: disable the blocking with `eglSwapInterval(0)` and use `wl_surface_frame()` callback, and you get notified in callback when you can redraw and swap again. But you can't do blocking reads with `wl_display_dispatch()` anymore, have to use the timeout variant. After using it this way, you can also easily manage multiple vsynced windows independently on the same thread, and even use wayland socket in epoll event loop. None of this is documented of course.

The clipboard interface is definitely compromised a bit by being shared with drag-and-drop events, but it's not that complicated. Also there is a pitfall when you copy-paste to your own application and don't use any async event loop, you can get deadlocked by being expected to write and read on the same file descriptor at the same time.

Anyway, if I was persuaded that Wayland has a rather backwards design (here my reasons: https://news.ycombinator.com/item?id=47477083), now I have the confirmation that its philosophy is something like "put surfaces on the screen and distribute events to the clients, all the other stuff is not my business", and that exploring alternative approaches to window management is still worth it. Having applications that manage all their resources (canvases, events, decorations) is not bad per se (for example video games), but not all of them need to.

> Make easy things easy. Make hard things doable.

is generally unachievable. Instead, pick one:

- easy things easy, hard things impossible

- easy things tedious, hard things possible

(Unless you want to maintain two sets of interfaces in parallel.)

What scares me though are all the responsibilities passed to compositors, because what ends up happening is that each compositor may reimplement what should be common functionality in annoying ways. This is especially true for input things, like key remapping. This ultimately fragments linux desktop experiences even harder than it was before.

The API feels like a hardcore OOP/C++ developer's first C interface.

https://www.youtube.com/watch?v=HMKaM3FdsgY

No you don't need to reinvent the wheel thank you.

It's getting a bit boring, especially since none really does more than complain.

So I feel your pain. I did hear programming for Wayland is harder than X11, but I never did either so I have no idea if that is true.

It satisfies the requirement to "make easy things easy, make hard things doable" and it also gets you cross platform support.