From 849b8f5dce4d3f93b251259f5323ea9fd43e0c05 Mon Sep 17 00:00:00 2001 From: Benjamin Saunders Date: Sun, 19 Apr 2020 14:09:08 -0700 Subject: [PATCH] Clarify when RedrawRequested is useful (#1529) Co-Authored-By: Osspial --- src/event.rs | 10 +++++++--- src/lib.rs | 10 +++++++--- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/src/event.rs b/src/event.rs index 4756f3d8..6b9fe1a6 100644 --- a/src/event.rs +++ b/src/event.rs @@ -81,10 +81,11 @@ pub enum Event<'a, T: 'static> { /// /// This event is useful as a place to put your code that should be run after all /// state-changing events have been handled and you want to do stuff (updating state, performing - /// calculations, etc) that happens as the "main body" of your event loop. If your program draws - /// graphics, it's usually better to do it in response to + /// calculations, etc) that happens as the "main body" of your event loop. If your program only draws + /// graphics when something changes, it's usually better to do it in response to /// [`Event::RedrawRequested`](crate::event::Event::RedrawRequested), which gets emitted - /// immediately after this event. + /// immediately after this event. Programs that draw graphics continuously, like most games, + /// can render here unconditionally for simplicity. MainEventsCleared, /// Emitted after `MainEventsCleared` when a window should be redrawn. @@ -97,6 +98,9 @@ pub enum Event<'a, T: 'static> { /// /// During each iteration of the event loop, Winit will aggregate duplicate redraw requests /// into a single event, to help avoid duplicating rendering work. + /// + /// Mainly of interest to applications with mostly-static graphics that avoid redrawing unless + /// something changes, like most non-game GUIs. RedrawRequested(WindowId), /// Emitted after all `RedrawRequested` events have been processed and control flow is about to diff --git a/src/lib.rs b/src/lib.rs index cf43f396..e3b0be75 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -73,14 +73,18 @@ //! // Application update code. //! //! // Queue a RedrawRequested event. +//! // +//! // You only need to call this if you've determined that you need to redraw, in +//! // applications which do not always need to. Applications that redraw continuously +//! // can just render here instead. //! window.request_redraw(); //! }, //! Event::RedrawRequested(_) => { //! // Redraw the application. //! // -//! // It's preferrable to render in this event rather than in MainEventsCleared, since -//! // rendering in here allows the program to gracefully handle redraws requested -//! // by the OS. +//! // It's preferable for applications that do not render continuously to render in +//! // this event rather than in MainEventsCleared, since rendering in here allows +//! // the program to gracefully handle redraws requested by the OS. //! }, //! _ => () //! }