[Merged by Bors] - Reduce power usage with configurable event loop

Cargo.toml

@@ -98,7 +98,9 @@ bevy_dylib = { path = "crates/bevy_dylib", version = "0.6.0", default-features =
 bevy_internal = { path = "crates/bevy_internal", version = "0.6.0", default-features = false }
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
-bevy_internal = { path = "crates/bevy_internal", version = "0.6.0", default-features = false, features = ["webgl"] }
+bevy_internal = { path = "crates/bevy_internal", version = "0.6.0", default-features = false, features = [
+  "webgl",
+] }
 
 [dev-dependencies]
 anyhow = "1.0.4"
@@ -522,6 +524,10 @@ path = "examples/ui/ui.rs"
 name = "clear_color"
 path = "examples/window/clear_color.rs"
 
+[[example]]
+name = "low_power"
+path = "examples/window/low_power.rs"
+
 [[example]]
 name = "multiple_windows"
 path = "examples/window/multiple_windows.rs"

crates/bevy_window/src/event.rs

@@ -20,6 +20,11 @@ pub struct CreateWindow {
     pub descriptor: WindowDescriptor,
 }
 
+/// An event that indicates the window should redraw, even if its control flow is set to `Wait` and
+/// there have been no window events.
+#[derive(Debug, Clone)]
+pub struct RequestRedraw;
+
 /// An event that indicates a window should be closed.
 #[derive(Debug, Clone)]
 pub struct CloseWindow {

crates/bevy_window/src/lib.rs

@@ -43,6 +43,7 @@ impl Plugin for WindowPlugin {
             .add_event::<CreateWindow>()
             .add_event::<WindowCreated>()
             .add_event::<WindowCloseRequested>()
+            .add_event::<RequestRedraw>()
             .add_event::<CloseWindow>()
             .add_event::<CursorMoved>()
             .add_event::<CursorEntered>()

crates/bevy_winit/src/lib.rs

@@ -17,15 +17,18 @@ use bevy_ecs::{
     world::World,
 };
 use bevy_math::{ivec2, DVec2, Vec2};
-use bevy_utils::tracing::{error, trace, warn};
+use bevy_utils::{
+    tracing::{error, trace, warn},
+    Instant,
+};
 use bevy_window::{
     CreateWindow, CursorEntered, CursorLeft, CursorMoved, FileDragAndDrop, ReceivedCharacter,
-    WindowBackendScaleFactorChanged, WindowCloseRequested, WindowCreated, WindowFocused,
-    WindowMoved, WindowResized, WindowScaleFactorChanged, Windows,
+    RequestRedraw, WindowBackendScaleFactorChanged, WindowCloseRequested, WindowCreated,
+    WindowFocused, WindowMoved, WindowResized, WindowScaleFactorChanged, Windows,
 };
 use winit::{
     dpi::PhysicalPosition,
-    event::{self, DeviceEvent, Event, WindowEvent},
+    event::{self, DeviceEvent, Event, StartCause, WindowEvent},
     event_loop::{ControlFlow, EventLoop, EventLoopWindowTarget},
 };
 
@@ -37,6 +40,7 @@ pub struct WinitPlugin;
 impl Plugin for WinitPlugin {
     fn build(&self, app: &mut App) {
         app.init_non_send_resource::<WinitWindows>()
+            .init_resource::<WinitSettings>()
             .set_runner(winit_runner)
             .add_system_to_stage(CoreStage::PostUpdate, change_window.exclusive_system());
         let event_loop = EventLoop::new();
@@ -227,41 +231,71 @@ pub fn winit_runner(app: App) {
 //     winit_runner_with(app, EventLoop::new_any_thread());
 // }
 
+/// Stores state that must persist between frames.
+struct WinitPersistentState {
+    /// Tracks whether or not the application is active or suspended.
+    active: bool,
+    /// Tracks whether or not an event has occurred this frame that would trigger an update in low
+    /// power mode. Should be reset at the end of every frame.
+    low_power_event: bool,
+    /// Tracks whether the event loop was started this frame because of a redraw request.
+    redraw_request_sent: bool,
+    /// Tracks if the event loop was started this frame because of a `WaitUntil` timeout.
+    timeout_reached: bool,
+    last_update: Instant,
+}
+impl Default for WinitPersistentState {
+    fn default() -> Self {
+        Self {
+            active: true,
+            low_power_event: false,
+            redraw_request_sent: false,
+            timeout_reached: false,
+            last_update: Instant::now(),
+        }
+    }
+}
+
 pub fn winit_runner_with(mut app: App) {
     let mut event_loop = app
         .world
         .remove_non_send_resource::<EventLoop<()>>()
         .unwrap();
     let mut create_window_event_reader = ManualEventReader::<CreateWindow>::default();
     let mut app_exit_event_reader = ManualEventReader::<AppExit>::default();
+    let mut redraw_event_reader = ManualEventReader::<RequestRedraw>::default();
+    let mut winit_state = WinitPersistentState::default();
     app.world
         .insert_non_send_resource(event_loop.create_proxy());
 
+    let return_from_run = app.world.resource::<WinitSettings>().return_from_run;
     trace!("Entering winit event loop");
 
-    let should_return_from_run = app
-        .world
-        .get_resource::<WinitConfig>()
-        .map_or(false, |config| config.return_from_run);
-
-    let mut active = true;
-
     let event_handler = move |event: Event<()>,
                               event_loop: &EventLoopWindowTarget<()>,
                               control_flow: &mut ControlFlow| {
-        *control_flow = ControlFlow::Poll;
-
-        if let Some(app_exit_events) = app.world.get_resource_mut::<Events<AppExit>>() {
-            if app_exit_event_reader
-                .iter(&app_exit_events)
-                .next_back()
-                .is_some()
-            {
-                *control_flow = ControlFlow::Exit;
-            }
-        }
-
         match event {
+            event::Event::NewEvents(start) => {
+                let winit_config = app.world.resource::<WinitSettings>();
+                let windows = app.world.resource::<Windows>();
+                let focused = windows.iter().any(|w| w.is_focused());
+                // Check if either the `WaitUntil` timeout was triggered by winit, or that same
+                // amount of time has elapsed since the last app update. This manual check is needed
+                // because we don't know if the criteria for an app update were met until the end of
+                // the frame.
+                let auto_timeout_reached = matches!(start, StartCause::ResumeTimeReached { .. });
+                let now = Instant::now();
+                let manual_timeout_reached = match winit_config.update_mode(focused) {
+                    UpdateMode::Continuous => false,
+                    UpdateMode::Reactive { max_wait }
+                    | UpdateMode::ReactiveLowPower { max_wait } => {
+                        now.duration_since(winit_state.last_update) >= *max_wait
+                    }
+                };
+                // The low_power_event state and timeout must be reset at the start of every frame.
+                winit_state.low_power_event = false;
+                winit_state.timeout_reached = auto_timeout_reached || manual_timeout_reached;
+            }
             event::Event::WindowEvent {
                 event,
                 window_id: winit_window_id,
@@ -287,6 +321,7 @@ pub fn winit_runner_with(mut app: App) {
                     warn!("Skipped event for unknown Window Id {:?}", winit_window_id);
                     return;
                 };
+                winit_state.low_power_event = true;
 
                 match event {
                     WindowEvent::Resized(size) => {
@@ -497,25 +532,73 @@ pub fn winit_runner_with(mut app: App) {
                 });
             }
             event::Event::Suspended => {
-                active = false;
+                winit_state.active = false;
             }
             event::Event::Resumed => {
-                active = true;
+                winit_state.active = true;
             }
             event::Event::MainEventsCleared => {
                 handle_create_window_events(
                     &mut app.world,
                     event_loop,
                     &mut create_window_event_reader,
                 );
-                if active {
+                let winit_config = app.world.resource::<WinitSettings>();
+                let update = if winit_state.active {
+                    let windows = app.world.resource::<Windows>();
+                    let focused = windows.iter().any(|w| w.is_focused());
+                    match winit_config.update_mode(focused) {
+                        UpdateMode::Continuous | UpdateMode::Reactive { .. } => true,
+                        UpdateMode::ReactiveLowPower { .. } => {
+                            winit_state.low_power_event
+                                || winit_state.redraw_request_sent
+                                || winit_state.timeout_reached
+                        }
+                    }
+                } else {
+                    false
+                };
+                if update {
+                    winit_state.last_update = Instant::now();
                     app.update();
                 }
             }
+            Event::RedrawEventsCleared => {
+                {
+                    let winit_config = app.world.resource::<WinitSettings>();
+                    let windows = app.world.resource::<Windows>();
+                    let focused = windows.iter().any(|w| w.is_focused());
+                    let now = Instant::now();
+                    use UpdateMode::*;
+                    *control_flow = match winit_config.update_mode(focused) {
+                        Continuous => ControlFlow::Poll,
+                        Reactive { max_wait } | ReactiveLowPower { max_wait } => {
+                            ControlFlow::WaitUntil(now + *max_wait)
+                        }
+                    };
+                }
+                // This block needs to run after `app.update()` in `MainEventsCleared`. Otherwise,
+                // we won't be able to see redraw requests until the next event, defeating the
+                // purpose of a redraw request!
+                let mut redraw = false;
+                if let Some(app_redraw_events) = app.world.get_resource::<Events<RequestRedraw>>() {
+                    if redraw_event_reader.iter(app_redraw_events).last().is_some() {
+                        *control_flow = ControlFlow::Poll;
+                        redraw = true;
+                    }
+                }
+                if let Some(app_exit_events) = app.world.get_resource::<Events<AppExit>>() {
+                    if app_exit_event_reader.iter(app_exit_events).last().is_some() {
+                        *control_flow = ControlFlow::Exit;
+                    }
+                }
+                winit_state.redraw_request_sent = redraw;
+            }
             _ => (),
         }
     };
-    if should_return_from_run {
+
+    if return_from_run {
         run_return(&mut event_loop, event_handler);
     } else {
         run(event_loop, event_handler);

crates/bevy_winit/src/winit_config.rs

@@ -1,15 +1,89 @@
+use bevy_utils::Duration;
+
 /// A resource for configuring usage of the `rust_winit` library.
-#[derive(Debug, Default)]
-pub struct WinitConfig {
-    /// Configures the winit library to return control to the main thread after
-    /// the [run](bevy_app::App::run) loop is exited. Winit strongly recommends
-    /// avoiding this when possible. Before using this please read and understand
-    /// the [caveats](winit::platform::run_return::EventLoopExtRunReturn::run_return)
-    /// in the winit documentation.
-    ///
-    /// This feature is only available on desktop `target_os` configurations.
-    /// Namely `windows`, `macos`, `linux`, `dragonfly`, `freebsd`, `netbsd`, and
-    /// `openbsd`. If set to true on an unsupported platform
-    /// [run](bevy_app::App::run) will panic.
+#[derive(Debug)]
+pub struct WinitSettings {
+    /// Configures the winit library to return control to the main thread after the
+    /// [run](bevy_app::App::run) loop is exited. Winit strongly recommends avoiding this when
+    /// possible. Before using this please read and understand the
+    /// [caveats](winit::platform::run_return::EventLoopExtRunReturn::run_return) in the winit
+    /// documentation.
+    ///
+    /// This feature is only available on desktop `target_os` configurations. Namely `windows`,
+    /// `macos`, `linux`, `dragonfly`, `freebsd`, `netbsd`, and `openbsd`. If set to true on an
+    /// unsupported platform [run](bevy_app::App::run) will panic.
     pub return_from_run: bool,
+    /// Configures how the winit event loop updates while the window is focused.
+    pub focused_mode: UpdateMode,
+    /// Configures how the winit event loop updates while the window is *not* focused.
+    pub unfocused_mode: UpdateMode,
+}
+impl WinitSettings {
+    /// Configure winit with common settings for a game.
+    pub fn game() -> Self {
+        WinitSettings::default()
+    }
+
+    /// Configure winit with common settings for a desktop application.
+    pub fn desktop_app() -> Self {
+        WinitSettings {
+            focused_mode: UpdateMode::Reactive {
+                max_wait: Duration::from_secs(5),
+            },
+            unfocused_mode: UpdateMode::ReactiveLowPower {
+                max_wait: Duration::from_secs(60),
+            },
+            ..Default::default()
+        }
+    }
+
+    /// Gets the configured `UpdateMode` depending on whether the window is focused or not
+    pub fn update_mode(&self, focused: bool) -> &UpdateMode {
+        match focused {
+            true => &self.focused_mode,
+            false => &self.unfocused_mode,
+        }
+    }
+}
+impl Default for WinitSettings {
+    fn default() -> Self {
+        WinitSettings {
+            return_from_run: false,
+            focused_mode: UpdateMode::Continuous,
+            unfocused_mode: UpdateMode::Continuous,
+        }
+    }
+}
+
+/// Configure how the winit event loop should update.
+#[derive(Debug)]
+pub enum UpdateMode {
+    /// The event loop will update continuously, running as fast as possible.
+    Continuous,
+    /// The event loop will only update if there is a winit event, a redraw is requested, or the
+    /// maximum wait time has elapsed.
+    ///
+    /// ## Note
+    ///
+    /// Once the app has executed all bevy systems and reaches the end of the event loop, there is
+    /// no way to force the app to wake and update again, unless a `winit` event (such as user
+    /// input, or the window being resized) is received or the time limit is reached.
+    Reactive { max_wait: Duration },
+    /// The event loop will only update if there is a winit event from direct interaction with the
+    /// window (e.g. mouseover), a redraw is requested, or the maximum wait time has elapsed.
+    ///
+    /// ## Note
+    ///
+    /// Once the app has executed all bevy systems and reaches the end of the event loop, there is
+    /// no way to force the app to wake and update again, unless a `winit` event (such as user
+    /// input, or the window being resized) is received or the time limit is reached.
+    ///
+    /// ## Differences from [`UpdateMode::Reactive`]
+    ///
+    /// Unlike [`UpdateMode::Reactive`], this mode will ignore winit events that aren't directly
+    /// caused by interaction with the window. For example, you might want to use this mode when the
+    /// window is not focused, to only re-draw your bevy app when the cursor is over the window, but
+    /// not when the mouse moves somewhere else on the screen. This helps to significantly reduce
+    /// power consumption by only updated the app when absolutely necessary.
+    ReactiveLowPower { max_wait: Duration },
 }

examples/README.md

@@ -261,6 +261,7 @@ Example | File | Description
 Example | File | Description
 --- | --- | ---
 `clear_color` | [`window/clear_color.rs`](./window/clear_color.rs) | Creates a solid color window
+`low_power` | [`window/low_power.rs`](./window/low_power.rs) | Demonstrates settings to reduce power use for bevy applications
 `multiple_windows` | [`window/multiple_windows.rs`](./window/multiple_windows.rs) | Demonstrates creating multiple windows, and rendering to them
 `scale_factor_override` | [`window/scale_factor_override.rs`](./window/scale_factor_override.rs) | Illustrates how to customize the default window settings
 `transparent_window` | [`window/transparent_window.rs`](./window/transparent_window.rs) | Illustrates making the window transparent and hiding the window decoration

examples/app/return_after_run.rs

@@ -1,19 +1,21 @@
-use bevy::{prelude::*, winit::WinitConfig};
+use bevy::{prelude::*, winit::WinitSettings};
 
 fn main() {
     println!("Running first App.");
     App::new()
-        .insert_resource(WinitConfig {
+        .insert_resource(WinitSettings {
             return_from_run: true,
+            ..default()
         })
         .insert_resource(ClearColor(Color::rgb(0.2, 0.2, 0.8)))
         .add_plugins(DefaultPlugins)
         .add_system(system1)
         .run();
     println!("Running another App.");
     App::new()
-        .insert_resource(WinitConfig {
+        .insert_resource(WinitSettings {
             return_from_run: true,
+            ..default()
         })
         .insert_resource(ClearColor(Color::rgb(0.2, 0.8, 0.2)))
         .add_plugins_with(DefaultPlugins, |group| {