Enum nannou::app::LoopMode

pub enum LoopMode {
    Rate {
        update_interval: Duration,
    },
    Wait {
        updates_following_event: usize,
        update_interval: Duration,
    },
    RefreshSync {
        minimum_update_interval: Duration,
        windows: Option<HashSet<Id>>,
    },
}

The mode in which the App is currently running the event loop and emitting Update events.

Variants

Rate

Specifies that the application is continuously looping at a consistent rate.

An application running in the Rate loop mode will behave as follows:

1. Poll for and collect all pending user input. event is then called with all application events that have occurred.

2. event is called with an Update event.

3. Check the time and sleep for the remainder of the update_interval then go to 1.

view is called at an arbitraty rate by the vulkan swapchain for each window. It uses whatever the state of the user's model happens to be at that moment in time.

Fields of Rate

update_interval: Duration

The minimum interval between emitted updates.

Wait

Waits for user input events to occur before calling event with an Update event.

This is particularly useful for low-energy GUIs that only need to update when some sort of input has occurred. The benefit of using this mode is that you don't waste CPU cycles looping or updating when you know nothing is changing in your model or view.

Fields of Wait

updates_following_event: usize

The number of updates (and in turn view calls per window) that should occur since the application last received a non-Update event.

update_interval: Duration

The minimum interval between emitted updates.

RefreshSync

Synchronises Update events with requests for a new image by the swapchain for each window in order to achieve minimal latency between the state of the model and what is displayed on screen. This mode should be particularly useful for interactive applications and games where minimal latency between user input and the display image is essential.

The result of using this loop mode is similar to using vsync in traditional applications. E.g. if you have one window running on a monitor with a 60hz refresh rate, your update will get called at a fairly consistent interval that is close to 60 times per second.

It is worth noting that, in the case that you have more than one window and they are situated on different displays with different refresh rates, update will almost certainly not be called at a consistent interval. Instead, it will be called as often as necessary - if it has been longer than minimum_update_interval or if some user input was received since the last Update. That said, each Update event contains the duration since the last Update occurred, so as long as all time-based state (like animations or physics simulations) are driven by this, the update interval consistency should not cause issues.

The Swapchain

The purpose of the swapchain for each window is to synchronise the presentation of images (calls to view in nannou) with the refresh rate of the screen. You can learn more about the swap chain here.

Fields of RefreshSync

minimum_update_interval: Duration

The minimum duration that must occur between calls to update. Under the RefreshSync mode, the application loop will attempt to emit an Update event once every time a new image is acquired from a window's swapchain. Thus, this value is very useful when working with multiple windows in order to avoid updating at an unnecessarily high rate.

We recommend using a Duration that is roughly half the duration between refreshes of the window on the display with the highest refresh rate. For example, if the highest display refresh rate is 60hz (with an interval of ~16ms) a suitable minimum_update_interval might be 8ms. This should result in update being called once every 16ms regardless of the number of windows.

windows: Option<HashSet<Id>>

The windows to which Update events should be synchronised.

If this is Some, an Update will only occur for those windows that are contained within this set. This is particularly useful if you only want to synchronise your updates with one or more "main" windows and you don't mind so much about the latency for the rest.

If this is None (the default case), Update events will be synchronised with all windows.

Methods

impl LoopMode

pub const DEFAULT_RATE_FPS: f64

pub const DEFAULT_UPDATES_FOLLOWING_EVENT: usize

pub fn rate_fps(fps: f64) -> Self

Specify the Rate mode with the given frames-per-second.

pub fn wait(updates_following_event: usize) -> Self

Specify the Wait mode with the given number of updates following each non-Update event.

Uses the default update interval.

pub fn wait_with_max_fps(updates_following_event: usize, max_fps: f64) -> Self

Specify the Wait mode with the given number of updates following each non-Update event.

Waits long enough to ensure loop iteration never occurs faster than the given max_fps.

pub fn wait_with_interval(
    updates_following_event: usize,
    update_interval: Duration
) -> Self

Specify the Wait mode with the given number of updates following each non-Update event.

Waits long enough to ensure loop iteration never occurs faster than the given max_fps.

pub fn refresh_sync() -> Self

A simplified constructor for the default RefreshSync loop mode.

Assumes a display refresh rate of ~60hz and in turn specifies a minimum_update_latency of ~8.33ms. The windows field is set to None.

Trait Implementations

impl PartialEq<LoopMode> for LoopMode

fn eq(&self, other: &LoopMode) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &LoopMode) -> bool

This method tests for !=.

impl Clone for LoopMode

fn clone(&self) -> LoopMode

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for LoopMode

fn default() -> Self

Returns the "default value" for a type.

impl Debug for LoopMode

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.