VPP  0.8
A high-level modern C++ API for Vulkan
vpp::SwapChain Class Reference

Represents a set of swappable on-screen images. More...

#include <vppSwapChain.hpp>

Public Member Functions

 SwapChain ()
 Constructs null reference.
 
 SwapChain (const Device &hDevice, const Surface &hSurface, unsigned int imageCount=0, VkPresentModeKHR imageQueuingMode=VK_PRESENT_MODE_MAILBOX_KHR, const SwapChain &hReplacedSwapChain=SwapChain())
 Constructs a swapchain for given Surface and Device pair. More...
 
bool valid () const
 Checks whether this SwapChain object refers to a valid swapchain.
 
VkSwapchainKHR handle () const
 Retrieves the Vulkan handle.
 
const Devicedevice () const
 Retrieves the device.
 
const Surfacesurface () const
 Retrieves the surface.
 
size_t views () const
 Retrieves the number of images in the swapchain.
 
FrameImageView view (size_t index) const
 Retrieves the image view for given index.
 
unsigned int acquireDisplayImage (const Queue &hQueue)
 Acquires and locks an image view for rendering. More...
 
void presentDisplayImage (const Queue &hQueue, unsigned int iImage)
 Schedules an image view for display. More...
 

Detailed Description

Represents a set of swappable on-screen images.

In typical situations, final images generated by the rendering engine are immediately displayed. This is the case of all game engines and other interactive applications. The SwapChain class provides a set of images (represented by untyped views, i.e. FrameImageView) that can be used as rendering targets and then scheduled for actual display on screen. There is more than one image in that set, to facilitate double buffering.

This object is reference-counted and may be passed by value.

Constructor & Destructor Documentation

◆ SwapChain()

vpp::SwapChain::SwapChain ( const Device hDevice,
const Surface hSurface,
unsigned int  imageCount = 0,
VkPresentModeKHR  imageQueuingMode = VK_PRESENT_MODE_MAILBOX_KHR,
const SwapChain hReplacedSwapChain = SwapChain() 
)

Constructs a swapchain for given Surface and Device pair.

In order to construct a swapchain, you need both Device and Surface object.

By default, the constructor makes a swapchain with system-defined number of images. This is recommended, since the minimum and maximum number of images are platform-dependent. Do not hardcode any particular number, as it might turn out to be unsupported on some combination of OS/graphic card. You can retrieve these limits by calling the Surface::getCapabilities() method. Provide zero value (or leave default one) to instruct VPP to determine the number of images automatically.

You can also specify image queuing mode as imageQueuingMode parameter. Unfortunately, availablility of these is also system-dependent and popular contemporary cards support only limited selection. You can retrieve supported modes by calling the Surface::getPresentationModes() method. The SwapChain constructor will try to use specified mode if possible, or fallback to another mode if not. See official Vulkan docs (the version with extensions docs, look for VkPresentModeKHR description) for complete list of queuing modes and their meaning.

The hReplacedSwapChain parameter is useful when we are creating a swapchain for the surface that already has a swapchain. The old swapchain will always be discarded, but providing a reference to it here allows to reuse some resources, making creating the new swapchain faster.

Member Function Documentation

◆ acquireDisplayImage()

unsigned int vpp::SwapChain::acquireDisplayImage ( const Queue hQueue)

Acquires and locks an image view for rendering.

Call this method to obtain an index of image. Retrieve the image view by calling view().

The image is supposed to be rendered and subsequently scheduled for display on the screen via presentDisplayImage().

This method also handles layout transitions and all other internal Vulkan requirements.

◆ presentDisplayImage()

void vpp::SwapChain::presentDisplayImage ( const Queue hQueue,
unsigned int  iImage 
)

Schedules an image view for display.

Call this method to queue a swapchain image for display.

The semantics of acquireDisplayImage()/presentDisplayImage() pair is like resource allocation/releasing. Each call to acquireDisplayImage() must be paired with presentDisplayImage().

This method also handles layout transitions and all other internal Vulkan requirements.


The documentation for this class was generated from the following file: