APIs such as Vulkan can be used for many different purposes, such as mathematical and physical computations, image or video stream processing, and data visualizations. But the main purpose Vulkan was designed for and its most common usage is efficiently rendering 2D and 3D graphics. And when our application generates an image, we usually would like to display it on screen.

At first, it may seem surprising that the core of the Vulkan API doesn't allow for displaying generated images in the application's window. This is because Vulkan is a portable, cross-platform API but, unfortunately, there is no universal standard for presenting images on screen in different operating systems because they have drastically different architectures and standards.

That's why a set of extensions was introduced for the Vulkan API which allow us to present generated images in an application's window....

To be able to properly display images on screen, we need to enable a set of WSI extensions. They are divided into instance- and device-levels, depending on the functionality they introduce. The first step is to create a Vulkan Instance with a set of enabled extensions that allow us to create a presentation surface--a Vulkan representation of an application's window.

On the Windows operating systems family, perform the following steps:

1. Prepare a variable of type VkInstance named instance.
2. Prepare a variable of type std::vector<char const *> named desired_extensions. Store the names of all extensions you want to enable in the desired_extensions variable.
3. Add another element to the desired_extensions...

A presentation surface represents an application's window. It allows us to acquire the window's parameters, such as dimensions, supported color formats, required number of images, or presentation modes. It also allows us to check whether a given physical device is able to display an image in a given window.

That's why, in situations where we want to show an image on screen, we need to create a presentation surface first, as it will help us choose a physical device that suits our needs.

To create a presentation surface, we need to provide the parameters of an application's window. In order to do that, the window must have been already created. In this recipe, we will provide its parameters through a...

Displaying an image on screen is performed by submitting a special command to the device's queue. We can't display images using any queues we want or, in other words, we can't submit this operation to any queue. This is because it may not be supported. Image presentation, along with the graphics, compute, transfer, and sparse operations, is another property of a queue family. And similar to all types of operations, not all queues may support it and, more importantly, not even all devices may support it. That's why we need to check what queue family from which physical device allows us to present an image on screen.

1. Take the handle of a physical device returned...

When we have created an Instance with WSI extensions enabled and have found a queue family that supports image presentation, it is time to create a logical device with another extension enabled. A device-level WSI extension allows us to create a swapchain. This is a collection of images which are managed by the presentation engine. In order to use any of these images and to render into them, we need to acquire them. After we are done, we give it back to the presentation engine. This operation is called a presentation and it informs the driver that we want to show an image to the user (present or display it on screen). The presentation engine displays it according to the parameters defined during swapchain creation. And we can create it only on logical devices with an enabled swapchain extension.

The ability to display images on screen is one of the most important features of a Vulkan's swapchain--and, in fact, it's what a swapchain was designed for. In OpenGL, when we finished rendering to a back buffer, we just switched it with a front buffer and the rendered image was displayed on screen. We could only determine whether we wanted to display an image along with blanking intervals (if we wanted a v-sync to be enabled) or not.

In Vulkan, we are not limited to only one image (back buffer) to which we can render. And, instead of two (v-sync enabled or disabled), we can select one of more ways in which images are displayed on screen. This is called a presentation mode and we need to specify it during swapchain creation.

When we create a swapchain, we need to specify creation parameters. But we can't choose whatever values we want. We must provide values that fit into supported limits, which can be obtained from a presentation surface. So in order to properly create a swapchain, we need to acquire the surface's capabilities.

1. Take the handle of a selected physical device enumerated using the vkEnumeratePhysicalDevices() function and store it in a variable of type VkPhysicalDevice named physical_device.
2. Take the handle of a created presentation surface. Store it in a variable of type VkSurfaceKHR named presentation_surface.
3. Create a variable of type VkSurfaceCapabilitiesKHR named surface_capabilities.
4. Call...

When an application wants to render into a swapchain image, it must acquire it from the presentation engine. An application can acquire more images; we are not limited to just one image at a time. But the number of images that are available (unused by the presentation engine at a given time) depends on the specified presentation mode, the application's current situation (rendering/presenting history), and the number of images--when we create a swapchain, we must specify the (minimal) number of images that should be created.

1. Acquire the capabilities of a presentation surface (refer to the Getting capabilities of a presentation surface recipe). Store them in a variable of type VkSurfaceCapabilitiesKHR named...

Usually, images created for a swapchain should fit into an application's window. The supported dimensions are available in the presentation surface's capabilities. But on some operating systems, the size of the images defines the final size of the window. We also should keep that in mind and check what dimensions are proper for the swapchain images.

1. Acquire the capabilities of a presentation surface (refer to the Getting capabilities of a presentation surface recipe). Store them in a variable of type VkSurfaceCapabilitiesKHR named surface_capabilities.
2. Create a variable of type VkExtent2D named size_of_images in which we will store the desired size of swapchain images.
3. Check whether the currentExtent...

Images created with a swapchain are usually used as color attachments. This means that we want to render into them (use them as render targets). But we are not limited only to this scenario. We can use swapchain images for other purposes--we can sample from them, use them as a source of data in copy operations, or copy data into them. These are all different image usages and we can specify them during swapchain creation. But, again, we need to check whether these usages are supported.

1. Acquire the capabilities of a presentation surface (refer to the Getting capabilities of a presentation surface recipe). Store them in a variable of type VkSurfaceCapabilitiesKHR named surface_capabilities.
2. Choose...

On some (especially mobile) devices, images can be viewed from different orientations. Sometimes we would like to be able to specify how an image should be oriented when it is displayed on screen. In Vulkan, we have such a possibility. When creating a swapchain, we need to specify the transformation which should be applied to an image before it is presented.

1. Acquire the capabilities of a presentation surface (refer to the Getting capabilities of a presentation surface recipe). Store them in a variable of type VkSurfaceCapabilitiesKHR named surface_capabilities.
2. Store the desired transformations in a bit field variable of type VkSurfaceTransformFlagBitsKHR named desired_transform.
3. Create a variable of...

The format defines the number of color components, the number of bits for each component, and the used data type. During swapchain creation, we must specify whether we want to use red, green, and blue channels with or without an alpha component, whether the color values should be encoded using unsigned integer or floating-point data types, and what their precision is. We must also choose whether we are encoding color values using linear or nonlinear color space. But as with other swapchain parameters, we can use only values that are supported by the presentation surface.

In this recipe, we use several terms that may seem identical, but in fact they specify different parameters:

• Image format is used to describe...

A swapchain is used to display images on screen. It is an array of images which can be acquired by the application and then presented in our application's window. Each image has the same defined set of properties. When we have prepared all of these parameters, meaning that we chose a number, a size, a format, and usage scenarios for swapchain images, and also acquired and selected one of the available presentation modes, we are ready to create a swapchain.

1. Take the handle of a created logical device object. Store it in a variable of type VkDevice named logical_device.
2. Assign the handle of a created presentation surface to a variable of type VkSurfaceKHR named presentation_surface.
3. Take the desired number of swapchain images...

When the swapchain object is created, it may be very useful to acquire the number and handles of all images that were created along with the swapchain.

1. Take the handle of a created logical device object. Store it in a variable of type VkDevice named logical_device.
2. Assign the handle of a created swapchain to a variable of type VkSwapchainKHR named swapchain.
3. Create a variable of type uint32_t named images_count.
4. Call vkGetSwapchainImagesKHR(logical_device, swapchain, &images_count, nullptr) for which provide the handle to the created logical device in the first parameter, the handle of the swapchain in the second, and a pointer to the images_count variable in the third parameter. Provide a nullptr value in...

To create a swapchain, we need to acquire a lot of additional information and prepare a considerable number of parameters. To present the order of all the steps required for the preparation phases and how to use the acquired information, we will create a swapchain with arbitrarily chosen parameters. For it, we will set a mailbox presentation mode, the most commonly used R8G8B8A8 color format with unsigned normalized values (similar to OpenGL's RGBA8 format), no transformations, and a standard color attachment image usage.

1. Prepare a physical device handle. Store it in a variable of type VkPhysicalDevice named physical_device.
2. Take the handle of a created presentation surface...

Before we can use a swapchain image, we need to ask a presentation engine for it. This process is called image acquisition. It returns an image's index into the array of images returned by the vkGetSwapchainImagesKHR() function as described in the Getting handles of swapchain images recipe.

To acquire an image in Vulkan, we need to specify one of two types of objects that haven't been described yet. These are semaphores and fences.

Semaphores are used to synchronize device's queues. It means that when we submit commands for processing, these commands may require another job to be finished. In such a situation, we can specify that these commands should wait for the other commands before they are executed. And...

After we are done rendering into a swapchain image or using it for any other purposes, we need to give the image back to the presentation engine. This operation is called a presentation and it displays an image on screen.

In this recipe, we will be using a custom structure defined as follows:

struct PresentInfo { 
  VkSwapchainKHR  Swapchain; 
  uint32_t        ImageIndex; 
};

It is used to define a swapchain from which we want to present an image, and an image (its index) that we want to display. For each swapchain, we can present only one image at a time.

1. Prepare...

When we are done using a swapchain, because we don't want to present images any more, or because we are just closing our application, we should destroy it. We need to destroy it before we destroy a presentation surface which was used during a given swapchain creation.

1. Take the handle of a logical device and store it in a variable of type VkDevice named logical_device.
2. Take the handle of a swapchain object that needs to be destroyed. Store it in a variable of type VkSwapchainKHR named swapchain.
3. Call vkDestroySwapchainKHR( logical_device, swapchain, nullptr ) and provide the logical_device variable as the first argument and the swapchain handle as the second argument. Set the last parameter to nullptr.
4. For safety reasons...

The presentation surface represents the window of our application. It is used, among other purposes, during swapchain creation. That's why we should destroy the presentation surface after the destruction of a swapchain that is based on a given surface is finished.

1. Prepare the handle of a Vulkan Instance and store it in a variable of type VkInstance named instance.
2. Take the handle of a presentation surface and assign it to the variable of type VkSurfaceKHR named presentation_surface.
3. Call vkDestroySurfaceKHR( instance, presentation_surface, nullptr ) and provide the instance and presentation_surface variables in the first two parameters and a nullptr value in the last parameter.
4. For safety reasons, assign a VK_NULL_HANDLE...