Struct FramesInFlight 

pub struct FramesInFlight { /* private fields */ }

The fundamental synchronization mechanism for an application with N “frames in flight” where frame K’s graphics command buffer can be recorded while frames K+1, K+2, … K+N are all in-progress rendering on the GPU.

For example, when there are 3 frames in flight, the sequence can be visualized like so:

---
config:
  theme: dark
---
sequenceDiagram
    participant app as App
    box Frames In Flight
    participant f0 as Frame[0]
    participant f1 as Frame[1]
    participant f2 as Frame[2]
    end
    participant swp as Swapchain

    %% ------- %%
    %% Frame 0 %%
    %% ------- %%
    f0 ->> f0: Wait for previous Frame[0]
graphics commands fence
    activate f0
    swp ->> f0: acquire swapchain image
    f0 ->> app: start_frame()->
 Frame
    activate app
    Note left of app: Record commands for
the Frame. Return
ownership of Frame
instance when complete.
    app ->> f0: present_frame(Frame)
    deactivate app
    f0 ->> f0: Submit Graphics 
 Command Buffer and
Signal Frame[0] Fence
when finished

    %% ------- %%
    %% Frame 1 %%
    %% ------- %%
    f1 ->> f1: Wait for previous Frame[1]
graphics commands fence
    activate f1
    swp ->> f1: acquire swapchain image
    f1 ->> app: start_frame()->
 Frame
    activate app
    Note left of app: Record commands for
the Frame. Return
ownership of Frame
instance when complete.
    app ->> f1: present_frame(Frame)
    deactivate app
    f1 ->> f1: Submit Graphics 
 Command Buffer and
Signal Frame[1] Fence
when finished

    %% ------- %%
    %% Frame 2 %%
    %% ------- %%
    f2 ->> f2: Wait for previous Frame[2]
graphics commands fence
    activate f2
    swp ->> f2: acquire swapchain image
    f2 ->> app: start_frame()->
 Frame
    activate app
    Note left of app: Record commands for
the Frame. Return
ownership of Frame
instance when complete.
    app ->> f2: present_frame(Frame)
    deactivate app
    f2 ->> f2: Submit Graphics 
 Command Buffer and
Signal Frame[2] Fence
when finished

    f0 ->> swp: present image when graphics
commands for Frame[0] signal
the present semaphore.
    deactivate f0

    %% ------- %%
    %% Frame 0 %%
    %% ------- %%
    f0 ->> f0: Wait for previous Frame[0]
graphics commands fence
    activate f0
    swp ->> f0: acquire swapchain image
    f0 ->> app: start_frame()->
 Frame
    activate app
    Note left of app: Record commands for
the Frame. Return
ownership of Frame
instance when complete.
    app ->> f0: present_frame(Frame)
    deactivate app
    f0 ->> f0: Submit Graphics 
 Command Buffer and
Signal Frame[0] Fence
when finished

    f1 ->> swp: present image when graphics
commands for Frame[1] signal
the present semaphore.
    deactivate f1

    %% ------- %%
    %% Frame 1 %%
    %% ------- %%
    f1 ->> f1: Wait for previous Frame[1]
graphics commands fence
    activate f1
    swp ->> f1: acquire swapchain image
    f1 ->> app: start_frame()->
 Frame
    activate app
    Note left of app: Record commands for
the Frame. Return
ownership of Frame
instance when complete.
    app ->> f1: present_frame(Frame)
    deactivate app
    f1 ->> f1: Submit Graphics 
 Command Buffer and
Signal Frame[1] Fence
when finished


    f2 ->> swp: present image when graphics
commands for Frame[2] signal
the present semaphore.
    deactivate f2


    f0 ->> swp: present image when graphics
commands for Frame[0] signal
the present semaphore.
    deactivate f0

    f1 ->> swp: present image when graphics
commands for Frame[1] signal
the present semaphore.
    deactivate f1

The application takes ownership of the Frame object when calling Self::start_frame and returns ownership when calling Self::present_frame. As such, any time a system needs to access a frame-specific resource, the best option is to accept an Frame borrow and use Frame::frame_index to select frame-specific resources. This is certain to be safe because the only time the application has a Frame instance is when that frame’s previous commands have finished executing.

Implementations

impl FramesInFlight

pub fn new( ctx: Arc<VulkanContext>, swapchain_image_count: usize, frame_count: usize, ) -> Result<Self>

Creates a new instance with frame_count frames.

pub fn frame_count(&self) -> usize

Get the total number of configured frames in flight.

pub fn wait_for_all_frames_to_complete(&self) -> Result<()>

Blocks until all submitted commands for all frames have completed.

NOTE: Only waits on pending frames. If there’s a frame mid-assembly, there’s nothing to wait on. (and what’s more, attempting to wait would never succeed until the frame is submitted)

pub fn start_frame(&mut self, swapchain: &Swapchain) -> Result<FrameStatus>

Starts the next frame in flight.

This method can block if all frames are in flight. It will block until the next frame is available.

Returns

A FrameStatus containing one of:

• A Frame that must be returned to Self::present_frame
• A flag indicating that the Swapchain needs to be rebuilt before the next frame.

pub fn present_frame( &mut self, swapchain: &Swapchain, frame: Frame, ) -> Result<PresentImageStatus>

Queues the Frame’s command buffer and swapchain presentation.

Trait Implementations

impl Debug for FramesInFlight

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

Formats the value using the given formatter.

impl Drop for FramesInFlight

fn drop(&mut self)

Executes the destructor for this type.