# waybackend
A simple, low-level implementation of the Wayland client protocol.
## Design decisions
- manually call Wayland requests (in practice, you must program while
consulting the protocol documentation).
- low-level constructs without `Arc` or `Mutex`.
- no generic object management. The developer must know ahead of time which
protocols they will be interacting with, and inform us of this through an
`enum`.
- do not expose an event queue. The user must decide how to poll for events
themselves.
- only has blocking IO
- `libwayland` compatible when it comes to wayland object creation and
management
- use [rustix](https://crates.io/crates/rustix) for better syscalls than raw
`libc`.
## Project status
Currently, I use this for a few personal projects of mine. It hasn't shown any
bugs in there, so you may consider it something like an advanced beta.
## Crates
There are only 2 main crates:
- `waybackend`: the main crate that implements the client side of
the Wayland wire protocol.
- `waybackend-scanner`: implements automatic code generation for the many
Wayland protocols.
## Why make this when [smithay](https://crates.io/crates/smithay-client-toolkit) and [wayrs](https://crates.io/crates/wayrs-client) exist?
This crate has different design goals than `smithay` and `wayrs`. Specifically:
- `smithay` uses a lot of `Arc` and dynamic dispatch to implement its API.
This greatly increases its incurred overhead, specially in terms of memory
usage.
- `wayrs` is better, but it uses the `libc` crate for syscalls, and still has
proxies and other minor design decisions that make it less than ideal.
This crate was created specifically to allow for an efficient, low overhead
solution for a wayland client backend. We pursued that goal as much as it is
reasonable.
The tradeoff is that this crate can be rather annoying to use. You will have to
make manual calls to Wayland requests, allowing you to do non-sensical things
such as ask for a `wl_surface` from a `wl_shm`, which will raise a protocol
error.
## Is it worth it?
In all honesty, only if you are somewhat obsessed with having a very low memory
footprint, or if your application is extremely simple, to the point that these
optimizations will be actually felt. If you have a complicated application that,
for example, needs to store font data to render text, it is likely that the
extra overhead from `smithay` or `wayrs` is negligeable next to just keeping the
font data in memory.
On the other hand, if you have a very simple application (say, a wallpaper
setter), that doesn't do very much, you can use `waybackend` to make it very
resource efficient. It will also compile much faster than with `smithay`, though
it might take a little longer compared to `wayrs`, since we use a few extra
crates (mainly `rustix`) and you will have to run a build script to generate the
Wayland protocol code.
## Alternatives
As already mentioned, the two best alternatives are
[smithay](https://crates.io/crates/smithay-client-toolkit) and
[wayrs](https://crates.io/crates/wayrs-client). `smithay` is a more widely used,
and you can use their [wayland client](https://crates.io/crates/wayland-client)
implementation directly for a more low-level, low overhead approach. `wayrs`, on
the other hand, is lower-overhead by default, though it offers no compatibility
with `libwayland`. `wayrs` also has support for non-blocking and assynchronous
IO, which we lack.