Struct nannou::app::Builder

pub struct Builder<M = (), E = Event> { /* private fields */ }

A nannou App builder.

Implementations

impl<M> Builder<M, Event>

where M: 'static,

pub const DEFAULT_BACKENDS: Backends = wgpu::DEFAULT_BACKENDS

The default set of backends requested.

pub fn new(model: ModelFn<M>) -> Self

Begin building the App.

The model argument is the function that the App will call to initialise your Model.

The Model can be thought of as the state that you would like to track throughout the lifetime of your nannou program from start to exit.

The given function is called before any event processing begins within the application.

The Model that is returned by the function is the same model that will be passed to the given event and view functions.

pub fn new_async( model: impl FnOnce(&App) -> Box<dyn Future<Output = M> + '_> + 'static ) -> Self

pub fn event<E>(self, event: EventFn<M, E>) -> Builder<M, E>

where E: LoopEvent,

The function that the app will call to allow you to update your Model on events.

The event function allows you to expect any event type that implements LoopEvent, however nannou also provides a default Event type that should cover most use cases. This event type is an enum that describes all the different kinds of I/O events that might occur during the life of the program. These include things like Updates and WindowEvents such as KeyPressed, MouseMoved, and so on.

impl<M, E> Builder<M, E>

where M: 'static, E: LoopEvent,

pub const DEFAULT_CAPTURE_FRAME_TIMEOUT: Duration = _

By default, we timeout if waiting for a frame capture job takes longer than 5 seconds. This is to avoid hanging forever in the case the frame writing process encounters an unrecoverable error.

pub fn view(self, view: ViewFn<M>) -> Self

The default view function that the app will call to allow you to present your Model to the surface of a window on your display.

This function will be used in the case that a window-specific view function has not been provided, e.g. via window::Builder::view or window::Builder::sketch.

Note that when working with more than one window, you can use frame.window_id() to determine which window the current call is associated with.

pub fn update(self, update: UpdateFn<M>) -> Self

A function for updating the model within the application loop.

See the LoopMode documentation for more information about the different kinds of application loop modes available in nannou and how they behave.

Update events are also emitted as a variant of the event function. Note that if you specify both an event function and an update function, the event function will always be called with an update event prior to this update function.

pub fn simple_window(self, view: ViewFn<M>) -> Self

Tell the app that you would like it to create a single, simple, default window just before it calls your model function.

The given view function will play the same role as if passed to the view builder method. Note that the view function passed to this method will overwrite any pre-existing view function specified by any preceding call to the view

Note that calling this multiple times will not give you multiple windows, but instead will simply overwrite pre-existing calls to the method. If you would like to create multiple windows or would like more flexibility in your window creation process, please see the App::new_window method. The role of this simple_window method is to provide a quick-and-easy way to start with a simple window. This can be very useful for quick ideas, small single-window applications and examples.

pub fn exit(self, exit: ExitFn<M>) -> Self

Specify an exit function to be called when the application exits.

The exit function gives ownership of the model back to you for any cleanup that might be necessary.

pub fn size(self, width: u32, height: u32) -> Self

Specify the default window size in points.

If a window is created and its size is not specified, this size will be used.

pub fn fullscreen(self) -> Self

Specify that windows should be created on the primary monitor by default.

pub fn loop_mode(self, mode: LoopMode) -> Self

Specify the default initial loop mode for this app.

pub fn max_capture_frame_jobs(self, max_jobs: u32) -> Self

The maximum number of simultaneous capture frame jobs that can be run per window before we block and wait for the existing jobs to complete.

A “capture frame job” refers to the combind process of waiting to read a frame from the GPU and then writing that frame to an image file on the disk. Each call to window.capture_frame(path) spawns a new “capture frame job” on an internal thread pool.

By default, this value is equal to the number of physical cpu threads available on the system. However, keep in mind that this means there must be room in both RAM and VRAM for this number of textures to exist per window at any moment in time. If you run into an “out of memory” error, try reducing the number of max jobs to a lower value, though never lower than 1.

Panics if the specified value is less than 1.

pub fn capture_frame_timeout(self, timeout: Option<Duration>) -> Self

In the case that max_capture_frame_jobs is reached and the main thread must block, this specifies how long to wait for a running capture job to complete. See the max_capture_frame_jobs docs for more details.

By default, the timeout used is equal to app::Builder::DEFAULT_CAPTURE_FRAME_TIMEOUT.

If None is specified, the capture process will never time out. This may be necessary on extremely low-powered machines that take a long time to write each frame to disk.

pub fn backends(self, backends: Backends) -> Self

Specify the set of preferred WGPU backends.

By default, this is wgpu::Backends::PRIMARY | wgpu::Backends::GL.

pub fn run(self)

Build and run an App with the specified parameters.

This function will not return until the application has exited.

If you wish to remain cross-platform friendly, we recommend that you call this on the main thread as some platforms require that their application event loop and windows are initialised on the main thread.

pub async fn run_async(self)

impl Builder<(), Event>

pub fn sketch(view: SketchViewFn) -> SketchBuilder<Event>

Shorthand for building a simple app that has no model, handles no events and simply draws to a single window.

This is useful for late night hack sessions where you just don’t care about all that other stuff, you just want to play around with some ideas or make something pretty.