Conversation
madsmtm
force-pushed
the
madsmtm/docs-consumer-producer
branch
from
9d940c6 to
0afced4
Compare
madsmtm
force-pushed
the
madsmtm/docs-consumer-producer
branch
from
0afced4 to
bf19e5d
Compare
| //! 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/). |
There was a problem hiding this comment.
Question: what here makes the difference between the crates before "consider these reference implementations" and after? Maybe the is useful to communicate to the user?
There was a problem hiding this comment.
In my mind, it's that I will actively go and fix the rwh integration for these crates. But yeah, we could make this clearer, and maybe it makes sense to remove wgpu from the list (since we don't actually control that crate).
There was a problem hiding this comment.
I do PR to wgpu from time to time (specifically WRT windowing / surface handles), but it's so humongous (and has an insane amount of insultingly low-quality PR contributions, I feel sorry for the maintainers) that it's almost impossible to get back into it every time, for example once one of the maintainers finally comes around to re-review my PR (because of otherwise having to deal with noise...).
ash-window is my area fwiw, but it can't do much if anything for lifetimes after handing out a cheaply-copyable VkSurfaceKHR handle; unless we re-wrap it in a smarter type that sparingly hands it out.
| //! 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/). |
There was a problem hiding this comment.
These are consumers, right? They take a RWH to interface with the OS for non-graphics like clipboard access, popup dialogs and whatnot (perhaps mention what these crates do in brief, as it's not always clear from the crate name).
| //! 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/). | |
| //! 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/). |
| #![deny(unsafe_op_in_unsafe_fn)] | ||
|
|
||
| //! Interoperability library for Rust Windowing applications. | ||
| //! # Interoperability helper between graphics crates |
There was a problem hiding this comment.
I believe the new title is actually less accurate than the previous one.
What we offer here is interoperability between windowing and graphic libraries.
Potentially we also help multiple graphics libraries communicate a window between each other, but that's not really the main use case.
| //! # Interoperability helper between graphics crates | |
| //! # Interoperability Types For Window Handles |
I believe in general we should not frame everything around graphics and surfaces. As you already point out somewhere else in the documentation, there are also consumers that just work with the window directly.
| //! 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 |
There was a problem hiding this comment.
I know we discussed offering that. But right now we are still providing window handles, not surface handles.
| //! types to allow more easily using them with consumer crates. Examples of this include `x11rb`, | ||
| //! `ndk`, `orbclient` and `wayland-backend`. |
There was a problem hiding this comment.
| //! 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), | |
| //! [`ndk`](https://docs.rs/ndk), [`orbclient`](https://docs.rs/orbclient) and [`wayland-backend`](https://docs.rs/wayland-backend). |
| //! | ||
| //! ## Consumers | ||
| //! | ||
| //! Consumer crates expose some sort of "surface" type that renders into a provided window handle. |
There was a problem hiding this comment.
I believe that in general we should reframe this as just an example of what a consumer crate might do. You already point out further down that there are consumers who just work with the window directly.
| //! 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. |
3 participants
Part of #193.