From bf19e5d210e5ab950a12b03eb69c56775b4469d2 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Sat, 28 Feb 2026 22:04:11 +0100 Subject: [PATCH 01/13] Document producer/consumer relationship --- Cargo.toml | 2 +- README.md | 12 +++++++----- src/lib.rs | 53 ++++++++++++++++++++++++++++++++++++++++++++++++----- 3 files changed, 56 insertions(+), 11 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 9644270..128b0e8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ name = "raw-window-handle" version = "0.6.2" authors = ["Osspial "] edition = "2021" -description = "Interoperability library for Rust Windowing applications." +description = "Interoperability helper between graphics crates" license = "MIT OR Apache-2.0 OR Zlib" repository = "https://github.com/rust-windowing/raw-window-handle" keywords = ["windowing"] diff --git a/README.md b/README.md index 8ed6e30..8010d9a 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,13 @@ [![Docs](https://docs.rs/raw-window-handle/badge.svg)](https://docs.rs/raw-window-handle) [![CI Status](https://github.com/rust-windowing/raw-window-handle/workflows/CI/badge.svg)](https://github.com/rust-windowing/raw-window-handle/actions) -This library provides standard types for accessing a window's platform-specific -raw window handle and display's platform-specific raw display handle. This does -not provide any utilities for creating and managing windows; instead, it -provides a common interface that window creation libraries (e.g. Winit, SDL) -can use to easily talk with graphics libraries (e.g. gfx-hal). +This crate is intended as an interoperability crate, that allows "producer" +crates to create a handle to a window surface, and for this handle to be +passed onwards to "consumer" crates for rendering to that surface. + +This crate does not by itself provide any utilities for creating and managing +windows, nor for rendering into them; use Winit or SDL for the former, and +Softbuffer, Glutin or Wgpu for the latter. ## MSRV Policy diff --git a/src/lib.rs b/src/lib.rs index 2cabf79..8d2cad0 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -3,12 +3,55 @@ #![allow(clippy::new_without_default)] #![deny(unsafe_op_in_unsafe_fn)] -//! Interoperability library for Rust Windowing applications. +//! # Interoperability helper between graphics crates //! -//! This library provides standard types for accessing a window's platform-specific raw window -//! handle and platforms display handle. This does not provide any utilities for creating and -//! managing windows; instead, it provides a common interface that window creation libraries (e.g. -//! Winit, SDL) can use to easily talk with graphics libraries (e.g. gfx-hal). +//! This crate is intended as an interoperability crate, that allows "producer" crates to create a +//! handle to a window surface, and for this handle to be passed onwards to "consumer" crates for +//! rendering to that surface. +//! +//! This crate does not by itself provide any utilities for creating and managing windows, nor for +//! rendering into them. +//! +//! ## Producers +//! +//! Producer crates provide some sort of "window" type that implements [`HasWindowHandle`], and +//! ensures that the [`WindowHandle`] returned from that is alive for as long as the window is. The +//! primary example of this is [`winit`](https://docs.rs/winit/), consider that the "reference +//! implementation" of a producer crate. +//! +//! Other cross-platform producer crates include [`sdl3`](https://docs.rs/sdl3/), +//! [`sdl2`](https://docs.rs/sdl2/), [`minifb`](https://docs.rs/minifb/), +//! [`glfw`](https://docs.rs/glfw/) and [`fltk`](https://docs.rs/fltk/). +//! +//! Some platform-specific toolkits might also decide to implement `HasWindowHandle` for their +//! types to allow more easily using them with consumer crates. Examples of this include `x11rb`, +//! `ndk`, `orbclient` and `wayland-backend`. +//! +//! ## Consumers +//! +//! Consumer crates expose some sort of "surface" type that renders into a provided window handle. +//! +//! In general, consumer crates must either be generic over the handle type, or contain a lifetime +//! to it, because on some platforms (Wayland, GBM, maybe more?) that is the only way to ensure that +//! the handle is not deallocated while in use by the surface. +//! ``` +//! struct Surface { +//! handle: W, +//! } +//! ``` +//! +//! Examples of consumer crates include [`softbuffer`](https://docs.rs/softbuffer/), +//! [`glutin`](https://docs.rs/glutin/) and [`wgpu`](https://docs.rs/wgpu/), consider these +//! "reference implementations" of consumer crates. Other examples include +//! [`ash-window`](https://docs.rs/ash-window/) and [`pixels`](https://docs.rs/pixels/). +//! +//! Another type of producer is those that use the window handle to access either the platform +//! widget/view or the actual window, and performs some operation that requires that. Examples of +//! this include [`rfd`](https://docs.rs/rfd/), [`wry`](https://docs.rs/wry/), +//! [`muda`](https://docs.rs/muda/), [`window_clipboard`](https://docs.rs/window_clipboard/), +//! [`ashpd`](https://docs.rs/ashpd/), [`window-vibrancy`](https://docs.rs/window-vibrancy/), +//! [`window-shadows`](https://docs.rs/window-shadows/) and +//! [`native-dialog`](https://docs.rs/native-dialog/). //! //! ## Safety guarantees //! From c446619fd07c111bfc22b0a0b50657b32807fd70 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Sat, 14 Mar 2026 11:46:38 +0100 Subject: [PATCH 02/13] Change title --- Cargo.toml | 2 +- src/lib.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 128b0e8..ce7f79e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ name = "raw-window-handle" version = "0.6.2" authors = ["Osspial "] edition = "2021" -description = "Interoperability helper between graphics crates" +description = "Interoperability types for window handles" license = "MIT OR Apache-2.0 OR Zlib" repository = "https://github.com/rust-windowing/raw-window-handle" keywords = ["windowing"] diff --git a/src/lib.rs b/src/lib.rs index 8d2cad0..5552361 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -3,7 +3,7 @@ #![allow(clippy::new_without_default)] #![deny(unsafe_op_in_unsafe_fn)] -//! # Interoperability helper between graphics crates +//! # Interoperability types for window handles //! //! This crate is intended as an interoperability crate, that allows "producer" crates to create a //! handle to a window surface, and for this handle to be passed onwards to "consumer" crates for From e5fbf6a6302ea3336b8a33b362438c1e27e20bcc Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Sat, 14 Mar 2026 11:50:16 +0100 Subject: [PATCH 03/13] Daxpeddadocs --- src/lib.rs | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 5552361..de7d5b3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -6,8 +6,8 @@ //! # Interoperability types for window handles //! //! This crate is intended as an interoperability crate, that allows "producer" crates to create a -//! handle to a window surface, and for this handle to be passed onwards to "consumer" crates for -//! rendering to that surface. +//! handle to a window, and for this handle to be passed onwards to "consumer" crates for rendering +//! to the window's surface. //! //! This crate does not by itself provide any utilities for creating and managing windows, nor for //! rendering into them. @@ -24,16 +24,18 @@ //! [`glfw`](https://docs.rs/glfw/) and [`fltk`](https://docs.rs/fltk/). //! //! Some platform-specific toolkits might also decide to implement `HasWindowHandle` for their -//! types to allow more easily using them with consumer crates. Examples of this include `x11rb`, -//! `ndk`, `orbclient` and `wayland-backend`. +//! types to allow more easily using them with consumer crates. Examples of this include +//! [`x11rb`](https://docs.rs/x11rb), [`wayland-backend`](https://docs.rs/wayland-backend), +//! [`ndk`](https://docs.rs/ndk) and [`orbclient`](https://docs.rs/orbclient). //! //! ## Consumers //! -//! Consumer crates expose some sort of "surface" type that renders into a provided window handle. +//! Consumer crates typically expose some sort of "surface" type that renders into a provided window +//! handle. //! -//! In general, consumer crates must either be generic over the handle type, or contain a lifetime -//! to it, because on some platforms (Wayland, GBM, maybe more?) that is the only way to ensure that -//! the handle is not deallocated while in use by the surface. +//! These consumer crates must either be generic over the handle type, or contain a lifetime to it, +//! because on some platforms (Wayland, GBM, maybe more?) that is the only way to ensure that the +//! handle is not deallocated while in use by the surface. //! ``` //! struct Surface { //! handle: W, From 11f250183c0e128aee83ea2390699b897ee72ba4 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Sat, 14 Mar 2026 11:51:03 +0100 Subject: [PATCH 04/13] Fix doctest --- src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index de7d5b3..7abfe65 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -37,7 +37,7 @@ //! because on some platforms (Wayland, GBM, maybe more?) that is the only way to ensure that the //! handle is not deallocated while in use by the surface. //! ``` -//! struct Surface { +//! struct Surface { //! handle: W, //! } //! ``` From eadf17fa61dafcdbd7a11205d805ebcc2e1521d8 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Sat, 14 Mar 2026 11:51:38 +0100 Subject: [PATCH 05/13] fix typo --- src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index 7abfe65..cb64a71 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -47,7 +47,7 @@ //! "reference implementations" of consumer crates. Other examples include //! [`ash-window`](https://docs.rs/ash-window/) and [`pixels`](https://docs.rs/pixels/). //! -//! Another type of producer is those that use the window handle to access either the platform +//! Another type of consumer is those that use the window handle to access either the platform //! widget/view or the actual window, and performs some operation that requires that. Examples of //! this include [`rfd`](https://docs.rs/rfd/), [`wry`](https://docs.rs/wry/), //! [`muda`](https://docs.rs/muda/), [`window_clipboard`](https://docs.rs/window_clipboard/), From 997307a3e09c62a6804d309c3359e74598640a16 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Sat, 14 Mar 2026 11:59:15 +0100 Subject: [PATCH 06/13] Make example section a list --- src/lib.rs | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index cb64a71..47e24d2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -19,14 +19,19 @@ //! primary example of this is [`winit`](https://docs.rs/winit/), consider that the "reference //! implementation" of a producer crate. //! -//! Other cross-platform producer crates include [`sdl3`](https://docs.rs/sdl3/), -//! [`sdl2`](https://docs.rs/sdl2/), [`minifb`](https://docs.rs/minifb/), -//! [`glfw`](https://docs.rs/glfw/) and [`fltk`](https://docs.rs/fltk/). +//! Other cross-platform producer crates include: +//! - [`sdl3`](https://docs.rs/sdl3/). +//! - [`sdl2`](https://docs.rs/sdl2/). +//! - [`minifb`](https://docs.rs/minifb/) +//! - [`glfw`](https://docs.rs/glfw/). +//! - [`fltk`](https://docs.rs/fltk/). //! //! Some platform-specific toolkits might also decide to implement `HasWindowHandle` for their -//! types to allow more easily using them with consumer crates. Examples of this include -//! [`x11rb`](https://docs.rs/x11rb), [`wayland-backend`](https://docs.rs/wayland-backend), -//! [`ndk`](https://docs.rs/ndk) and [`orbclient`](https://docs.rs/orbclient). +//! types to allow more easily using them with consumer crates. Examples of this include: +//! - [`x11rb`](https://docs.rs/x11rb). +//! - [`wayland-backend`](https://docs.rs/wayland-backend). +//! - [`ndk`](https://docs.rs/ndk). +//! - [`orbclient`](https://docs.rs/orbclient). //! //! ## Consumers //! @@ -42,18 +47,24 @@ //! } //! ``` //! -//! Examples of consumer crates include [`softbuffer`](https://docs.rs/softbuffer/), -//! [`glutin`](https://docs.rs/glutin/) and [`wgpu`](https://docs.rs/wgpu/), consider these -//! "reference implementations" of consumer crates. Other examples include -//! [`ash-window`](https://docs.rs/ash-window/) and [`pixels`](https://docs.rs/pixels/). +//! Examples of consumer crates include: +//! - [`softbuffer`](https://docs.rs/softbuffer/) (surface for software rendering). +//! - [`glutin`](https://docs.rs/glutin/) (OpenGL surface and context setup). +//! - [`wgpu`](https://docs.rs/wgpu/) (general GPU interface). +//! - [`ash-window`](https://docs.rs/ash-window/) (Vulkan API). +//! - [`pixels`](https://docs.rs/pixels/) (software rendering built upon `wgpu`). //! //! Another type of consumer is those that use the window handle to access either the platform //! widget/view or the actual window, and performs some operation that requires that. Examples of -//! this include [`rfd`](https://docs.rs/rfd/), [`wry`](https://docs.rs/wry/), -//! [`muda`](https://docs.rs/muda/), [`window_clipboard`](https://docs.rs/window_clipboard/), -//! [`ashpd`](https://docs.rs/ashpd/), [`window-vibrancy`](https://docs.rs/window-vibrancy/), -//! [`window-shadows`](https://docs.rs/window-shadows/) and -//! [`native-dialog`](https://docs.rs/native-dialog/). +//! this include: +//! - [`rfd`](https://docs.rs/rfd/) (file dialog). +//! - [`wry`](https://docs.rs/wry/) (webview). +//! - [`muda`](https://docs.rs/muda/) (menubar). +//! - [`window_clipboard`](https://docs.rs/window_clipboard/). +//! - [`ashpd`](https://docs.rs/ashpd/) (XDG portals). +//! - [`window-vibrancy`](https://docs.rs/window-vibrancy/). +//! - [`window-shadows`](https://docs.rs/window-shadows/). +//! - [`native-dialog`](https://docs.rs/native-dialog/). //! //! ## Safety guarantees //! From cce0178c8112e53db434229d99858701b81296cc Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Sat, 14 Mar 2026 12:02:33 +0100 Subject: [PATCH 07/13] include winit in list --- src/lib.rs | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 47e24d2..95d19c3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -15,11 +15,10 @@ //! ## Producers //! //! Producer crates provide some sort of "window" type that implements [`HasWindowHandle`], and -//! ensures that the [`WindowHandle`] returned from that is alive for as long as the window is. The -//! primary example of this is [`winit`](https://docs.rs/winit/), consider that the "reference -//! implementation" of a producer crate. -//! -//! Other cross-platform producer crates include: +//! ensures that the [`WindowHandle`] returned from that is alive for as long as the window is. +//! Examples of cross-platform producer crates include: +//! - [`winit`](https://docs.rs/winit/), consider this the "reference implementation" of a producer +//! crate. //! - [`sdl3`](https://docs.rs/sdl3/). //! - [`sdl2`](https://docs.rs/sdl2/). //! - [`minifb`](https://docs.rs/minifb/) From 7e7428f71079e78ae1ea264d695e0fff45e33b1f Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Sat, 14 Mar 2026 12:02:55 +0100 Subject: [PATCH 08/13] parens --- src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 95d19c3..6a51027 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -17,8 +17,8 @@ //! Producer crates provide some sort of "window" type that implements [`HasWindowHandle`], and //! ensures that the [`WindowHandle`] returned from that is alive for as long as the window is. //! Examples of cross-platform producer crates include: -//! - [`winit`](https://docs.rs/winit/), consider this the "reference implementation" of a producer -//! crate. +//! - [`winit`](https://docs.rs/winit/) (consider this the "reference implementation" of a producer +//! crate). //! - [`sdl3`](https://docs.rs/sdl3/). //! - [`sdl2`](https://docs.rs/sdl2/). //! - [`minifb`](https://docs.rs/minifb/) From a4cbb17c32fdb0c59929ff879c89b52dd8f4c325 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Mon, 16 Mar 2026 05:28:52 +0100 Subject: [PATCH 09/13] Johnits --- src/lib.rs | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 6a51027..124a8ec 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -17,6 +17,7 @@ //! Producer crates provide some sort of "window" type that implements [`HasWindowHandle`], and //! ensures that the [`WindowHandle`] returned from that is alive for as long as the window is. //! Examples of cross-platform producer crates include: +//! //! - [`winit`](https://docs.rs/winit/) (consider this the "reference implementation" of a producer //! crate). //! - [`sdl3`](https://docs.rs/sdl3/). @@ -27,6 +28,7 @@ //! //! Some platform-specific toolkits might also decide to implement `HasWindowHandle` for their //! types to allow more easily using them with consumer crates. Examples of this include: +//! //! - [`x11rb`](https://docs.rs/x11rb). //! - [`wayland-backend`](https://docs.rs/wayland-backend). //! - [`ndk`](https://docs.rs/ndk). @@ -47,15 +49,17 @@ //! ``` //! //! Examples of consumer crates include: +//! //! - [`softbuffer`](https://docs.rs/softbuffer/) (surface for software rendering). //! - [`glutin`](https://docs.rs/glutin/) (OpenGL surface and context setup). //! - [`wgpu`](https://docs.rs/wgpu/) (general GPU interface). //! - [`ash-window`](https://docs.rs/ash-window/) (Vulkan API). //! - [`pixels`](https://docs.rs/pixels/) (software rendering built upon `wgpu`). //! -//! Another type of consumer is those that use the window handle to access either the platform -//! widget/view or the actual window, and performs some operation that requires that. Examples of -//! this include: +//! Another type of consumer includes crates that use the window handle to access either the +//! platform widget/view or the actual window, and performs some operation that requires that. +//! Examples of this pattern include: +//! //! - [`rfd`](https://docs.rs/rfd/) (file dialog). //! - [`wry`](https://docs.rs/wry/) (webview). //! - [`muda`](https://docs.rs/muda/) (menubar). From f6d6682305acc26ffd3fa592ecf1f0adf8e632e4 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Mon, 16 Mar 2026 05:30:24 +0100 Subject: [PATCH 10/13] Qouting Strunk & White like it's nobody's business --- src/lib.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 124a8ec..b109546 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -5,9 +5,9 @@ //! # Interoperability types for window handles //! -//! This crate is intended as an interoperability crate, that allows "producer" crates to create a -//! handle to a window, and for this handle to be passed onwards to "consumer" crates for rendering -//! to the window's surface. +//! This crate is an interoperability interface that allows "producer" crates to create a handle to +//! a window, and for this handle to be passed onwards to "consumer" crates for rendering to the +//! window's surface. //! //! This crate does not by itself provide any utilities for creating and managing windows, nor for //! rendering into them. From fe71bbb92864d59b091575a30ddfcaa5b6d13992 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Mon, 16 Mar 2026 05:41:11 +0100 Subject: [PATCH 11/13] composition vs. lifetime --- src/lib.rs | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index b109546..6f16127 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -39,13 +39,21 @@ //! Consumer crates typically expose some sort of "surface" type that renders into a provided window //! handle. //! -//! These consumer crates must either be generic over the handle type, or contain a lifetime to it, -//! because on some platforms (Wayland, GBM, maybe more?) that is the only way to ensure that the -//! handle is not deallocated while in use by the surface. +//! These consumer crates must either be generic over the handle type, or contain a lifetime to the +//! handle, because on some platforms (in particular Wayland) that is the only way to ensure that +//! the handle is not deallocated while in use by the surface. //! ``` +//! // Composition: //! struct Surface { //! handle: W, //! } +//! +//! // OR +//! +//! // Lifetime: +//! struct Surface<'w> { +//! handle: raw_window_handle::WindowHandle<'w>, +//! } //! ``` //! //! Examples of consumer crates include: From 35c789e083ad781c842d94f66a0cabe3ee4af2af Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Mon, 16 Mar 2026 05:44:11 +0100 Subject: [PATCH 12/13] fix building --- src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 6f16127..befd8f9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -47,9 +47,9 @@ //! struct Surface { //! handle: W, //! } +//! ``` //! -//! // OR -//! +//! ``` //! // Lifetime: //! struct Surface<'w> { //! handle: raw_window_handle::WindowHandle<'w>, From 8f3a41dd36a026b50dc54bcca081bc520518916c Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Tue, 24 Mar 2026 16:21:26 +0100 Subject: [PATCH 13/13] MxN problem --- src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index befd8f9..78514aa 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -7,7 +7,8 @@ //! //! This crate is an interoperability interface that allows "producer" crates to create a handle to //! a window, and for this handle to be passed onwards to "consumer" crates for rendering to the -//! window's surface. +//! window's surface. This solves the MxN integration problem: consumer and producer crates don't +//! have to know about / depend on each other. //! //! This crate does not by itself provide any utilities for creating and managing windows, nor for //! rendering into them.