From 05148f8df9eacd5c1d8e26a03ea483703569509d Mon Sep 17 00:00:00 2001 From: Adam Sheehan Date: Wed, 4 Jan 2023 14:24:45 -0500 Subject: [PATCH] Expand documentation of RawDisplayHandle (#106) I came to this crate after reading about the recent changes to [`glutin`][0]. At a glance I didn't understand the difference between `RawWindowHandle` and `RawDisplayHandle` (or even what a display was), and the enums looked mostly the same. After reading through this [issue][1] and digging through the structs, I have a better understanding of what each type represents, but I thought it would be useful to add a line clarifying the distinction between the two. I also added some examples of what external types may be represented for a few platforms. [0]: https://github.com/rust-windowing/glutin/releases/tag/v0.30.0 [1]: https://github.com/rust-windowing/raw-window-handle/issues/92 --- src/lib.rs | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 01c70a5..f20fee3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -18,6 +18,12 @@ //! added without breaking backwards compatibility. Each struct provides an `empty` method that may //! be used along with the struct update syntax to construct it. See each specific struct for //! examples. +//! +//! ## Display Handles +//! +//! Some windowing systems use a separate display handle for some operations. The display usually +//! represents a connection to some display server, but it is not necessarily tied to a particular +//! window. See [`RawDisplayHandle`] for more details. #[cfg(feature = "alloc")] extern crate alloc; @@ -81,7 +87,14 @@ unsafe impl HasRawWindowHandle for alloc::sync:: } } -/// An enum to simply combine the different possible raw window handle variants. +/// A window handle for a particular windowing system. +/// +/// Each variant contains a struct with fields specific to that windowing system +/// (e.g. [`Win32WindowHandle`] will include a [HWND], [`WaylandWindowHandle`] uses [wl_surface], +/// etc.) +/// +/// [HWND]: https://learn.microsoft.com/en-us/windows/win32/winmsg/about-windows#window-handle +/// [wl_surface]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_surface /// /// # Variant Availability /// @@ -216,7 +229,20 @@ unsafe impl HasRawDisplayHandle for alloc::sync } } -/// An enum to simply combine the different possible raw display handle variants. +/// A display server handle for a particular windowing system. +/// +/// The display usually represents a connection to some display server, but it is not necessarily +/// tied to a particular window. Some APIs can use the display handle without ever creating a window +/// handle (e.g. offscreen rendering, headless event handling). +/// +/// Each variant contains a struct with fields specific to that windowing system +/// (e.g. [`XlibDisplayHandle`] contains a [Display] connection to an X Server, +/// [`WaylandDisplayHandle`] uses [wl_display] to connect to a compositor). Not all windowing +/// systems have a separate display handle (or they haven't been implemented yet) and their variants +/// contain empty structs. +/// +/// [Display]: https://www.x.org/releases/current/doc/libX11/libX11/libX11.html#Display_Functions +/// [wl_display]: https://wayland.freedesktop.org/docs/html/apb.html#Client-classwl__display /// /// # Variant Availability ///