Struct nannou::frame::raw::RawFrame

pub struct RawFrame { /* fields omitted */ }

Allows the user to draw a single RawFrame to the surface of a window.

The application's view function is called each time the application is ready to retrieve a new image that will be displayed to a window. The RawFrame type can be thought of as the canvas to which you draw this image.

Under the hood - Vulkan

There are a couple of main goals for the RawFrame type:

• Allow for maximum flexibility and customisation over the:
  • Render Pass
  • Graphics Pipeline
  • Framebuffer Creation and
  • Command Buffer to the extent that the user may not interfere with the expected behaviour of the App.
• Provide reasonable defaults for each step so that it is friendly for new users.

Vulkan

Nannou uses Vulkan for interacting with the available graphics devices on a machine and for presenting images to the swapchain associated with each window. It does so via the vulkano crate, which is exposed publicly from the crate root. vulkano aims to be a type-safe, near-zero-cost API around the low-level Vulkan API. As a result vulkano tends to be a lot nicer than using the Vulkan API directly where it is the role of the user to maintain all the invariants described within the spec themselves. Due to this higher-level nature, nannou exposes the vulkano API directly in some areas where it is deemed reasonable/safe to do so.

In order to provide maximum flexibility, nannou allows for fully custom RenderPass and GraphicsPipeline via the vulkano API but aims to take care of the surface creation, swapchain tedium and rendering synchronisation behind the scenes.

Render Pass and Swapchain Framebuffers.

The render pass describes the destination for the output of the graphics pipeline. It is essential that the render pass uses the same pixel format of the window's surface. It also must be initialised with the same logical device with which the surface was initialised.

For now, it is up to the user to ensure these gaurantees are met. In the future nannou may provide a simplified constructor that implicitly uses the same logical device and format associated with the surface.

The user can create the framebuffers for the swapchain using this render pass by using the SwapchainFramebuffers type. While under the hood there is no distinction between the Framebuffer type used to draw to a swapchain image and any other image, nannou chooses to wrap these framebuffers in a type to ensure the following invariants are met:

• There must be one framebuffer per swapchain image.
• Each framebuffer must be recreated to match the dimensions of the swapchain each time the swapchain requires recreation. This will occur any time the window is resized on desktop or when an app comes in or out of focus on Android, and possibly in many other cases not mentioned here.
• It should be impossible to write to these framebuffers outside the view function to ensure framebuffer availability.
• Each call to view must draw to the framebuffer associated with the image that is ready as indicated by the swapchain::acquire_next_image function.

As a result, access to the swapchain framebuffers may feel relatively restrictive. If you require greater flexibility (e.g. control over framebuffer dimensions, the ability to draw to a framebuffer outside the view function, etc) then consider creating and writing to another intermediary framebuffer before drawing to the swapchain framebuffers.

See the vulkano documenation for more details on render passes and framebuffers.

Graphics Pipeline

The role of the GraphicsPipeline is similar to that of the GL "program" but much more detailed and explicit. It allows for describing and chaining together a series of custom shaders.

For more information on the graphics pipeline and how to create one, see the vulkano documentation.

Command Buffer

The API for the Frame type maps directly onto a vulkano AutoCommandBufferBuilder under the hood. This AutoCommandBufferBuilder is created using the primary_one_time_submit constructor. When returned, the App will build the command buffer and submit it to the GPU. Note that certain builder methods are not provided in order to avoid unexpected behaviour. E.g. the build and submit methods are not provided as it is important that the App is able to build the command buffer and synchronise its submission with the swapchain.

Use the frame.add_commands() method to begin chaining together commands. You may call this more than once throughout the duration of the view function.

See the vulkano documentation for more details on how command buffers work in vulkano.

Note: If you find you are unable to do something or that this API is too restrictive, please open an issue about it so that might be able to work out a solution!

Methods

impl RawFrame

pub fn swapchain_image_is_new(&self) -> bool

Returns whether or not this is the first time this swapchain image has been presented.

This will be true following each occurrence at which the swapchain has been recreated, which may occur during resize, loop mode switch, etc.

It is important to call this each frame to determine whether or not framebuffers associated with the swapchain need to be recreated.

pub fn add_commands(&self) -> AddCommands

Add commands to be executed by the GPU once the RawFrame is returned.

pub fn window_id(&self) -> Id

The Id of the window whose vulkan surface is associated with this frame.

pub fn nth(&self) -> u64

The nth frame for the associated window since the application started.

E.g. the first frame yielded will return 0, the second will return 1, and so on.

pub fn swapchain_image(&self) -> &Arc<SwapchainImage>

The swapchain image that will be the target for this frame.

NOTE: You should avoid using the returned SwapchainImage outside of the view function as it may become invalid at any moment. The reason we expose the Arc is that some of the vulkano API (including framebuffer creation) requires it to avoid some severe ownsership issues.

pub fn swapchain_image_index(&self) -> usize

The index associated with the swapchain image that will be the target for this frame.

pub fn queue(&self) -> &Arc<Queue>

The queue on which the swapchain image will be drawn.