diff --git a/crates/bevy_winit/src/accessibility.rs b/crates/bevy_winit/src/accessibility.rs index 68eff9b21462e..4bda4319a5784 100644 --- a/crates/bevy_winit/src/accessibility.rs +++ b/crates/bevy_winit/src/accessibility.rs @@ -1,3 +1,5 @@ +//! Helpers for mapping window entities to accessibility types + use std::{ collections::VecDeque, sync::{atomic::Ordering, Arc, Mutex}, diff --git a/crates/bevy_winit/src/lib.rs b/crates/bevy_winit/src/lib.rs index caf74d3eeb0d8..dec1a9076be24 100644 --- a/crates/bevy_winit/src/lib.rs +++ b/crates/bevy_winit/src/lib.rs @@ -1,3 +1,11 @@ +#![warn(missing_docs)] +//! `bevy_winit` provides utilities to handle window creation and the eventloop through [`winit`] +//! +//! Most commonly, the [`WinitPlugin`] is used as part of +//! [`DefaultPlugins`](https://docs.rs/bevy/latest/bevy/struct.DefaultPlugins.html). +//! The app's [runner](bevy_app::App::runner) is set by `WinitPlugin` and handles the `winit` [`EventLoop`](winit::event_loop::EventLoop). +//! See `winit_runner` for details. + pub mod accessibility; mod converters; mod system; @@ -49,6 +57,7 @@ use crate::web_resize::{CanvasParentResizeEventChannel, CanvasParentResizePlugin #[cfg(target_os = "android")] pub static ANDROID_APP: once_cell::sync::OnceCell = once_cell::sync::OnceCell::new(); +/// A [`Plugin`] that utilizes [`winit`] for window creation and event loop management. #[derive(Default)] pub struct WinitPlugin; @@ -270,6 +279,9 @@ impl Default for WinitPersistentState { } } +/// The default [`App::runner`] for the [`WinitPlugin`] plugin. +/// +/// Overriding the app's [runner](bevy_app::App::runner) while using `WinitPlugin` will bypass the `EventLoop`. pub fn winit_runner(mut app: App) { // We remove this so that we have ownership over it. let mut event_loop = app diff --git a/crates/bevy_winit/src/winit_config.rs b/crates/bevy_winit/src/winit_config.rs index 40bfd1f87323b..d5627c4b2225b 100644 --- a/crates/bevy_winit/src/winit_config.rs +++ b/crates/bevy_winit/src/winit_config.rs @@ -1,7 +1,7 @@ use bevy_ecs::system::Resource; use bevy_utils::Duration; -/// A resource for configuring usage of the `rust_winit` library. +/// A resource for configuring usage of the [`winit`] library. #[derive(Debug, Resource)] pub struct WinitSettings { /// Configures `winit` to return control to the caller after exiting the diff --git a/crates/bevy_winit/src/winit_windows.rs b/crates/bevy_winit/src/winit_windows.rs index b87678acd3d8d..6bc5995490714 100644 --- a/crates/bevy_winit/src/winit_windows.rs +++ b/crates/bevy_winit/src/winit_windows.rs @@ -1,3 +1,4 @@ +#![warn(missing_docs)] use std::sync::atomic::Ordering; use accesskit_winit::Adapter; @@ -20,11 +21,16 @@ use crate::{ converters::convert_window_level, }; +/// A resource which maps window entities to [`winit`] library windows. #[derive(Debug, Default)] pub struct WinitWindows { + /// Stores [`winit`] windows by window identifier. pub windows: HashMap, + /// Maps entities to `winit` window identifiers. pub entity_to_winit: HashMap, + /// Maps `winit` window identifiers to entities. pub winit_to_entity: HashMap, + // Some winit functions, such as `set_window_icon` can only be used from the main thread. If // they are used in another thread, the app will hang. This marker ensures `WinitWindows` is // only ever accessed with bevy's non-send functions and in NonSend systems. @@ -32,6 +38,7 @@ pub struct WinitWindows { } impl WinitWindows { + /// Creates a `winit` window and associates it with our entity. pub fn create_window( &mut self, event_loop: &winit::event_loop::EventLoopWindowTarget<()>, @@ -227,6 +234,9 @@ impl WinitWindows { } } +/// Gets the "best" video mode which fits the given dimensions. +/// +/// The heuristic for "best" prioritizes width, height, and refresh rate in that order. pub fn get_fitting_videomode( monitor: &winit::monitor::MonitorHandle, width: u32, @@ -259,6 +269,9 @@ pub fn get_fitting_videomode( modes.first().unwrap().clone() } +/// Gets the "best" videomode from a monitor. +/// +/// The heuristic for "best" prioritizes width, height, and refresh rate in that order. pub fn get_best_videomode(monitor: &winit::monitor::MonitorHandle) -> winit::monitor::VideoMode { let mut modes = monitor.video_modes().collect::>(); modes.sort_by(|a, b| { @@ -300,6 +313,7 @@ pub(crate) fn attempt_grab(winit_window: &winit::window::Window, grab_mode: Curs } } +/// Compute the physical window position for a given [`WindowPosition`]. // Ideally we could generify this across window backends, but we only really have winit atm // so whatever. pub fn winit_window_position(