Struct nannou::window::Builder

pub struct Builder<'app> { /* private fields */ }

A context for building a window.

Implementations

impl<'app> Builder<'app>

pub const DEFAULT_POWER_PREFERENCE: PowerPreference = wgpu::DEFAULT_POWER_PREFERENCE

The default power preference used to request the WGPU adapter.

pub const DEFAULT_FORCE_FALLBACK_ADAPTER: bool = false

The default force_fallback_adapter field used to request the WGPU adapter.

pub fn new(app: &'app App) -> Self

Begin building a new window.

pub fn window(self, window: WindowBuilder) -> Self

Build the window with some custom window parameters.

pub fn surface_conf_builder( self, surface_conf_builder: SurfaceConfigurationBuilder ) -> Self

Specify a set of parameters for building the window surface.

pub fn power_preference(self, pref: PowerPreference) -> Self

Specify the power preference desired for the WGPU adapter.

By default, this is wgpu::PowerPreference::HighPerformance.

pub fn force_fallback_adapter(self, force: bool) -> Self

Indicates that only a fallback adapter can be returned. This is generally a “software” implementation on the system..

By default, this is false.

pub fn device_descriptor(self, device_desc: DeviceDescriptor<'static>) -> Self

Specify a device descriptor to use when requesting the logical device from the adapter. This allows for specifying custom wgpu device extensions.

pub fn msaa_samples(self, msaa_samples: u32) -> Self

Specify the number of samples per pixel for the multisample anti-aliasing render pass.

If msaa_samples is unspecified, the first default value that nannou will attempt to use can be found via the Frame::DEFAULT_MSAA_SAMPLES constant.

Note: This parameter has no meaning if the window uses a raw_view function for rendering graphics to the window rather than a view function. This is because the raw_view function provides a RawFrame with direct access to the surface texture itself and thus must manage their own MSAA pass.

On the other hand, the view function provides the Frame type which allows the user to render to a multisampled intermediary image allowing Nannou to take care of resolving the multisampled texture to the surface texture. In order to avoid confusion, The Window::build method will panic! if the user tries to specify msaa_samples as well as a raw_view method.

TODO: Perhaps it would be worth adding two separate methods for specifying msaa samples. One for forcing a certain number of samples and returning an error otherwise, and another for attempting to use the given number of samples but falling back to a supported value in the case that the specified number is not supported.

pub fn sketch(self, sketch_fn: SketchFn) -> Self

Provide a simple function for drawing to the window.

This is similar to view but does not provide access to user data via a Model type. This is useful for sketches where you don’t require tracking any state.

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

where M: 'static,

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

pub fn raw_view<M>(self, raw_view_fn: RawViewFn<M>) -> Self

where M: 'static,

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

Unlike the ViewFn, the RawViewFn provides a RawFrame that is designed for drawing directly to a window’s surface texture, rather than to a convenient intermediary image.

pub fn clear_color<C>(self, color: C) -> Self

where C: IntoLinSrgba<f32>,

Set the initial color of the window background when its contents are invalidated, e.g. upon window resize.

pub fn event<M>(self, event_fn: EventFn<M>) -> Self

where M: 'static,

A function for updating your model on WindowEvents associated with this window.

These include events such as key presses, mouse movement, clicks, resizing, etc.

Event Function Call Order

In nannou, if multiple functions require being called for a single kind of event, the more general event function will always be called before the more specific event function.

If an event function was also submitted to the App, that function will always be called immediately before window-specific event functions. Similarly, if a function associated with a more specific event type (e.g. key_pressed) was given, that function will be called after this function will be called.

Specific Events Variants

Note that if you only care about a certain kind of event, you can submit a function that only gets called for that specific event instead. For example, if you only care about key presses, you may wish to use the key_pressed method instead.

pub fn raw_event<M>(self, raw_event_fn: RawEventFn<M>) -> Self

where M: 'static,

The same as the event method, but allows for processing raw winit::event::WindowEvents rather than Nannou’s simplified event::WindowEvents.

Event Function Call Order

If both raw_event and event functions have been provided, the given raw_event function will always be called immediately before the given event function.

pub fn key_pressed<M>(self, f: KeyPressedFn<M>) -> Self

where M: 'static,

A function for processing key press events associated with this window.

pub fn key_released<M>(self, f: KeyReleasedFn<M>) -> Self

where M: 'static,

A function for processing key release events associated with this window.

pub fn received_character<M>(self, f: ReceivedCharacterFn<M>) -> Self

where M: 'static,

pub fn mouse_moved<M>(self, f: MouseMovedFn<M>) -> Self

where M: 'static,

A function for processing mouse moved events associated with this window.

pub fn mouse_pressed<M>(self, f: MousePressedFn<M>) -> Self

where M: 'static,

A function for processing mouse pressed events associated with this window.

pub fn mouse_released<M>(self, f: MouseReleasedFn<M>) -> Self

where M: 'static,

A function for processing mouse released events associated with this window.

pub fn mouse_wheel<M>(self, f: MouseWheelFn<M>) -> Self

where M: 'static,

A function for processing mouse wheel events associated with this window.

pub fn mouse_entered<M>(self, f: MouseEnteredFn<M>) -> Self

where M: 'static,

A function for processing mouse entered events associated with this window.

pub fn mouse_exited<M>(self, f: MouseExitedFn<M>) -> Self

where M: 'static,

A function for processing mouse exited events associated with this window.

pub fn touch<M>(self, f: TouchFn<M>) -> Self

where M: 'static,

A function for processing touch events associated with this window.

pub fn touchpad_pressure<M>(self, f: TouchpadPressureFn<M>) -> Self

where M: 'static,

A function for processing touchpad pressure events associated with this window.

pub fn moved<M>(self, f: MovedFn<M>) -> Self

where M: 'static,

A function for processing window moved events associated with this window.

pub fn resized<M>(self, f: ResizedFn<M>) -> Self

where M: 'static,

A function for processing window resized events associated with this window.

pub fn hovered_file<M>(self, f: HoveredFileFn<M>) -> Self

where M: 'static,

A function for processing hovered file events associated with this window.

pub fn hovered_file_cancelled<M>(self, f: HoveredFileCancelledFn<M>) -> Self

where M: 'static,

A function for processing hovered file cancelled events associated with this window.

pub fn dropped_file<M>(self, f: DroppedFileFn<M>) -> Self

where M: 'static,

A function for processing dropped file events associated with this window.

pub fn focused<M>(self, f: FocusedFn<M>) -> Self

where M: 'static,

A function for processing the focused event associated with this window.

pub fn unfocused<M>(self, f: UnfocusedFn<M>) -> Self

where M: 'static,

A function for processing the unfocused event associated with this window.

pub fn closed<M>(self, f: ClosedFn<M>) -> Self

where M: 'static,

A function for processing the window closed event associated with this window.

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

The maximum number of simultaneous capture frame jobs that can be run for this 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 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 build(self) -> Result<Id, BuildError>

Builds the window, inserts it into the App’s display map and returns the unique ID.

pub async fn build_async(self) -> Result<Id, BuildError>

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

Requests the window to be a specific size in points.

This describes to the “inner” part of the window, not including desktop decorations like the title bar.

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

Set the minimum size in points for the window.

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

Set the maximum size in points for the window.

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

Requests the window to be a specific size in points.

This describes to the “inner” part of the window, not including desktop decorations like the title bar.

pub fn resizable(self, resizable: bool) -> Self

Whether or not the window should be resizable after creation.

pub fn title<T>(self, title: T) -> Self

where T: Into<String>,

Requests a specific title for the window.

pub fn fullscreen(self) -> Self

Create the window fullscreened on the current monitor.

pub fn fullscreen_with(self, fullscreen: Option<Fullscreen>) -> Self

Set the window fullscreen state with the given settings.

• None indicates a normal window. This is the default case.
• Some(Fullscreen) means fullscreen with the desired settings.

pub fn maximized(self, maximized: bool) -> Self

Requests maximized mode.

pub fn visible(self, visible: bool) -> Self

Sets whether the window will be initially hidden or visible.

pub fn transparent(self, transparent: bool) -> Self

Sets whether the background of the window should be transparent.

pub fn decorations(self, decorations: bool) -> Self

Sets whether the window should have a border, a title bar, etc.

pub fn always_on_top(self, always_on_top: bool) -> Self

Sets whether or not the window will always be on top of other windows.

pub fn window_icon(self, window_icon: Option<Icon>) -> Self

Sets the window icon.