Safe bindings about x11-rs HOT 3 CLOSED

I'm leaning toward low-level, as high-level would almost result in a winit-like API but not cross-platform. If I get around to making this new crate, I can update glutin and winit to utilize it.

By low-level, I mean a safe library that doesn't do much more than speak the X11 protocol (similar to XCB)

OpenGL needs the exact pointers returned by the xlib available on the user's machine.
I don't think we can get away with anything else but raw bindings to xlib.

from x11-rs.

I'd like to deprecate the x11-dl crate in favor of safe bindings

I don't see what reason there could be for deprecating it. Though, dlib could probably be used to have both the static and dynamic bindings under one crate.

As far as APIs go, I've purposefully been keeping things straightforward, so that anyone reading the code would understand how it maps to Xlib. Here's some code from winit for getting frame extents:

let extents_atom = unsafe { self.get_atom_unchecked(b"_NET_FRAME_EXTENTS\0") };

if !hint_is_supported(extents_atom) {
    return None;
}

let extents: Option<Vec<c_ulong>> = self.get_property(
    window,
    extents_atom,
    ffi::XA_CARDINAL,
).ok();

(self is present because most of my util functions are methods on our XConnection struct, which is just all the dynamically loaded functions bundled with an X connection)

get_property returns Result<Vec<T>, GetPropertyError>, where T is constrained to c_char, c_short, and c_long (along with the unsigned counterparts). It handles all of the buffer stuff and memory safety for you, and just gives you all the data at once. I need to update it to return Result<Option<Vec<T>>, GetPropertyError> to better handle when the property is absent (since now you just get GetPropertyError::TypeMismatch(0) which kinda sucks), but I haven't gotten around to it yet.

There are still some design problems, i.e. get_atom_unchecked really irks me. The only way to make it safe while also eliminating pointless overhead seems to be to use a macro just like imgui-rs does.

One thing I've been thinking about is making more things more strongly typed, since while it's nice that it's statically verified that your return type is possible, it's not yet verified that it's correct. Since the vast majority of atoms people use have known meanings, it would be really sweet to be able to do something like this:

let extents = self.get_property::<NetFrameExtents>::(window);

Using a Property trait, which would use associated types and constants to abstract away the prop type and give you a return type that matches the prop type. This is something I've been planning on doing the next time I spruce up winit's X11 backend.

My API makes it obvious when a function is async, too. I've made a Flusher type, which is must_use (and prints an explanation of the Xlib output buffer if you don't use it), and provides you with the methods flush, sync, and queue to make all of this explicit. All async functions return this type. However, right now flush returns Result<(), XError>, which is wrong... we have no reason to believe we'll know the error status of the requests immediately after flushing the buffer. Really, the only reason I kept it there was because I wasn't ready to justify removing something like half of winit's error checks... I'd need to come up with a good time and place for error checking first.

In terms of what belongs in a standalone crate, one thing that's unresolved is whether or not it should include some higher-level utilities. hint_is_supported is one of these, but is the most trivial example. winit contains some pretty extensively tested heuristics for getting the correct frame extents on all WMs, accounting both for WMs that don't support the property and for ones that have various quirks. This is something that could be really useful for people to have, and that people are unlikely to implement correctly themselves.

from x11-rs.

Safe bindings specifically for X11 would be a whole lot more work than this project currently covers, and it wouldn't even work for many people's purposes. Closing for now.

from x11-rs.