Vulkan 3D Graphics Rendering Cookbook

Getting Started with Vulkan

In this chapter, we’ll take our first steps with Vulkan, focusing on swapchains, shaders, and pipelines. The recipes in this chapter will guide you through getting your first triangle on the screen using Vulkan. The Vulkan implementation we’ll use is based on the open-source library LightweightVK https://github.com/corporateshark/lightweightvk, which we’ll explore throughout the book.

In the chapter, we will cover the following recipes:

Initializing Vulkan instance and graphical device
Initializing Vulkan swapchain
Setting up Vulkan debugging capabilities
Using Vulkan command buffers
Initializing Vulkan shader modules
Initializing Vulkan pipelines

Initializing Vulkan instance and graphical device

As some readers may recall from the first edition of our book, the Vulkan API is significantly more verbose than OpenGL. To make things more manageable, we’ve broken down the process of creating our first graphical demo apps into a series of smaller, focused recipes. In this recipe, we’ll cover how to create a Vulkan instance, enumerate all physical devices in the system capable of 3D graphics rendering, and initialize one of these devices to create a window with an attached surface.

Getting ready

We recommend starting with beginner-friendly Vulkan books, such as The Modern Vulkan Cookbook by Preetish Kakkar and Mauricio Maurer (published by Packt) or Vulkan Programming Guide: The Official Guide to Learning Vulkan by Graham Sellers and John Kessenich (Addison-Wesley Professional).

The most challenging aspect of transitioning from OpenGL to Vulkan—or to any similar modern graphics API—is the extensive amount of explicit code required to set up the rendering process, which, fortunately, only needs to be done once. It’s also helpful to familiarize yourself with Vulkan’s object model. A great starting point is Adam Sawicki’s article, Understanding Vulkan Objects https://gpuopen.com/understanding-vulkan-objects. In the recipes that follow, our goal is to start rendering 3D scenes with the minimal setup needed, demonstrating how modern bindless Vulkan can be wrapped into a more user-friendly API.

All our Vulkan recipes rely on the LightweightVK library, which can be downloaded from https://github.com/corporateshark/lightweightvk using the provided Bootstrap snippet. This library implements all the low-level Vulkan wrapper classes, which we will discuss in detail throughout this book.

{
  "name": "lightweightvk",
  "source": {
    "type": "git",
    "url" : "https://github.com/corporateshark/lightweightvk.git",
    "revision": "v1.3"
  }
}

The complete Vulkan example for this recipe can be found in Chapter02/01_Swapchain.

How to do it...

Before diving into the actual implementation, let’s take a look at some scaffolding code that makes debugging Vulkan backends a bit easier. We will begin with error-checking facilities.

Any function call from a complex API can fail. To handle failures, or at least provide the developer with the exact location of the failure, LightweightVK wraps most Vulkan calls in the VK_ASSERT() and VK_ASSERT_RETURN() macros, which check the results of Vulkan operations. When starting a new Vulkan implementation from scratch, having something like this in place from the beginning can be very helpful.

#define VK_ASSERT(func) {                                  \
  const VkResult vk_assert_result = func;                  \
  if (vk_assert_result != VK_SUCCESS) {                    \
    LLOGW("Vulkan API call failed: %s:%i\n  %s\n  %s\n",   \
      __FILE__, __LINE__, #func,                           \
    ivkGetVulkanResultString(vk_assert_result));           \
    assert(false);                                         \
  }                                                        \
}

The VK_ASSERT_RETURN() macro is very similar and returns the control to the calling code.

#define VK_ASSERT_RETURN(func) {                           \
  const VkResult vk_assert_result = func;                  \
  if (vk_assert_result != VK_SUCCESS) {                    \
    LLOGW("Vulkan API call failed: %s:%i\n  %s\n  %s\n",   \
      __FILE__, __LINE__, #func,                           \
    ivkGetVulkanResultString(vk_assert_result));           \
    assert(false);                                         \
    return getResultFromVkResult(vk_assert_result);        \
  }                                                        \
}

Now we can start creating our first Vulkan application. Let’s explore what is going on in the sample application Chapter02/01_Swapchain which creates a window, a Vulkan instance and device together with a Vulkan swapchain, which will be explained in a few moments. The application code is very simple:

We start by initializing the Minilog logging library and creating a GLFW window as we discussed in the recipe Using the GLFW library from the Chapter 1. All the Vulkan setup magic, including creating a context and swapchain, is handled by the lvk::createVulkanContextWithSwapchain() helper function, which we will examine shortly.

int main(void) {
  minilog::initialize(nullptr, { .threadNames = false });
  int width  = 960;
  int height = 540;
  GLFWwindow* window = lvk::initWindow(
    "Simple example", width, height);
  std::unique_ptr<lvk::IContext> ctx =
    lvk::createVulkanContextWithSwapchain(
      window, width, height, {});

The application’s main loop handles updates to the framebuffer size if the window is sized, acquires a command buffer, submits it, and presents the current swapchain image, or texture as it is called in LightweightVK.

  while (!glfwWindowShouldClose(window)) {
    glfwPollEvents();
    glfwGetFramebufferSize(window, &width, &height);
    if (!width || !height) continue;
    lvk::ICommandBuffer& buf = ctx->acquireCommandBuffer();
    ctx->submit(buf, ctx->getCurrentSwapchainTexture());
  }

The shutdown process is straightforward. The IDevice object should be destroyed before the GLFW window.
```
  ctx.reset();
  glfwDestroyWindow(window);
  glfwTerminate();
  return 0;
}
```

The application should render an empty black window as in the following screenshot:

Figure 2.1: The main loop and swapchain

Let’s explore lvk::createVulkanContextWithSwapchain() and take a sneak peek at its implementation. As before, we will skip most of the error checking in the book text where it doesn’t contribute to the overall understanding:

This helper function calls LightweightVK to create a VulkanContext object, taking the provided GLFW window and display properties for our operating system into account. LightweightVK includes additional code paths for macOS/MoltenVK and Android initialization. We’ll skip them here for the sake of brevity and because not all the demos in this book are compatible with MoltenVK or Android.

std::unique_ptr<lvk::IContext> createVulkanContextWithSwapchain(
  GLFWwindow* window, uint32_t width, uint32_t height,
  const lvk::vulkan::VulkanContextConfig& cfg,
  lvk::HWDeviceType preferredDeviceType)
{
  std::unique_ptr<vulkan::VulkanContext> ctx;
#if defined(_WIN32)
  ctx = std::make_unique<VulkanContext>(cfg,
    (void*)glfwGetWin32Window(window));
#elif defined(__linux__)
  #if defined(LVK_WITH_WAYLAND)
  wl_surface* waylandWindow = glfwGetWaylandWindow(window);
  if (!waylandWindow) {
    LVK_ASSERT_MSG(false, "Wayland window not found");
    return nullptr;
  }
  ctx = std::make_unique<VulkanContext>(cfg,
    (void*)waylandWindow, (void*)glfwGetWaylandDisplay());
  #else
  ctx = std::make_unique<VulkanContext>(cfg,
    (void*)glfwGetX11Window(window), (void*)glfwGetX11Display());
  #endif // LVK_WITH_WAYLAND
#else
#  error Unsupported OS
#endif

Next, we enumerate Vulkan physical devices and attempt to select the most preferred one. We prioritize choosing a discrete GPU first, and if none is available, we opt for an integrated GPU.

  HWDeviceDesc device;
  uint32_t numDevices =
    ctx->queryDevices(preferredDeviceType, &device, 1);
  if (!numDevices) {
    if (preferredDeviceType == HWDeviceType_Discrete) {
      numDevices =
        ctx->queryDevices(HWDeviceType_Integrated, &device);
    } else if (preferredDeviceType == HWDeviceType_Integrated) {
      numDevices =
        ctx->queryDevices(HWDeviceType_Discrete, &device);
    }
  }

Once a physical device is selected, we call VulkanContext::initContext(), which creates all Vulkan and LightweightVK internal data structures.
```
  if (!numDevices) return nullptr;
  Result res = ctx->initContext(device);
  if (!res.isOk()) return nullptr;
```
If we have a non-empty viewport, initialize a Vulkan swapchain. The swapchain creation process will be explained in detail in the next recipe Initializing Vulkan swapchain.
```
  if (width > 0 && height > 0) {
    res = ctx->initSwapchain(width, height);
    if (!res.isOk()) return nullptr;
  }
  return std::move(ctx);
}
```

That covers the high-level code. Now, let’s dive deeper and explore the internals of LightweightVK to see how the actual Vulkan interactions work.

How it works...

There are several helper functions involved in getting Vulkan up and running. It all begins with the creation of a Vulkan instance in VulkanContext::createInstance(). Once the Vulkan instance is created, we can use it to acquire a list of physical devices with the required properties.

First, we need to check if the required Vulkan Validation Layers are available on our system. This ensures we have the flexibility to manually disable validation if no validation layers are present.

const char* kDefaultValidationLayers[] =
  {"VK_LAYER_KHRONOS_validation"};
void VulkanContext::createInstance() {
  vkInstance_ = VK_NULL_HANDLE;
  uint32_t numLayerProperties = 0;
  vkEnumerateInstanceLayerProperties(
    &numLayerProperties, nullptr);
  std::vector<VkLayerProperties>
    layerProperties(numLayerProperties);
  vkEnumerateInstanceLayerProperties(
    &numLayerProperties, layerProperties.data());

We use a local C++ lambda to iterate through the available validation layers and update VulkanContextConfig::enableValidation accordingly if none are found.

  [this, &layerProperties]() -> void {
    for (const VkLayerProperties& props : layerProperties) {
      for (const char* layer : kDefaultValidationLayers) {
        if (!strcmp(props.layerName, layer)) return;
      }
    }
    config_.enableValidation = false;
  }();

Then, we need to specify the names of all Vulkan instance extensions required to run our Vulkan graphics backend. We need VK_KHR_surface and another platform-specific extension which takes an OS window handle and attaches a rendering surface to it. On Linux, we support both libXCB-based window creation and the Wayland protocol. Here is how Wayland support was added to LightweightVK by Roman Kuznetsov: https://github.com/corporateshark/lightweightvk/pull/13.

  std::vector<const char*> instanceExtensionNames = {
    VK_KHR_SURFACE_EXTENSION_NAME,
    VK_EXT_DEBUG_UTILS_EXTENSION_NAME,
#if defined(_WIN32)
    VK_KHR_WIN32_SURFACE_EXTENSION_NAME,
#elif defined(VK_USE_PLATFORM_ANDROID_KHR)
    VK_KHR_ANDROID_SURFACE_EXTENSION_NAME,
#elif defined(__linux__)
  #if defined(VK_USE_PLATFORM_WAYLAND_KHR)
    VK_KHR_WAYLAND_SURFACE_EXTENSION_NAME,
  #else
    VK_KHR_XLIB_SURFACE_EXTENSION_NAME,
  #endif // VK_USE_PLATFORM_WAYLAND_KHR
#endif
  };

We add VK_EXT_validation_features when validation features are requested and available. Additionally, a headless rendering extension, VK_EXT_headless_surface, can also be added here together with all custom instance extensions from VulkanContextConfig::extensionsInstance[].

  if (config_.enableValidation)
    instanceExtensionNames.push_back(
      VK_EXT_VALIDATION_FEATURES_EXTENSION_NAME);
  if (config_.enableHeadlessSurface)
    instanceExtensionNames.push_back(
      VK_EXT_HEADLESS_SURFACE_EXTENSION_NAME);
  for (const char* ext : config_.extensionsInstance) {
    if (ext) instanceExtensionNames.push_back(ext);
  }

Next, we specify the enabled Vulkan validation features when validation is enabled.

  VkValidationFeatureEnableEXT validationFeaturesEnabled[] = {
    VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_EXT,
    VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_
      RESERVE_BINDING_SLOT_EXT,
  };
  const VkValidationFeaturesEXT features = {
    .sType = VK_STRUCTURE_TYPE_VALIDATION_FEATURES_EXT,
    .enabledValidationFeatureCount = config_.enableValidation ?
      (uint32_t)LVK_ARRAY_NUM_ELEMENTS(validationFeaturesEnabled) : 0u,
    .pEnabledValidationFeatures = config_.enableValidation ?
      validationFeaturesEnabled : nullptr,
  };

The next code snippet might be particularly interesting. Sometimes, we need to disable specific Vulkan validation checks, either for performance reasons or due to bugs in the Vulkan validation layers. Here’s how LightweightVK handles this to work around some known issues with the validation layers (these were the issues at the time of writing this book, of course).

  VkBool32 gpuav_descriptor_checks = VK_FALSE;
  VkBool32 gpuav_indirect_draws_buffers = VK_FALSE;
  VkBool32 gpuav_post_process_descriptor_indexing = VK_FALSE;
#define LAYER_SETTINGS_BOOL32(name, var)              \
  VkLayerSettingEXT {                                 \
    .pLayerName = kDefaultValidationLayers[0],        \
    .pSettingName = name,                             \
    .type = VK_LAYER_SETTING_TYPE_BOOL32_EXT,         \
    .valueCount = 1,                                  \
    .pValues = var }
  const VkLayerSettingEXT settings[] = {
    LAYER_SETTINGS_BOOL32("gpuav_descriptor_checks",
      &gpuav_descriptor_checks),
    LAYER_SETTINGS_BOOL32("gpuav_indirect_draws_buffers",
      &gpuav_indirect_draws_buffers),
    LAYER_SETTINGS_BOOL32(
      "gpuav_post_process_descriptor_indexing",
      &gpuav_post_process_descriptor_indexing),
  };
#undef LAYER_SETTINGS_BOOL32
  const VkLayerSettingsCreateInfoEXT layerSettingsCreateInfo = {
    .sType = VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT,
    .pNext = config_.enableValidation ? &features : nullptr,
    .settingCount = (uint32_t)LVK_ARRAY_NUM_ELEMENTS(settings),
    .pSettings = settings
  };

After constructing the list of instance-related extensions, we need to fill in some mandatory information about our application. Here, we request the required Vulkan version, VK_API_VERSION_1_3.

  const VkApplicationInfo appInfo = {
    .sType = VK_STRUCTURE_TYPE_APPLICATION_INFO,
    .pApplicationName = "LVK/Vulkan",
    .applicationVersion = VK_MAKE_VERSION(1, 0, 0),
    .pEngineName = "LVK/Vulkan",
    .engineVersion = VK_MAKE_VERSION(1, 0, 0),
    .apiVersion = VK_API_VERSION_1_3,
  };

To create a VkInstance object, we need to populate the VkInstanceCreateInfo structure. We use pointers to the previously mentioned appInfo constant and layerSettingsCreateInfo we created earlier. We also use a list of requested Vulkan layers stored in the global variable kDefaultValidationLayers[], which will allow us to enable debugging output for every Vulkan call. The only layer we use in this book is the Khronos validation layer, VK_LAYER_KHRONOS_validation. Then, we use the Volk library to load all instance-related Vulkan functions for the created VkInstance.

Note

Volk is a meta-loader for Vulkan. It allows you to dynamically load entry points required to use Vulkan without linking to vulkan-1.dll or statically linking the Vulkan loader. Volk simplifies the use of Vulkan extensions by automatically loading all associated entry points. Besides that, Volk can load Vulkan entry points directly from the driver which can increase performance by skipping loader dispatch overhead. https://github.com/zeux/volk

  const VkInstanceCreateInfo ci = {
    .sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO,
    .pNext = &layerSettingsCreateInfo,
    .pApplicationInfo = &appInfo,
    .enabledLayerCount = config_.enableValidation ?
      (uint32_t)LVK_ARRAY_NUM_ELEMENTS(kDefaultValidationLayers) : 0u,
    .ppEnabledLayerNames = config_.enableValidation ?
      kDefaultValidationLayers : nullptr,
    .enabledExtensionCount =
      (uint32_t)instanceExtensionNames.size(),
    .ppEnabledExtensionNames = instanceExtensionNames.data(),
  };
  VK_ASSERT(vkCreateInstance(&ci, nullptr, &vkInstance_));
  volkLoadInstance(vkInstance_);

Last but not least, let’s print a neatly formatted list of all available Vulkan instance extensions. The function vkEnumerateInstanceExtensionProperties() is called twice: first to get the number of available extensions, and second to retrieve information about them.

  uint32_t count = 0;
  vkEnumerateInstanceExtensionProperties(
    nullptr, &count, nullptr);
  std::vector<VkExtensionProperties>
    allInstanceExtensions(count);
  vkEnumerateInstanceExtensionProperties(
    nullptr, &count, allInstanceExtensions.data()));
  LLOGL("\nVulkan instance extensions:\n");
  for (const VkExtensionProperties& extension : allInstanceExtensions)
    LLOGL("  %s\n", extension.extensionName);
}

Note

If you’ve looked at the actual source code in VulkanClasses.cpp, you’ll have noticed that we skipped the Debug Messenger initialization code here. It will be covered later in the recipe Setting up Vulkan debugging capabilities.

Once we’ve created a Vulkan instance, we can access the list of Vulkan physical devices, which are necessary to continue setting up our Vulkan context. Here’s how we can enumerate Vulkan physical devices and choose a suitable one:

The function vkEnumeratePhysicalDevices() is called twice: first to get the number of available physical devices and allocate std::vector storage for it, and second to retrieve the actual physical device data.

uint32_t lvk::VulkanContext::queryDevices(
  HWDeviceType deviceType,
  HWDeviceDesc* outDevices,
  uint32_t maxOutDevices)
{
  uint32_t deviceCount = 0;
  vkEnumeratePhysicalDevices(vkInstance_, &deviceCount, nullptr);
  std::vector<VkPhysicalDevice> vkDevices(deviceCount);
  vkEnumeratePhysicalDevices(
    vkInstance_, &deviceCount, vkDevices.data());

We iterate through the vector of devices to retrieve their properties and filter out non-suitable ones. The local lambda function convertVulkanDeviceTypeToLVK() converts a Vulkan enum, VkPhysicalDeviceType, into a LightweightVK enum, HWDeviceType.

More information

enum HWDeviceType {
  HWDeviceType_Discrete = 1,
  HWDeviceType_External = 2,
  HWDeviceType_Integrated = 3,
  HWDeviceType_Software = 4,
};

  const HWDeviceType desiredDeviceType = deviceType;
  uint32_t numCompatibleDevices = 0;
  for (uint32_t i = 0; i < deviceCount; ++i) {
    VkPhysicalDevice physicalDevice = vkDevices[i];
    VkPhysicalDeviceProperties deviceProperties;
    vkGetPhysicalDeviceProperties(
      physicalDevice, &deviceProperties);
    const HWDeviceType deviceType =
      convertVulkanDeviceTypeToLVK(deviceProperties.deviceType);
    if (desiredDeviceType != HWDeviceType_Software &&
        desiredDeviceType != deviceType) continue;
    if (outDevices && numCompatibleDevices < maxOutDevices) {
      outDevices[numCompatibleDevices] =
        {.guid = (uintptr_t)vkDevices[i], .type = deviceType};
      strncpy(outDevices[numCompatibleDevices].name,
              deviceProperties.deviceName,
              strlen(deviceProperties.deviceName));
      numCompatibleDevices++;
    }
  }
  return numCompatibleDevices;
}

Once we’ve selected a suitable Vulkan physical device, we can create a logical representation of a single GPU, or more precisely, a device VkDevice. We can think of Vulkan devices as collections of queues and memory heaps. To use a device for rendering, we need to specify a queue capable of executing graphics-related commands, along with a physical device that has such a queue. Let’s explore LightweightVK and some parts of the function VulkanContext::initContext(), which, among many other things we’ll cover later, detects suitable queue families and creates a Vulkan device. As before, most of the error checking will be omitted here in the text.

The first thing we do in VulkanContext::initContext() is retrieve all supported extensions of the physical device we selected earlier and the Vulkan driver. We store them in allDeviceExtensions to later decide which features we can enable. Note how we iterate over the validation layers to check which extensions they bring in.

lvk::Result VulkanContext::initContext(const HWDeviceDesc& desc)
{
  vkPhysicalDevice_ = (VkPhysicalDevice)desc.guid;
  std::vector<VkExtensionProperties> allDeviceExtensions;
  getDeviceExtensionProps(
    vkPhysicalDevice_, allDeviceExtensions);
  if (config_.enableValidation) {
    for (const char* layer : kDefaultValidationLayers)
      getDeviceExtensionProps(
        vkPhysicalDevice_, allDeviceExtensions, layer);
  }

Then, we can retrieve all Vulkan features and properties for this physical device.

  vkGetPhysicalDeviceFeatures2(
    vkPhysicalDevice_, &vkFeatures10_);
  vkGetPhysicalDeviceProperties2(
    vkPhysicalDevice_, &vkPhysicalDeviceProperties2_);

The class member variables vkFeatures10_, vkFeatures11_, vkFeatures12_, and vkFeatures13_ are declared in VulkanClasses.h and correspond to the Vulkan features for Vulkan versions 1.0 to 1.3. These structures are chained together using their pNext pointers as follows:

  // lightweightvk/lvk/vulkan/VulkanClasses.h
  VkPhysicalDeviceVulkan13Features vkFeatures13_ = {
    .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES};
  VkPhysicalDeviceVulkan12Features vkFeatures12_ = {
    .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_FEATURES,
    .pNext = &vkFeatures13_};
  VkPhysicalDeviceVulkan11Features vkFeatures11_ = {
    .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_FEATURES,
    .pNext = &vkFeatures12_};
  VkPhysicalDeviceFeatures2 vkFeatures10_ = {
    .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2,
    .pNext = &vkFeatures11_};
  // ...

Let’s get back to initContext() and print some information related to the Vulkan physical device and a list of all supported extensions. This is very useful for debugging.

  const uint32_t apiVersion =
    vkPhysicalDeviceProperties2_.properties.apiVersion;
  LLOGL("Vulkan physical device: %s\n",
        vkPhysicalDeviceProperties2_.properties.deviceName);
  LLOGL("           API version: %i.%i.%i.%i\n",
        VK_API_VERSION_MAJOR(apiVersion),
        VK_API_VERSION_MINOR(apiVersion),
        VK_API_VERSION_PATCH(apiVersion),
        VK_API_VERSION_VARIANT(apiVersion));
  LLOGL("           Driver info: %s %s\n",
        vkPhysicalDeviceDriverProperties_.driverName,
        vkPhysicalDeviceDriverProperties_.driverInfo);
  LLOGL("Vulkan physical device extensions:\n");
  for (const VkExtensionProperties& ext : allDeviceExtensions) {
    LLOGL("  %s\n", ext.extensionName);
  }

Before creating a VkDevice object, we need to find the queue family indices and create queues. This code block creates one or two device queues—graphical and compute—based on the actual queue availability on the provided physical device. The helper function lvk::findQueueFamilyIndex(), implemented in lvk/vulkan/VulkanUtils.cpp, returns the first dedicated queue family index that matches the requested queue flag. It’s recommended to take a look at it to see how it ensures the selection of dedicated queues first.
Note

In Vulkan, queueFamilyIndex is the index of the queue family to which the queue belongs. A queue family is a collection of Vulkan queues with similar properties and functionality. Here deviceQueues_ is member field of VulkanContext holding a structure with queues information:
```
struct DeviceQueues {
  const static uint32_t INVALID = 0xFFFFFFFF;
  uint32_t graphicsQueueFamilyIndex = INVALID;
  uint32_t computeQueueFamilyIndex = INVALID;
  VkQueue graphicsQueue = VK_NULL_HANDLE;
  VkQueue computeQueue = VK_NULL_HANDLE;
};
```

  deviceQueues_.graphicsQueueFamilyIndex =
    lvk::findQueueFamilyIndex(vkPhysicalDevice_,
      VK_QUEUE_GRAPHICS_BIT);
  deviceQueues_.computeQueueFamilyIndex =
    lvk::findQueueFamilyIndex(vkPhysicalDevice_,
      VK_QUEUE_COMPUTE_BIT);
  const float queuePriority = 1.0f;
  const VkDeviceQueueCreateInfo ciQueue[2] = {
    { .sType = VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO,
      .queueFamilyIndex = deviceQueues_.graphicsQueueFamilyIndex,
      .queueCount = 1,
      .pQueuePriorities = &queuePriority, },
    { .sType = VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO,
      .queueFamilyIndex = deviceQueues_.computeQueueFamilyIndex,
      .queueCount = 1,
      .pQueuePriorities = &queuePriority, },
  };

Sometimes, especially on mobile GPUs, graphics and compute queues might be the same. Here we take care of such corner cases.
```
  const uint32_t numQueues =
    ciQueue[0].queueFamilyIndex == ciQueue[1].queueFamilyIndex ?
      1 : 2;
```
Let’s construct a list of extensions that our logical device is required to support. A device must support a swapchain object, which allows us to present rendered frames onto the screen. We use Vulkan 1.3, which includes all the necessary functionality, so no extra extensions are required. However, users can provide additional custom extensions via VulkanContextConfig::extensionsDevice[].
```
  std::vector<const char*> deviceExtensionNames = {
    VK_KHR_SWAPCHAIN_EXTENSION_NAME,
  };
  for (const char* ext : config_.extensionsDevice) {
    if (ext) deviceExtensionNames.push_back(ext);
  }
```
Let’s request all the necessary Vulkan 1.0–1.3 features we’ll be using in our Vulkan implementation. The most important features are descriptor indexing from Vulkan 1.2 and dynamic rendering from Vulkan 1.3, which we’ll discuss in subsequent chapters. Take a look at how to request these and other features we’ll be using.

Note

Descriptor indexing is a set of Vulkan 1.2 features that enable applications to access all of their resources and select among them using integer indices in shaders.

Dynamic rendering is a Vulkan 1.3 feature that allows applications to render directly into images without the need to create render pass objects or framebuffers.

  VkPhysicalDeviceFeatures deviceFeatures10 = {
      .geometryShader = vkFeatures10_.features.geometryShader,
      .sampleRateShading = VK_TRUE,
      .multiDrawIndirect = VK_TRUE,
    // ...
  };

The structures are chained together using their pNext pointers. Note how we access the vkFeatures10_ through vkFeatures13_ structures here to enable optional features only if they are actually supported by the physical device. The complete list is quite long, so we skip some parts of it here.

  VkPhysicalDeviceVulkan11Features deviceFeatures11 = {
    .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_FEATURES,
    .pNext = config_.extensionsDeviceFeatures,
    .storageBuffer16BitAccess = VK_TRUE,
    .samplerYcbcrConversion = vkFeatures11_.samplerYcbcrConversion,
    .shaderDrawParameters = VK_TRUE,
  };
  VkPhysicalDeviceVulkan12Features deviceFeatures12 = {
    .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_FEATURES,
    .pNext = &deviceFeatures11,
    .drawIndirectCount = vkFeatures12_.drawIndirectCount,
    // ...
    .descriptorIndexing = VK_TRUE,
    .shaderSampledImageArrayNonUniformIndexing = VK_TRUE,
    .descriptorBindingSampledImageUpdateAfterBind = VK_TRUE,
    .descriptorBindingStorageImageUpdateAfterBind = VK_TRUE,
    .descriptorBindingUpdateUnusedWhilePending = VK_TRUE,
    .descriptorBindingPartiallyBound = VK_TRUE,
    .descriptorBindingVariableDescriptorCount = VK_TRUE,
    .runtimeDescriptorArray = VK_TRUE,
    // ...
  };
  VkPhysicalDeviceVulkan13Features deviceFeatures13 = {
    .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES,
    .pNext = &deviceFeatures12,
    .subgroupSizeControl = VK_TRUE,
    .synchronization2 = VK_TRUE,
    .dynamicRendering = VK_TRUE,
    .maintenance4 = VK_TRUE,
  };

A few more steps before we can create the actual VkDevice object. We check our list of requested device extensions against the list of available extensions. Any missing extensions are printed into the log, and the initialization function returns. This is very convenient for debugging.

  std::string missingExtensions;
  for (const char* ext : deviceExtensionNames) {
    if (!hasExtension(ext, allDeviceExtensions))
      missingExtensions += "\n   " + std::string(ext);
  }
  if (!missingExtensions.empty()) {
    MINILOG_LOG_PROC(minilog::FatalError,
      "Missing Vulkan device extensions: %s\n",
      missingExtensions.c_str());
    return Result(Result::Code::RuntimeError);
  }

One last important thing worth mentioning before we proceed with creating a device: because some Vulkan features are mandatory for our code, we enable them unconditionally. We should check all the requested Vulkan features against the actual available features. With the help of C-macros, we can do this in a very clean way. When we’re missing some Vulkan features, this code will print a neatly formatted list of missing features, each marked with the corresponding Vulkan version. This is invaluable for debugging and makes your Vulkan backend adjustable to fit different devices.

  std::string missingFeatures;
#define CHECK_VULKAN_FEATURE(                       \
  reqFeatures, availFeatures, feature, version)     \
  if ((reqFeatures.feature == VK_TRUE) &&           \
      (availFeatures.feature == VK_FALSE))          \
        missingFeatures.append("\n   " version " ." #feature);
#define CHECK_FEATURE_1_0(feature)                               \
  CHECK_VULKAN_FEATURE(deviceFeatures10, vkFeatures10_.features, \
  feature, "1.0 ");
    CHECK_FEATURE_1_0(robustBufferAccess);
    CHECK_FEATURE_1_0(fullDrawIndexUint32);
    CHECK_FEATURE_1_0(imageCubeArray);
    … // omitted a lot of other Vulkan 1.0 features here
#undef CHECK_FEATURE_1_0
#define CHECK_FEATURE_1_1(feature)                      \
  CHECK_VULKAN_FEATURE(deviceFeatures11, vkFeatures11_, \
    feature, "1.1 ");
    CHECK_FEATURE_1_1(storageBuffer16BitAccess);
    CHECK_FEATURE_1_1(uniformAndStorageBuffer16BitAccess);
    CHECK_FEATURE_1_1(storagePushConstant16);
    … // omitted a lot of other Vulkan 1.1 features here
#undef CHECK_FEATURE_1_1
#define CHECK_FEATURE_1_2(feature)                      \
  CHECK_VULKAN_FEATURE(deviceFeatures12, vkFeatures12_, \
  feature, "1.2 ");
    CHECK_FEATURE_1_2(samplerMirrorClampToEdge);
    CHECK_FEATURE_1_2(drawIndirectCount);
    CHECK_FEATURE_1_2(storageBuffer8BitAccess);
    … // omitted a lot of other Vulkan 1.2 features here
#undef CHECK_FEATURE_1_2
#define CHECK_FEATURE_1_3(feature)                      \
  CHECK_VULKAN_FEATURE(deviceFeatures13, vkFeatures13_, \
  feature, "1.3 ");
    CHECK_FEATURE_1_3(robustImageAccess);
    CHECK_FEATURE_1_3(inlineUniformBlock);
    … // omitted a lot of other Vulkan 1.3 features here
#undef CHECK_FEATURE_1_3
  if (!missingFeatures.empty()) {
    MINILOG_LOG_PROC(minilog::FatalError,
      "Missing Vulkan features: %s\n", missingFeatures.c_str());
    return Result(Result::Code::RuntimeError);
  }

Finally, we are ready to create the Vulkan device, load all related Vulkan functions with Volk, and retrieve the actual device queues based on the queue family indices we selected earlier in this recipe.

  const VkDeviceCreateInfo ci = {
    .sType = VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO,
    .pNext = createInfoNext,
    .queueCreateInfoCount = numQueues,
    .pQueueCreateInfos = ciQueue,
    .enabledExtensionCount = deviceExtensionNames.size(),
    .ppEnabledExtensionNames = deviceExtensionNames.data(),
    .pEnabledFeatures = &deviceFeatures10,
  };
  vkCreateDevice(vkPhysicalDevice_, &ci, nullptr, &vkDevice_);
  volkLoadDevice(vkDevice_);
  vkGetDeviceQueue(vkDevice_,
    deviceQueues_.graphicsQueueFamilyIndex, 0,
    &deviceQueues_.graphicsQueue);
  vkGetDeviceQueue(vkDevice_,
    deviceQueues_.computeQueueFamilyIndex, 0,
    &deviceQueues_.computeQueue);
  // ... other code in initContext() is unrelated to this recipe
}

The VkDevice object is now ready to be used, but the initialization of the Vulkan rendering pipeline is far from complete. The next step is to create a swapchain object. Let’s proceed to the next recipe to learn how to do this.

Initializing Vulkan swapchain

Normally, each frame is rendered into an offscreen image. After the rendering process is finished, the offscreen image should be made visible or “presented.” A swapchain is an object that holds a collection of available offscreen images, or more specifically, a queue of rendered images waiting to be presented to the screen. In OpenGL, presenting an offscreen buffer to the visible area of a window is done using system-dependent functions, such as wglSwapBuffers() on Windows, eglSwapBuffers() on OpenGL ES embedded systems, glXSwapBuffers() on Linux, or automatically on macOS. Vulkan, however, gives us much more fine-grained control. We need to select a presentation mode for swapchain images and specify various flags.

In this recipe, we will show how to create a Vulkan swapchain object using the Vulkan instance and device initialized in the previous recipe.

Getting ready

Revisit the previous recipe Initializing Vulkan instance and graphical device, which covers the initial steps necessary to initialize Vulkan. The source code discussed in this recipe is implemented in the class lvk::VulkanSwapchain.

How to do it...

In the previous recipe, we began learning how Vulkan instances and devices are created by exploring the helper function lvk::createVulkanContextWithSwapchain(). This led us to the function VulkanContext::initContext(), which we discussed in detail. Let’s continue our journey by exploring VulkanContext::initSwapchain() and the related class VulkanSwapchain from LightweightVK.

First, let us take a look at a function which retrieves various surface format support capabilities and stores them in the member fields of VulkanContext. The function also checks depth format support, but only for those depth formats that might be used by LightweightVK.

void lvk::VulkanContext::querySurfaceCapabilities() {
  const VkFormat depthFormats[] = {
    VK_FORMAT_D32_SFLOAT_S8_UINT,
    VK_FORMAT_D24_UNORM_S8_UINT,
    VK_FORMAT_D16_UNORM_S8_UINT, VK_FORMAT_D32_SFLOAT,
    VK_FORMAT_D16_UNORM };
  for (const auto& depthFormat : depthFormats) {
    VkFormatProperties formatProps;
    vkGetPhysicalDeviceFormatProperties(
      vkPhysicalDevice_, depthFormat, &formatProps);
    if (formatProps.optimalTilingFeatures)
      deviceDepthFormats_.push_back(depthFormat);
  }
  if (vkSurface_ == VK_NULL_HANDLE) return;

All the surface capabilities and surface formats are retrieved and stored. First, we get the number of supported formats, then allocate the storage to hold them and read the actual properties.

  vkGetPhysicalDeviceSurfaceCapabilitiesKHR(
    vkPhysicalDevice_, vkSurface_, &deviceSurfaceCaps_);
  uint32_t formatCount;
  vkGetPhysicalDeviceSurfaceFormatsKHR(
    vkPhysicalDevice_, vkSurface_, &formatCount, nullptr);
  if (formatCount) {
    deviceSurfaceFormats_.resize(formatCount);
    vkGetPhysicalDeviceSurfaceFormatsKHR(
      vkPhysicalDevice_, vkSurface_,
      &formatCount, deviceSurfaceFormats_.data());
  }

In a similar way, store surface present modes as well.

  uint32_t presentModeCount;
  vkGetPhysicalDeviceSurfacePresentModesKHR(
    vkPhysicalDevice_, vkSurface_, &presentModeCount, nullptr);
  if (presentModeCount) {
    devicePresentModes_.resize(presentModeCount);
    vkGetPhysicalDeviceSurfacePresentModesKHR(
      vkPhysicalDevice_, vkSurface_,
      &presentModeCount, devicePresentModes_.data());
  }
}

Knowing all supported color surface formats, we can choose a suitable one for our swapchain. Let’s take a look at the chooseSwapSurfaceFormat() helper function to see how it’s done. The function takes a list of available formats and a desired color space as input.

First, it selects a preferred surface format based on the desired color space and the RGB/BGR native swapchain image format. RGB or BGR is determined by going through all available color formats returned by Vulkan and picking the one—RGB or BGR—that appears first in the list. If BGR is encountered earlier, it will be chosen. Once the preferred image format and color space are selected, the function goes through the list of supported formats to try to find an exact match. Here, colorSpaceToVkSurfaceFormat() and isNativeSwapChainBGR() are local C++ lambdas. Check the full source code to see their implementations.
```
VkSurfaceFormatKHR chooseSwapSurfaceFormat(
  const std::vector<VkSurfaceFormatKHR>& formats,
  lvk::ColorSpace colorSpace)
{
  const VkSurfaceFormatKHR preferred =
    colorSpaceToVkSurfaceFormat(
      colorSpace, isNativeSwapChainBGR(formats));
  for (const VkSurfaceFormatKHR& fmt : formats) {
    if (fmt.format == preferred.format &&
        fmt.colorSpace == preferred.colorSpace) return fmt;
  }
```
If we cannot find both a matching format and color space, try matching only the format. If we cannot match the format, default to the first available format. On many systems, it will be VK_FORMAT_R8G8B8A8_UNORM or a similar format.
```
  for (const VkSurfaceFormatKHR& fmt : formats) {
    if (fmt.format == preferred.format) return fmt;
  }
  return formats[0];
}
```

This function is called from the constructor of VulkanSwapchain. Once the format has been selected, we need to do a few more checks before we can create an actual Vulkan swapchain.

The first check is to ensure that the selected format supports presentation operation on the graphics queue family used to create the swapchain.

lvk::VulkanSwapchain::VulkanSwapchain(
  VulkanContext& ctx, uint32_t width, uint32_t height) :
  ctx_(ctx),
  device_(ctx.vkDevice_),
  graphicsQueue_(ctx.deviceQueues_.graphicsQueue),
  width_(width), height_(height)
{
  surfaceFormat_ = chooseSwapSurfaceFormat(
    ctx.deviceSurfaceFormats_, ctx.config_.swapChainColorSpace);
  VkBool32 queueFamilySupportsPresentation = VK_FALSE;
  vkGetPhysicalDeviceSurfaceSupportKHR(ctx.getVkPhysicalDevice(),
    ctx.deviceQueues_.graphicsQueueFamilyIndex, ctx.vkSurface_,
    &queueFamilySupportsPresentation));

The second check is necessary to choose usage flags for swapchain images. Usage flags define if swapchain images can be used as color attachments, in transfer operations, or as storage images to allow compute shaders to operate directly on them. Different devices have different capabilities and storage images are not always supported, especially on mobile GPUs. Here’s a C++ local lambda to do it:

auto chooseUsageFlags = [](VkPhysicalDevice pd,
  VkSurfaceKHR surface, VkFormat format) -> VkImageUsageFlags
{
  VkImageUsageFlags usageFlags =
    VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT |
    VK_IMAGE_USAGE_TRANSFER_DST_BIT |
    VK_IMAGE_USAGE_TRANSFER_SRC_BIT;
  VkSurfaceCapabilitiesKHR caps;
  vkGetPhysicalDeviceSurfaceCapabilitiesKHR(pd, surface, &caps);
  const bool isStorageSupported =
    (caps.supportedUsageFlags & VK_IMAGE_USAGE_STORAGE_BIT) > 0;
  VkFormatProperties props;
  vkGetPhysicalDeviceFormatProperties(pd, format, &props);
  const bool isTilingOptimalSupported =
    (props.optimalTilingFeatures & VK_IMAGE_USAGE_STORAGE_BIT) > 0;
  if (isStorageSupported && isTilingOptimalSupported) {
    usageFlags |= VK_IMAGE_USAGE_STORAGE_BIT;
  }
  return usageFlags;
}

Now we should select the presentation mode. The preferred presentation mode is VK_PRESENT_MODE_MAILBOX_KHR which specifies that the Vulkan presentation system should wait for the next vertical blanking period to update the current image. Visual tearing will not be observed in this case. However, this presentation mode is not guaranteed to be supported. In this situation, we can try picking VK_PRESENT_MODE_IMMEDIATE_KHR for the fastest frames-per-second without V-sync, or we can always fall back to VK_PRESENT_MODE_FIFO_KHR. The differences between all possible presentation mode are described in the Vulkan specification https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VkPresentModeKHR.html
```
auto chooseSwapPresentMode = [](
  const std::vector<VkPresentModeKHR>& modes) -> VkPresentModeKHR
{
#if defined(__linux__) || defined(_M_ARM64)
    if (std::find(modes.cbegin(), modes.cend(),
        VK_PRESENT_MODE_IMMEDIATE_KHR) != modes.cend()) {
      return VK_PRESENT_MODE_IMMEDIATE_KHR;
    }
#endif
    if (std::find(modes.cbegin(), modes.cend(),
        VK_PRESENT_MODE_MAILBOX_KHR) != modes.cend()) {
      return VK_PRESENT_MODE_MAILBOX_KHR;
    }
    return VK_PRESENT_MODE_FIFO_KHR;
  };
```

The last helper lambda we need will choose the number of images in the swapchain object. It is based on the surface capabilities we retrieved earlier. Instead of using minImageCount directly, we request one additional image to make sure we are not waiting on the GPU to complete any operations.

auto chooseSwapImageCount = [](
  const VkSurfaceCapabilitiesKHR& caps) -> uint32_t
{
  const uint32_t desired = caps.minImageCount + 1;
  const bool exceeded = caps.maxImageCount > 0 &&
                        desired > caps.maxImageCount;
  return exceeded ? caps.maxImageCount : desired;
};

Let’s go back to the constructor VulkanSwapchain::VulkanSwapchain() and explore how it uses all abovementioned helper functions to create a Vulkan swapchain object. The code here becomes rather short and consists only of filling in the VkSwapchainCreateInfoKHR structure.

  const VkImageUsageFlags usageFlags = chooseUsageFlags(
    ctx.getVkPhysicalDevice(), ctx.vkSurface_,
    surfaceFormat_.format);
  const bool isCompositeAlphaOpaqueSupported =
    (ctx.deviceSurfaceCaps_.supportedCompositeAlpha &
     VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR) != 0;
  const VkSwapchainCreateInfoKHR ci = {
    .sType = VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR,
    .surface = ctx.vkSurface_,
    .minImageCount = chooseSwapImageCount(ctx.deviceSurfaceCaps_),
    .imageFormat = surfaceFormat_.format,
    .imageColorSpace = surfaceFormat_.colorSpace,
    .imageExtent = {.width = width, .height = height},
    .imageArrayLayers = 1,
    .imageUsage = usageFlags,
    .imageSharingMode = VK_SHARING_MODE_EXCLUSIVE,
    .queueFamilyIndexCount = 1,
    .pQueueFamilyIndices = &ctx.deviceQueues_.graphicsQueueFamilyIndex,
    .preTransform = ctx.deviceSurfaceCaps_.currentTransform,
    .compositeAlpha = isCompositeAlphaOpaqueSupported ?
      VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR :
      VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR,
    .presentMode = chooseSwapPresentMode(ctx.devicePresentModes_),
    .clipped = VK_TRUE,
    .oldSwapchain = VK_NULL_HANDLE,
  };
  vkCreateSwapchainKHR(device_, &ci, nullptr, &swapchain_);

After the swapchain object has been created, we can retrieve swapchain images.

  VkImage swapchainImages[LVK_MAX_SWAPCHAIN_IMAGES];
  vkGetSwapchainImagesKHR(
    device_, swapchain_, &numSwapchainImages_, nullptr);
  if (numSwapchainImages_ > LVK_MAX_SWAPCHAIN_IMAGES) {
    numSwapchainImages_ = LVK_MAX_SWAPCHAIN_IMAGES;
  }
  vkGetSwapchainImagesKHR(
    device_, swapchain_, &numSwapchainImages_, swapchainImages);

The retrieved VkImage objects can be used to create VkImageView objects for textures and attachments. This topic will be discussed in the recipe Using texture data in Vulkan in the next chapter.

With Vulkan now initialized, we can run our first application, Chapter02/01_Swapchain, which displays an empty black window. In the next recipe, we’ll explore Vulkan’s built-in debugging capabilities to move closer to actual rendering.

Setting up Vulkan debugging capabilities

After creating a Vulkan instance, we can start monitoring all potential errors and warnings generated by the validation layers. This is done by using the VK_EXT_debug_utils extension to create a callback function and register it with the Vulkan instance. In this recipe, we’ll learn how to set up and use this feature.

Getting ready

Please revising the first recipe Initializing Vulkan instance and graphical device for details how to initialize Vulkan in your applications and enable the instance extension VK_EXT_debug_utils.

How to do it...

We have to provide a callback function to Vulkan to catch the debug output. In LightweightVK it is called vulkanDebugCallback(). Here’s how it can be passed into Vulkan to intercept logs.

Let’s create a debug messenger to forward debug messages to an application-provided callback function, vulkanDebugCallback(). This can be done right after the VkInstance object has been created.

...
vkCreateInstance(&ci, nullptr, &vkInstance_);
volkLoadInstance(vkInstance_);
const VkDebugUtilsMessengerCreateInfoEXT ci = {
  .sType =
    VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT,
  .messageSeverity =
    VK_DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT |
    VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT |
    VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT |
    VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT,
  .messageType = VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT |
                 VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT |
                 VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT,
  .pfnUserCallback = &vulkanDebugCallback,
  .pUserData = this,
};
vkCreateDebugUtilsMessengerEXT(
  vkInstance_, &ci, nullptr, &vkDebugUtilsMessenger_);

The callback code is more elaborate and can provide information about the Vulkan object causing an error or warning. However, we won’t cover tagged object allocation or associating custom data. Some performance warnings are suppressed to keep the debug output easier to read.

VKAPI_ATTR VkBool32 VKAPI_CALL vulkanDebugCallback(
  VkDebugUtilsMessageSeverityFlagBitsEXT msgSeverity,
  VkDebugUtilsMessageTypeFlagsEXT msgType,
  const VkDebugUtilsMessengerCallbackDataEXT* cbData,
  void* userData)
{
  if (msgSeverity < VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT)
    return VK_FALSE;
  const bool isError = (msgSeverity &
    VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT) != 0;
  const bool isWarning = (msgSeverity &
    VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT) != 0;
  lvk::VulkanContext* ctx = static_cast<lvk::VulkanContext*>(userData);
  minilog::eLogLevel level = minilog::Log;
  if (isError) {
    level = ctx->config_.terminateOnValidationError ?
      minilog::FatalError : minilog::Warning;
  }
  MINILOG_LOG_PROC(
    level, "%sValidation layer:\n%s\n", isError ?
    "\nERROR:\n" : "", cbData->pMessage);
  if (isError) {
    lvk::VulkanContext* ctx =
      static_cast<lvk::VulkanContext*>(userData);
    if (ctx->config_.terminateOnValidationError) {
      std::terminate();
    }
  }
  return VK_FALSE;
}

This code is enough to get you started with reading validation layer messages and debugging your Vulkan applications. Remember to destroy the validation layer callbacks just before destroying the Vulkan instance. Refer to the full source code for all the details https://github.com/corporateshark/lightweightvk/blob/master/lvk/vulkan/VulkanClasses.cpp.

There’s more…

The extension VK_EXT_debug_utils provides the ability to identify specific Vulkan objects using a textual name or tag to improve Vulkan objects tracking and debugging experience.

For example, in LightweightVK, we can assign a name to our VkDevice object.

lvk::setDebugObjectName(vkDevice_, VK_OBJECT_TYPE_DEVICE,
  (uint64_t)vkDevice_, "Device: VulkanContext::vkDevice_");

This helper function is implemented in lvk/vulkan/VulkanUtils.cpp and looks as follows:

VkResult lvk::setDebugObjectName(VkDevice device, VkObjectType type,
  uint64_t handle, const char* name)
{
  if (!name || !*name) return VK_SUCCESS;
  const VkDebugUtilsObjectNameInfoEXT ni = {
    .sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT,
    .objectType = type,
    .objectHandle = handle,
    .pObjectName = name,
  };
  return vkSetDebugUtilsObjectNameEXT(device, &ni);
}

Using Vulkan command buffers

In the previous recipes, we learned how to create a Vulkan instance, a device for rendering, and a swapchain. In this recipe, we will learn how to manage command buffers and submit them using command queues which will bring us a bit closer to rendering our first image with Vulkan.

Vulkan command buffers are used to record Vulkan commands which can be then submitted to a device queue for execution. Command buffers are allocated from pools which allow the Vulkan implementation to amortize the cost of resource creation across multiple command buffers. Command pools are be externally synchronized which means one command pool should not be used between multiple threads. Let’s learn how to make a convenient user-friendly wrapper on top of Vulkan command buffers and pools.

Getting ready…

We are going to explore the command buffers management code from the LightweightVK library. Take a look at the class VulkanImmediateCommands from lvk/vulkan/VulkanClasses.h. In the previous edition of our book, we used very rudimentary command buffers management code which did not suppose any synchronization because every frame was “synchronized” with vkDeviceWaitIdle(). Here we are going to explore a more pragmatic solution with some facilities for synchronization.

Let’s go back to our demo application from the recipe Initializing Vulkan swapchain which renders a black empty window Chapter02/01_Swapchain. The main loop of the application looks as follows:

  while (!glfwWindowShouldClose(window)) {
    glfwPollEvents();
    glfwGetFramebufferSize(window, &width, &height);
    if (!width || !height) continue;
    lvk::ICommandBuffer& buf = ctx->acquireCommandBuffer();
    ctx->submit(buf, ctx->getCurrentSwapchainTexture());
  }

Here we acquire a next command buffer and then submit it without writhing any commands into it so that LightweightVK can run its swapchain presentation code and render a black window. Let’s dive deep into the implementation and learn how lvk::VulkanImmediateCommands does all the heavy lifting behind the scenes.

How to do it...

First, we need a helper struct, SubmitHandle, to identify previously submitted command buffers. It will be essential for implementing synchronization when scheduling work that depends on the results of a previously submitted command buffer. The struct includes an internal index for the submitted buffer and an integer ID for the submission. For convenience, handles can be converted to and from 64-bit integers.

struct SubmitHandle {
  uint32_t bufferIndex_ = 0;
  uint32_t submitId_ = 0;
  SubmitHandle() = default;
  explicit SubmitHandle(uint64_t handle) :
    bufferIndex_(uint32_t(handle & 0xffffffff)),
    submitId_(uint32_t(handle >> 32)) {}
  bool empty() const { return submitId_ == 0; }
  uint64_t handle() const
  { return (uint64_t(submitId_) << 32) + bufferIndex_; }
};

Another helper struct, CommandBufferWrapper, is needed to encapsulate all Vulkan objects associated with a single Vulkan command buffer. This struct stores the originally allocated and currently active command buffers, the most recent SubmitHandle linked to the command buffer, a Vulkan fence, and a Vulkan semaphore. The fence is used for GPU-CPU synchronization, while the semaphore ensures that command buffers are processed by the GPU in the order they were submitted. This sequential processing, enforced by LightweightVK, simplifies many aspects of rendering.
```
struct CommandBufferWrapper {
  VkCommandBuffer cmdBuf_ = VK_NULL_HANDLE;
  VkCommandBuffer cmdBufAllocated_ = VK_NULL_HANDLE;
  SubmitHandle handle_ = {};
  VkFence fence_ = VK_NULL_HANDLE;
  VkSemaphore semaphore_ = VK_NULL_HANDLE;
  bool isEncoding_ = false;
};
```

Now let’s take a look at the interface of lvk::VulkanImmediateCommands.

Vulkan command buffers are preallocated and used in a round-robin manner. The maximum number of preallocated command buffers is defined by kMaxCommandBuffers. If all buffers are in use, VulkanImmediateCommands waits for an existing command buffer to become available by waiting on a fence. Typically, 64 command buffers are sufficient to ensure non-blocking operation in most cases. The constructor takes a queueFamilyIdx parameter to retrieve the appropriate Vulkan queue.
```
class VulkanImmediateCommands final {
 public:
   static constexpr uint32_t kMaxCommandBuffers = 64;
  VulkanImmediateCommands(VkDevice device,
    uint32_t queueFamilyIdx, const char* debugName);
  ~VulkanImmediateCommands();
```
The acquire() method returns a reference to the next available command buffer. If all command buffers are in use, it waits on a fence until one becomes available. The submit() method submits a command buffer to the assigned Vulkan queue.
```
  const CommandBufferWrapper& acquire();
  SubmitHandle submit(const CommandBufferWrapper& wrapper);
```
The next three methods provide GPU-GPU and GPU-CPU synchronization mechanisms. The waitSemaphore() method ensures the current command buffer waits on a given semaphore before execution. A common use case is using an “acquire semaphore” from our VulkanSwapchain object, which signals a semaphore when acquiring a swapchain image, ensuring the command buffer waits for it before starting to render into the swapchain image. The signalSemaphore() method signals a corresponding Vulkan timeline semaphore when the current command buffer finishes execution. The acquireLastSubmitSemaphore() method retrieves the semaphore signaled when the last submitted command buffer completes. This semaphore can be used by the swapchain before presentation to ensure that rendering into the image is complete. We’ll take a closer look at how this works in a moment.
```
  void waitSemaphore(VkSemaphore semaphore);
  void signalSemaphore(VkSemaphore semaphore, uint64_t signalValue);
  VkSemaphore acquireLastSubmitSemaphore();
```
The next set of methods manages GPU-CPU synchronization. As we’ll see later in this recipe, submit handles are implemented using Vulkan fences and can be used to wait for specific GPU operations to complete.
```
  SubmitHandle getLastSubmitHandle() const;
  bool isReady(SubmitHandle handle) const;
  void wait(SubmitHandle handle);
  void waitAll();
```

The private section of the class contains all the local state, including an array of preallocated CommandBufferWrapper objects called buffers_[].

 private:
  void purge();
  VkDevice device_ = VK_NULL_HANDLE;
  VkQueue queue_ = VK_NULL_HANDLE;
  VkCommandPool commandPool_ = VK_NULL_HANDLE;
  uint32_t queueFamilyIndex_ = 0;
  const char* debugName_ = "";
  CommandBufferWrapper buffers_[kMaxCommandBuffers];

Note how the VkSemaphoreSubmitInfo structures are preinitialized with generic stageMask values. For submitting Vulkan command buffers, we use the function vkQueueSubmit2() introduced in Vulkan 1.3, which requires pointers to these structures.

  VkSemaphoreSubmitInfo lastSubmitSemaphore_ = {
    .sType = VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO,
    .stageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT};
  VkSemaphoreSubmitInfo waitSemaphore_ = {
    .sType = VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO,
    .stageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT};
  VkSemaphoreSubmitInfo signalSemaphore_ = {
    .sType = VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO,
    .stageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT};
  uint32_t numAvailableCommandBuffers_ = kMaxCommandBuffers;
  uint32_t submitCounter_ = 1;
};

The VulkanImmediateCommands class is central to the entire operation of our Vulkan backend. Let’s dive into its implementation, examining each method in detail.

Let’s begin with the class constructor and destructor. The constructor preallocates all command buffers. For simplicity, error checking and debugging code will be omitted here; please refer to the LightweightVK library source code for full error-checking details.

First, we should retrieve a Vulkan device queue and allocate a command pool. The VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag is used to specify that any command buffers allocated from this pool can be individually reset to their initial state using the Vulkan function vkResetCommandBuffer(). To indicate that command buffers allocated from this pool will have a short lifespan, we use the VK_COMMAND_POOL_CREATE_TRANSIENT_BIT flag, meaning they will be reset or freed within a relatively short timeframe.

lvk::VulkanImmediateCommands::VulkanImmediateCommands(
  VkDevice device,
  uint32_t queueFamilyIndex, const char* debugName) :
  device_(device), queueFamilyIndex_(queueFamilyIndex),
  debugName_(debugName)
{
  vkGetDeviceQueue(device, queueFamilyIndex, 0, &queue_);
  const VkCommandPoolCreateInfo ci = {
      .sType = VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO,
      .flags = VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT |
               VK_COMMAND_POOL_CREATE_TRANSIENT_BIT,
      .queueFamilyIndex = queueFamilyIndex,
  };
  vkCreateCommandPool(device, &ci, nullptr, &commandPool_);

Now, we can preallocate all the command buffers from the command pool. In addition, we create one semaphore and one fence for each command buffer to enable our synchronization system.

  const VkCommandBufferAllocateInfo ai = {
      .sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO,
      .commandPool = commandPool_,
      .level = VK_COMMAND_BUFFER_LEVEL_PRIMARY,
      .commandBufferCount = 1,
  };
  for (uint32_t i = 0; i != kMaxCommandBuffers; i++) {
    CommandBufferWrapper& buf = buffers_[i];
    char fenceName[256] = {0};
    char semaphoreName[256] = {0};
    if (debugName) {
      // ... assign debug names to fenceName and semaphoreName
    }
    buf.semaphore_ = lvk::createSemaphore(device, semaphoreName);
    buf.fence_ = lvk::createFence(device, fenceName);
    vkAllocateCommandBuffers(
      device, &ai, &buf.cmdBufAllocated_);
    buffers_[i].handle_.bufferIndex_ = i;
  }
}

The destructor is almost trivial. We simply wait for all command buffers to be processed before destroying the command pool, fences, and semaphores.

lvk::VulkanImmediateCommands::~VulkanImmediateCommands() {
  waitAll();
  for (CommandBufferWrapper& buf : buffers_) {
    vkDestroyFence(device_, buf.fence_, nullptr);
    vkDestroySemaphore(device_, buf.semaphore_, nullptr);
  }
  vkDestroyCommandPool(device_, commandPool_, nullptr);
}

Now, let’s examine the implementation of our most important function acquire(). All error checking code is omitted again to keep the explanation clear and focused.

Before we can find an available command buffer, we need to ensure there is one. This busy-wait loop checks the number of currently available command buffers and calls the purge() function, which recycles processed command buffers and resets them to their initial state, until at least one buffer becomes available. In practice, this loop almost never runs.
```
const lvk::VulkanImmediateCommands::CommandBufferWrapper&
  lvk::VulkanImmediateCommands::acquire()
{
  while (!numAvailableCommandBuffers_) purge();
```
Once we know there’s at least one command buffer available, we can find it by going through the array of all buffers and selecting the first available one. At this point, we decrement numAvailableCommandBuffers to ensure proper busy-waiting on the next call to acquire(). The isEncoding member field is used to prevent the reuse of a command buffer that has already been acquired but has not yet been submitted.
```
  VulkanImmediateCommands::CommandBufferWrapper*
    current = nullptr;
  for (CommandBufferWrapper& buf : buffers_) {
    if (buf.cmdBuf_ == VK_NULL_HANDLE) {
      current = &buf;
      break;
    }
  }
  current->handle_.submitId_ = submitCounter_;
  numAvailableCommandBuffers_--;
  current->cmdBuf_ = current->cmdBufAllocated_;
  current->isEncoding_ = true;
```

After completing all the bookkeeping on our side, we can call the Vulkan API to begin recording the current command buffer.

  const VkCommandBufferBeginInfo bi = {
      .sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
      .flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT,
  };
  VK_ASSERT(vkBeginCommandBuffer(current->cmdBuf_, &bi));
  nextSubmitHandle_ = current->handle_;
  return *current;
}

Before we dive into the next series of functions, let’s take a look at a short helper function, purge(), which was mentioned earlier in acquire(). This function calls vkWaitForFences() with a Vulkan fence and a timeout value of 0, which causes it to return the current status of the fence without waiting. If the fence is signaled, we can reset the command buffer and increment numAvailableCommandBuffers. We always begin checking with the oldest submitted buffer and then wrap around.

void lvk::VulkanImmediateCommands::purge() {
  const uint32_t numBuffers = LVK_ARRAY_NUM_ELEMENTS(buffers_);
  for (uint32_t i = 0; i != numBuffers; i++) {
    const uint32_t index = i + lastSubmitHandle_.bufferIndex_+1;
    CommandBufferWrapper& buf = buffers_[index % numBuffers];
    if (buf.cmdBuf_ == VK_NULL_HANDLE || buf.isEncoding_)
      continue;
    const VkResult result =
      vkWaitForFences(device_, 1, &buf.fence_, VK_TRUE, 0);
    if (result == VK_SUCCESS) {
      vkResetCommandBuffer(
        buf.cmdBuf_, VkCommandBufferResetFlags{0});
      vkResetFences(device_, 1, &buf.fence_);
      buf.cmdBuf_ = VK_NULL_HANDLE;
      numAvailableCommandBuffers_++;
    } else {
      if (result != VK_TIMEOUT) VK_ASSERT(result);
    }
  }
}

Another crucial function is submit(), which submits a command buffer to a queue. Let’s take a look.

First, we should call vkEndCommandBuffer() to finish recording a command buffer.

SubmitHandle lvk::VulkanImmediateCommands::submit(
  const CommandBufferWrapper& wrapper) {
  vkEndCommandBuffer(wrapper.cmdBuf_);

Then we should prepare semaphores. We can set two optional semaphores to be waited on before GPU processes our command buffer. The first one is the semaphore we injected with the waitSemaphore() function. It can be an “acquire semaphore” from a swapchain or any other user-provided semaphore if we want to organize a frame graph of some sort. The second semaphore lastSubmitSemaphore_ is the semaphore signaled by a previously submitted command buffer. This ensures all command buffers are processed sequentially one by one.
```
  VkSemaphoreSubmitInfo waitSemaphores[] = {{}, {}};
  uint32_t numWaitSemaphores = 0;
  if (waitSemaphore_.semaphore)
    waitSemaphores[numWaitSemaphores++] = waitSemaphore_;
  if (lastSubmitSemaphore_.semaphore)
    waitSemaphores[numWaitSemaphores++] = lastSubmitSemaphore_;
```
The signalSemaphores[] are signaled when the command buffer finishes execution. There are two of them: The first is the one we allocated along with our command buffer and is used for chaining command buffers together. The second is an optional timeline semaphore, injected by the signalSemaphore() function. It is injected at the end of the frame, before presenting the final image to the screen, and is used to orchestrate the swapchain presentation.
```
  VkSemaphoreSubmitInfo signalSemaphores[] = {
    VkSemaphoreSubmitInfo{
      .sType = VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO,
      .semaphore = wrapper.semaphore_,
      .stageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT},
    {},
  };
  uint32_t numSignalSemaphores = 1;
  if (signalSemaphore_.semaphore) {
    signalSemaphores[numSignalSemaphores++] = signalSemaphore_;
  }
```

Once we have all the data in place, calling vkQueueSubmit2() is straightforward. We populate the VkCommandBufferSubmitInfo structure using VkCommandBuffer from the current CommandBufferWrapper object and add all the semaphores to VkSubmitInfo2, allowing us to synchronize on them during the next submit() call.

  const VkCommandBufferSubmitInfo bufferSI = {
    .sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO,
    .commandBuffer = wrapper.cmdBuf_,
  };
  const VkSubmitInfo2 si = {
    .sType = VK_STRUCTURE_TYPE_SUBMIT_INFO_2,
    .waitSemaphoreInfoCount = numWaitSemaphores,
    .pWaitSemaphoreInfos = waitSemaphores,
    .commandBufferInfoCount = 1u,
    .pCommandBufferInfos = &bufferSI,
    .signalSemaphoreInfoCount = numSignalSemaphores,
    .pSignalSemaphoreInfos = signalSemaphores,
  };
  vkQueueSubmit2(queue_, 1u, &si, wrapper.fence_);
  lastSubmitSemaphore_.semaphore = wrapper.semaphore_;
  lastSubmitHandle_ = wrapper.handle_;

Once the waitSemaphore_ and signalSemaphore_ objects have been used, they should be discarded. They are meant to be used with exactly one command buffer. The submitCounter_ variable is used to set the submitId value in the next SubmitHandle. Here’s a trick we use: a SubmitHandle is considered empty when its command buffer and submitId are both zero. A simple way to achieve this is to always skip the zero value of submitCounter, hence double incrementing when we encounter zero.
```
  waitSemaphore_.semaphore   = VK_NULL_HANDLE;
  signalSemaphore_.semaphore = VK_NULL_HANDLE;
  const_cast<CommandBufferWrapper&>(wrapper).isEncoding_ = false;
  submitCounter_++;
  if (!submitCounter_) submitCounter_++;
  return lastSubmitHandle_;
}
```

This code is already sufficient to manage command buffers in an application. However, let’s take a look at other methods of VulkanImmediateCommands that simplify working with Vulkan fences by hiding them behind SubmitHandle. The next most useful method is isReady(), which serves as our high-level equivalent of vkWaitForFences() with the timeout set to 0.

First, we perform a trivial check for an empty submit handle.

bool VulkanImmediateCommands::isReady(
  const SubmitHandle handle) const
{
  if (handle.empty()) return true;

Next, we inspect the actual command buffer wrapper and check if its command buffer has already been recycled by the purge() method we explored earlier.
```
  const CommandBufferWrapper& buf =
    buffers_[handle.bufferIndex_];
  if (buf.cmdBuf_ == VK_NULL_HANDLE) return true;
```
Another scenario occurs when a command buffer has been recycled and then reused. Reuse can only happen after the command buffer has finished execution. In this case, the submitId values would be different. Only after this comparison can we invoke the Vulkan API to check the status of our VkFence object.
```
  if (buf.handle_.submitId_ != handle.submitId_) return true;
  return vkWaitForFences(device_, 1, &buf.fence_, VK_TRUE, 0) ==
    VK_SUCCESS;
}
```

The isReady() method provides a simple interface to Vulkan fences, which can be exposed to applications using the LightweightVK library without revealing the actual VkFence objects or the entire mechanism of how VkCommandBuffer objects are submitted and reset.

There is a pair of similar methods that allow us to wait for a specific VkFence hidden behind SubmitHandle.

The first method is wait(), and it waits for a single fence to be signaled. Two important points to mention here: We can detect a wait operation on a non-submitted command buffer using the isEncoding_ flag. Also, we call purge() at the end of the function because we are sure there is now at least one command buffer available to be reclaimed. There’s a special shortcut here: if we call wait() with an empty SubmitHandle, it will invoke vkDeviceWaitIdle(), which is often useful for debugging.
```
void lvk::VulkanImmediateCommands::wait(
  const SubmitHandle handle) {
  if (handle.empty()) {
    vkDeviceWaitIdle(device_);
    return;
  }
  if (isReady(handle)) return;
  if (!LVK_VERIFY(!buffers_[handle.bufferIndex_].isEncoding_))
    return;
  VK_ASSERT(vkWaitForFences(device_, 1,
    &buffers_[handle.bufferIndex_].fence_, VK_TRUE, UINT64_MAX));
  purge();
}
```

The second function waits for all submitted command buffers to be completed, and it is useful when we want to delete all resources, such as in the destructor. The implementation is straightforward, and we call purge() again to reclaim all completed command buffers.

void lvk::VulkanImmediateCommands::waitAll() {
  VkFence fences[kMaxCommandBuffers];
  uint32_t numFences = 0;
  for (const CommandBufferWrapper& buf : buffers_) {
    if (buf.cmdBuf_ != VK_NULL_HANDLE && !buf.isEncoding_)
      fences[numFences++] = buf.fence_;
  }
  if (numFences) VK_ASSERT(vkWaitForFences(
    device_, numFences, fences, VK_TRUE, UINT64_MAX));
  purge();
}

Those are all the details about the low-level command buffers implementation. Now, let’s take a look at how this code works together with our demo application.

How it works…

Let’s go all the way back to our demo application Chapter02/01_Swapchain and its main loop. We call the function VulkanContext::acquireCommandBuffer(), which returns a reference to a high-level interface lvk::ICommandBuffer. Then, we call VulkanContext::submit() to submit that command buffer.

  while (!glfwWindowShouldClose(window)) {
    glfwPollEvents();
    glfwGetFramebufferSize(window, &width, &height);
    if (!width || !height) continue;
    lvk::ICommandBuffer& buf = ctx->acquireCommandBuffer();
    ctx->submit(buf, ctx->getCurrentSwapchainTexture());
  }

Here’s what is going on inside those functions.

The first function VulkanContext::acquireCommandBuffer() is very simple. It stores a new lvk::CommandBuffer object inside VulkanContext and returns a referent to it. This lightweight object implements the lvk::ICommandBuffer interface and, in the constructor, just calls VulkanImmediateCommands::acquire() we explored earlier.
```
ICommandBuffer& VulkanContext::acquireCommandBuffer() {
  LVK_ASSERT_MSG(!pimpl_->currentCommandBuffer_.ctx_,
    "Cannot acquire more than 1 command buffer simultaneously");
  pimpl_->currentCommandBuffer_ = CommandBuffer(this);
  return pimpl_->currentCommandBuffer_;
}
```

The function VulkanContext::submit() is more elaborate. Besides submitting a command buffer, it takes an optional argument of a swapchain texture to be presented. For now, we will skip this part and focus only on the command buffer submission.

void VulkanContext::submit(
  const lvk::ICommandBuffer& commandBuffer, TextureHandle present) {
  vulkan::CommandBuffer* vkCmdBuffer =
    const_cast<vulkan::CommandBuffer*>(
      static_cast<const vulkan::CommandBuffer*>(&commandBuffer));
  if (present) {
    // … do proper layout transitioning for the Vulkan image
  }

If we are presenting a swapchain image to the screen, we need to signal our timeline semaphore. Our timeline semaphore orchestrates the swapchain and works as follows: There is a uint64_t frame counter VulkanSwapchain::currentFrameIndex_, which increments monotonically with each presented frame. We have a specific number of frames in the swapchain—let’s say 3 for example. Then, we can calculate different timeline signal values for each swapchain image so that we wait on these values every 3 frames. We wait for these corresponding timeline values when we want to acquire the same swapchain image the next time, before calling vkAcquireNextImageKHR(). For example, we render frame 0, and the next time we want to acquire it, we wait until the signal semaphore value reaches at least 3. Here, we call the function signalSemaphore() mentioned earlier to inject this timeline signal into our command buffer submission.
```
  const bool shouldPresent = hasSwapchain() && present;
  if (shouldPresent) {
   const uint64_t signalValue = swapchain_->currentFrameIndex_ +
                                swapchain_->getNumSwapchainImages();
    swapchain_->timelineWaitValues_[
      swapchain_->currentImageIndex_] = signalValue;
    immediate_->signalSemaphore(timelineSemaphore_, signalValue);
  }
  vkCmdBuffer->lastSubmitHandle_ =
    immediate_->submit(*vkCmdBuffer->wrapper_);
```
After submission, we retrieve the last submit semaphore and pass it into the swapchain so it can wait on it before the image to be presented is fully rendered by the GPU.
```
  if (shouldPresent) {
    swapchain_->present(
      immediate_->acquireLastSubmitSemaphore());
  }
```

Then we call abovementioned VulkanImmediateCommands::submit() and use its last submit semaphore to tell the swapchain to wait until the rendering is completed.

  vkCmdBuffer->lastSubmitHandle_ =
    immediate_->submit(*vkCmdBuffer->wrapper_);
  if (shouldPresent) {
    swapchain_->present(immediate_->acquireLastSubmitSemaphore());
  }

On every submit operation, we process so-called deferred tasks. Our deferred task is an std::packaged_task that should only be run when an associated SubmitHandle, also known as VkFence, is ready. This mechanism is very helpful for managing or deallocating Vulkan resources that might still be in use by the GPU, and will be discussed in subsequent chapters.
```
  processDeferredTasks();
  SubmitHandle handle = vkCmdBuffer->lastSubmitHandle_;
  pimpl_->currentCommandBuffer_ = {};
  return handle;
}
```
Last but not least, let’s take a quick look at VulkanSwapchain::getCurrentTexture() to see how vkAcquireNextImageKHR() interacts with all the aforementioned semaphores. Here, we wait on the timeline semaphore using the specific signal value for the current swapchain image, which we calculated in the code above. If you’re confused, the pattern here is that for rendering frame N, we wait for the signal value N. After submitting GPU work, we signal the value N+numSwapchainImages.
```
lvk::TextureHandle lvk::VulkanSwapchain::getCurrentTexture() {
  if (getNextImage_) {
    const VkSemaphoreWaitInfo waitInfo = {
      .sType = VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO,
      .semaphoreCount = 1,
      .pSemaphores = &ctx_.timelineSemaphore_,
      .pValues = &timelineWaitValues_[currentImageIndex_],
    };
    vkWaitSemaphores(device_, &waitInfo, UINT64_MAX);
```

Then, we can pass the corresponding acquire semaphore to vkAcquireNextImageKHR(). After this call, we pass this acquireSemaphore to VulkanImmediateCommands::waitSemaphore() so that we wait on it before submitting the next command buffer that renders into this swapchain image.

    VkSemaphore acquireSemaphore =
      acquireSemaphore_[currentImageIndex_];
    vkAcquireNextImageKHR(device_, swapchain_, UINT64_MAX,
      acquireSemaphore, VK_NULL_HANDLE, &currentImageIndex_);
    getNextImage_ = false;
    ctx_.immediate_->waitSemaphore(acquireSemaphore);
  }
  if (LVK_VERIFY(currentImageIndex_ < numSwapchainImages_))
    return swapchainTextures_[currentImageIndex_];
  return {};
}

Now we have a working subsystem to wrangle Vulkan command buffers and expose VkFence objects to user applications in a clean and straightforward way. We didn’t cover the ICommandBuffer interface in this recipe, but we will address it shortly in this chapter while working on our first Vulkan rendering demo. Before we start rendering, let’s learn how to use compiled SPIR-V shaders from the recipe Compiling Vulkan shaders at runtime in Chapter 1.

There’s more…

We recommend referring to Vulkan Cookbook by Packt for in-depth coverage of swapchain creation and command queues management.

Initializing Vulkan shader modules

The Vulkan API consumes shaders in the form of compiled SPIR-V binaries. We already learned how to compile shaders from GLSL source code to SPIR-V using the open-source glslang compiler from Khronos. In this recipe, we will learn how to use GLSL shaders and precompiled SPIR-V binaries in Vulkan.

Getting ready

We recommend reading the recipe Compiling Vulkan shaders at runtime in Chapter 1 before you proceed.

How to do it...

Let’s take a look at our next demo application, Chapter02/02_HelloTriangle, to learn the high-level LightweightVK API for shader modules. There’s a method createShaderModule() in IContext that does the work and a helper function loadShaderModule() which makes it easier to use.

The helper function loadShaderModule() is defined in shared/Utils.cpp. It detects the shader stage type from the file name extension and calls createShaderModule() with the appropriate parameters.

Holder<ShaderModuleHandle> loadShaderModule(
  const std::unique_ptr<lvk::IContext>& ctx,
  const char* fileName)
{
  const std::string code = readShaderFile(fileName);
  const lvk::ShaderStage stage =
    lvkShaderStageFromFileName(fileName);
  Holder<ShaderModuleHandle> handle =
    ctx->createShaderModule({ code.c_str(), stage,
     (std::string("Shader Module: ") + fileName).c_str() });
  return handle;
}

In this way, given a pointer to IContext, Vulkan shader modules can be created from GLSL shaders as follows, where codeVS and codeFS are null-terminated strings holding the vertex and fragment shader source code, respectively.
```
Holder<ShaderModuleHandle> vert = loadShaderModule(
  ctx, "Chapter02/02_HelloTriangle/src/main.vert");
Holder<ShaderModuleHandle> frag = loadShaderModule(
  ctx, "Chapter02/02_HelloTriangle/src/main.frag");
```

The parameter of createShaderModule() is a structure ShaderModuleDesc containing all properties required to create a Vulkan shader module. If the dataSize member field is non-zero, the data field is treated as a binary SPIR-V blob. If dataSize is zero, data is treated as a null-terminated string containing GLSL source code.

struct ShaderModuleDesc {
  ShaderStage stage = Stage_Frag;
  const char* data = nullptr;
  size_t dataSize = 0;
  const char* debugName = "";
  ShaderModuleDesc(const char* source, lvk::ShaderStage stage,
    const char* debugName) : stage(stage), data(source),
    debugName(debugName) {}
  ShaderModuleDesc(const void* data, size_t dataLength,
    lvk::ShaderStage stage, const char* debugName) :
    stage(stage), data(static_cast<const char*>(data)),
    dataSize(dataLength), debugName(debugName) {}
};

Inside VulkanContext::createShaderModule(), we handle the branching for textual GLSL and binary SPIR-V shaders. An actual VkShaderModule object is stored in a pool, which we will discuss in subsequent chapters.

struct ShaderModuleState final {
  VkShaderModule sm = VK_NULL_HANDLE;
  uint32_t pushConstantsSize = 0;
};
Holder<ShaderModuleHandle>
  VulkanContext::createShaderModule(const ShaderModuleDesc& desc)
{
  Result result;
  ShaderModuleState sm = desc.dataSize ?
    createShaderModuleFromSPIRV(
      desc.data, desc.dataSize, desc.debugName, &result) :
    createShaderModuleFromGLSL(
      desc.stage, desc.data, desc.debugName, &result); // text
  return { this, shaderModulesPool_.create(std::move(sm)) };
}

The creation of a Vulkan shader module from a binary SPIR-V blob looks as follows. Error checking is omitted for simplicity.

ShaderModuleState VulkanContext::createShaderModuleFromSPIRV(
  const void* spirv,
  size_t numBytes,
  const char* debugName,
  Result* outResult) const
{
  VkShaderModule vkShaderModule = VK_NULL_HANDLE;
  const VkShaderModuleCreateInfo ci = {
    .sType = VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO,
    .codeSize = numBytes,
    .pCode = (const uint32_t*)spirv,
  };
  vkCreateShaderModule(vkDevice_, &ci, nullptr, &vkShaderModule);

There’s one important trick here. We will need the size of push constants in the shader to initialize our Vulkan pipelines later. Here, we use the SPIRV-Reflect library to introspect the SPIR-V code and retrieve the size of the push constants from it.

  SpvReflectShaderModule mdl;
  SpvReflectResult result =
    spvReflectCreateShaderModule(numBytes, spirv, &mdl);
  LVK_ASSERT(result == SPV_REFLECT_RESULT_SUCCESS);
  SCOPE_EXIT {
    spvReflectDestroyShaderModule(&mdl);
  };
  uint32_t pushConstantsSize = 0;
  for (uint32_t i = 0; i < mdl.push_constant_block_count; ++i) {
    const SpvReflectBlockVariable& block =
      mdl.push_constant_blocks[i];
    pushConstantsSize = std::max(pushConstantsSize, block.offset + block.size);
  }
  return {
    .sm = vkShaderModule,
    .pushConstantsSize = pushConstantsSize,
  };
}

The VulkanContext::createShaderModuleFromGLSL() function invokes compileShader(), which we learned about in the recipe Compiling Vulkan shaders at runtime in Chapter 1 to create a SPIR-V binary blob. It then calls the aforementioned createShaderModuleFromSPIRV() to create an actual VkShaderModule. Before doing so, it injects a bunch of textual source code into the provided GLSL code. This is done to reduce code duplication in the shader. Things like declaring GLSL extensions and helper functions for bindless rendering are injected here. The injected code is quite large, and we will explore it step by step in subsequent chapters. For now, you can find it in lightweightvk/lvk/vulkan/VulkanClasses.cpp.
```
ShaderModuleState VulkanContext::createShaderModuleFromGLSL(
  ShaderStage stage,
  const char* source,
  const char* debugName,
  Result* outResult) const
{
  const VkShaderStageFlagBits vkStage = shaderStageToVkShaderStage(stage);
  std::string sourcePatched;
```

The automatic GLSL code injection happens only when the provided GLSL shader does not contain the #version directive. This allows you to override the code injection and provide complete GLSL shaders manually.

  if (strstr(source, "#version ") == nullptr) {
    if (vkStage == VK_SHADER_STAGE_TASK_BIT_EXT ||
        vkStage == VK_SHADER_STAGE_MESH_BIT_EXT) {
      sourcePatched += R"(
      #version 460
      #extension GL_EXT_buffer_reference : require
      // ... skipped a lot of injected code
    }
    sourcePatched += source;
    source = sourcePatched.c_str();
  }
  const glslang_resource_t glslangResource =
    lvk::getGlslangResource(
      getVkPhysicalDeviceProperties().limits);
  std::vector<uint8_t> spirv;
  const Result result = lvk::compileShader(
    vkStage, source, &spirv, &glslangResource);
  return createShaderModuleFromSPIRV(
    spirv.data(), spirv.size(), debugName, outResult);
}

Now that our Vulkan shader modules are ready to be used with Vulkan pipelines, let’s learn how to do that in the next recipe.

Initializing Vulkan pipelines

A Vulkan pipeline is an implementation of an abstract graphics pipeline, which is a sequence of operations that transform vertices and rasterize the resulting image. Essentially, it’s like a single snapshot of a “frozen” OpenGL state. Vulkan pipelines are mostly immutable, meaning multiple Vulkan pipelines should be created to allow different data paths through the graphics pipeline. In this recipe, we will learn how to create a Vulkan pipeline suitable for rendering a colorful triangle and explore how low-level and verbose Vulkan can be wrapped into a simple, high-level interface.

Getting ready...

To get all the basic information about Vulkan pipelines, we recommend reading Vulkan Cookbook by Pawel Lapinski which was published by Packt, or the Vulkan Tutorial series by Alexander Overvoorde https://vulkan-tutorial.com/Drawing_a_triangle/Graphics_pipeline_basics/Introduction.

For additional information on descriptor set layouts, check out the chapter https://vulkan-tutorial.com/Uniform_buffers/Descriptor_layout_and_buffer.

Vulkan pipelines require Vulkan shader modules. Check the previous recipe Initializing Vulkan shader modules before going through this recipe.

How to do it...

Let’s dive into how to set up a Vulkan pipeline suitable for our triangle rendering application. Due to the verbosity of the Vulkan API, this recipe will be one of the longest. We will begin with the high-level code in our demo application, Chapter02/02_HelloTriangle, and work our way through to the internals of LightweightVK down to the Vulkan API. In the following chapters, we will explore more details, such as dynamic states, multisampling, vertex input, and more.

Let’s take a look at the initialization and the main loop of Chapter02/02_HelloTriangle.

First, we create a window and a Vulkan context as described in the previous recipes.

GLFWwindow* window =
  lvk::initWindow("Simple example", width, height);
std::unique_ptr<lvk::IContext> ctx =
  lvk::createVulkanContextWithSwapchain(window, width, height, {});

Next, we need to create a rendering pipeline. LightweightVK uses opaque handles to work with resources, so lvk::RenderPipelineHandle is an opaque handle that manages a collection of VkPipeline objects, and lvk::Holder is a RAII wrapper that automatically disposes of handles when they go out of scope. The method createRenderPipeline() takes a RenderPipelineDesc structure, which contains the data necessary to configure a rendering pipeline. For our first triangle demo, we aim to keep things as minimalistic as possible, so we simply set the vertex and fragment shaders, and define the format of a color attachment. This is the absolute minimum required to render something into a swapchain image.
```
Holder<lvk::ShaderModuleHandle> vert = loadShaderModule(
  ctx, "Chapter02/02_HelloTriangle/src/main.vert");
Holder<lvk::ShaderModuleHandle> frag = loadShaderModule(
  ctx, "Chapter02/02_HelloTriangle/src/main.frag");
Holder<lvk::RenderPipelineHandle> rpTriangle =
  ctx->createRenderPipeline({
    .smVert = vert,
    .smFrag = frag,
    .color  = { { .format = ctx->getSwapchainFormat() } } });
```

Inside the main loop, we acquire a command buffer as described in the recipe Using Vulkan command buffers and issue some drawing commands.

while (!glfwWindowShouldClose(window)) {
  glfwPollEvents();
  glfwGetFramebufferSize(window, &width, &height);
  if (!width || !height) continue;
  lvk::ICommandBuffer& buf = ctx->acquireCommandBuffer();

The member function cmdBeginRendering() wraps Vulkan 1.3 dynamic rendering functionality, which enables rendering directly into Vulkan images without explicitly creating any render passes or framebuffer objects. It takes a description of a render pass lvk::RenderPass and a description of a framebuffer lvk::Framebuffer. We will explore it in more detail in subsequent chapters. Here, we use the current swapchain texture as the first color attachment and clear it to a white color before rendering using the attachment load operation LoadOp_Clear, which corresponds to VK_ATTACHMENT_LOAD_OP_CLEAR in Vulkan. The store operation is set to StoreOp_Store by default.
```
  buf.cmdBeginRendering(
    {.color = {{ .loadOp = LoadOp_Clear, .clearColor = {1,1,1,1} }}},
    {.color = {{ .texture = ctx->getCurrentSwapchainTexture() }}});
```
The render pipeline can be bound to the command buffer in one line. Then we can issue a drawing command cmdDraw(), which is a wrapper on top of vkCmdDraw(). You may have noticed that we did not use any index or vertex buffers at all. We will see why in a moment as we look into GLSL shaders. The command cmdEndRendering() corresponds to vkCmdEndRendering() from Vulkan 1.3.
```
  buf.cmdBindRenderPipeline(rpTriangle);
  buf.cmdPushDebugGroupLabel("Render Triangle", 0xff0000ff);
  buf.cmdDraw(3);
  buf.cmdPopDebugGroupLabel();
  buf.cmdEndRendering();
  ctx->submit(buf, ctx->getCurrentSwapchainTexture());
}
```

Let’s take a look at the GLSL shaders.

As we do not provide any vertex input, the vertex shader has to generate vertex data for a triangle. We use the built-in GLSL variable gl_VertexIndex, which gets incremented automatically for every subsequent vertex, to return hardcoded values for positions and vertex colors.

#version 460
layout (location=0) out vec3 color;
const vec2 pos[3] = vec2[3](
  vec2(-0.6, -0.4), vec2(0.6, -0.4), vec2(0.0, 0.6) );
const vec3 col[3] = vec3[3](
  vec3(1.0, 0.0, 0.0), vec3(0.0, 1.0, 0.0), vec3(0.0, 0.0, 1.0) );
void main() {
  gl_Position = vec4(pos[gl_VertexIndex], 0.0, 1.0);
  color = col[gl_VertexIndex];
}

The GLSL fragment shader is trivial and just outputs the interpolated fragment color.

#version 460
layout (location=0) in vec3 color;
layout (location=0) out vec4 out_FragColor;
void main() {
  out_FragColor = vec4(color, 1.0);
}

The application should render a colorful triangle as in the following picture.

Figure 2.2: Hello Triangle

We learned how to draw a triangle with Vulkan using LightweightVK. It is time to look under the hood and find out how this high-level render pipeline management interface is implemented via Vulkan.

How it works…

To get to the underlying Vulkan implementation, we have to peel a few layers one by one. When we want to create a graphics pipeline in our application, we call the member function IContext::createRenderPipeline() which is implemented in VulkanContext. This function takes in a structure lvk::RenderPipelineDesc which describes our rendering pipeline. Let’s take a closer look at it.

The structure contains a subset of information necessary to create a valid graphics VkPipeline object. It starts with the topology and vertex input descriptions, followed by shader modules for all supported shader stages. While LightweightVK supports mesh shaders, in this book, we will use only vertex, fragment, geometry, and tessellation shaders.
```
struct RenderPipelineDesc final {
  Topology topology = Topology_Triangle;
  VertexInput vertexInput;
  ShaderModuleHandle smVert;
  ShaderModuleHandle smTesc;
  ShaderModuleHandle smTese;
  ShaderModuleHandle smGeom;
  ShaderModuleHandle smTask;
  ShaderModuleHandle smMesh;
  ShaderModuleHandle smFrag;
```

Specialization constants allow Vulkan shader modules to be specialized after their compilation, at the pipeline creation time. We will demonstrate how to use them in the next chapter.

  SpecializationConstantDesc specInfo = {};
  const char* entryPointVert = "main";
  const char* entryPointTesc = "main";
  const char* entryPointTese = "main";
  const char* entryPointGeom = "main";
  const char* entryPointTask = "main";
  const char* entryPointMesh = "main";
  const char* entryPointFrag = "main";

The maximum number of color attachments is set to 8. We do not store the number of used attachments here. Instead, we use a short helper function to calculate how many attachments we actually have.

  ColorAttachment color[LVK_MAX_COLOR_ATTACHMENTS] = {};
  uint32_t getNumColorAttachments() const {
    uint32_t n = 0;
    while (n < LVK_MAX_COLOR_ATTACHMENTS &&
      color[n].format != Format_Invalid) n++;
    return n;
  }

Other member fields represent a typical rendering state with a cull mode, face winding, polygon mode, and so on.

  Format depthFormat = Format_Invalid;
  Format stencilFormat = Format_Invalid;
  CullMode cullMode = lvk::CullMode_None;
  WindingMode frontFaceWinding = lvk::WindingMode_CCW;
  PolygonMode polygonMode = lvk::PolygonMode_Fill;
  StencilState backFaceStencil = {};
  StencilState frontFaceStencil = {};
  uint32_t samplesCount = 1u;
  uint32_t patchControlPoints = 0;
  float minSampleShading = 0.0f;
  const char* debugName = "";
};

When we call VulkanContext::createRenderPipeline(), it performs sanity checks on RenderPipelineDesc and stores all the values in the RenderPipelineState struct. LightweightVK pipelines cannot be directly mapped one-to-one to VkPipeline objects because the actual VkPipeline objects have to be created lazily. For example, LightweightVK manages Vulkan descriptor set layouts automatically. Vulkan requires a descriptor set layout to be specified for a pipeline object. To address this, the data stored in RenderPipelineState is used to lazily create actual VkPipeline objects through the function VulkanContext::getVkPipeline(). Let’s take a look at how this mechanism works, with error checking and some minor details omitted for simplicity.

The RenderPipelineState structure contains some precached values to avoid reinitializing them every time a new Vulkan pipeline object is created. All shader modules must remain alive as long as any pipeline that uses them is still in use.

class RenderPipelineState final {
  RenderPipelineDesc desc_;
  uint32_t numBindings_ = 0;
  uint32_t numAttributes_ = 0;
  VkVertexInputBindingDescription
    vkBindings_[VertexInput::LVK_VERTEX_BUFFER_MAX] = {};
  VkVertexInputAttributeDescription
    vkAttributes_[VertexInput::LVK_VERTEX_ATTRIBUTES_MAX] = {};
  VkDescriptorSetLayout lastVkDescriptorSetLayout_ =
    VK_NULL_HANDLE;
  VkShaderStageFlags shaderStageFlags_ = 0;

Each RenderPipelineState owns a pipeline layout, a pipeline, and memory storage for specialization constants.

  VkPipelineLayout pipelineLayout_ = VK_NULL_HANDLE;
  VkPipeline pipeline_ = VK_NULL_HANDLE;
  void* specConstantDataStorage_ = nullptr;
};

With all data structures in place, we are now ready to go through the implementation of VulkanContext::createRenderPipeline(). Most of the error checking code is skipped for the sake of brevity.

The constructor iterates over vertex input attributes, and precaches all necessary data into Vulkan structures for further use.

Holder<RenderPipelineHandle> VulkanContext::createRenderPipeline(
  const RenderPipelineDesc& desc, Result* outResult)
{
  const bool hasColorAttachments =
    desc.getNumColorAttachments() > 0;
  const bool hasDepthAttachment =
    desc.depthFormat != Format_Invalid;
  const bool hasAnyAttachments =
    hasColorAttachments || hasDepthAttachment;
  if (!LVK_VERIFY(hasAnyAttachments)) return {};
  if (!LVK_VERIFY(desc.smVert.valid())) return {};
  if (!LVK_VERIFY(desc.smFrag.valid())) return {};
  RenderPipelineState rps = {.desc_ = desc};

Iterate and cache vertex input bindings and attributes. Vertex buffer bindings are tracked in bufferAlreadyBound. Everything else is a very trivial conversion code from our high-level data structures to Vulkan.

  const lvk::VertexInput& vstate = rps.desc_.vertexInput;
  bool bufferAlreadyBound[LVK_VERTEX_BUFFER_MAX] = {};
  rps.numAttributes_ = vstate.getNumAttributes();
  for (uint32_t i = 0; i != rps.numAttributes_; i++) {
    const VertexInput::VertexAttribute& attr = vstate.attributes[i];
    rps.vkAttributes_[i] = { .location = attr.location,
                             .binding = attr.binding,
                             .format =
                               vertexFormatToVkFormat(attr.format),
                             .offset = (uint32_t)attr.offset };
    if (!bufferAlreadyBound[attr.binding]) {
      bufferAlreadyBound[attr.binding] = true;
      rps.vkBindings_[rps.numBindings_++] = {
        .binding = attr.binding,
        .stride = vstate.inputBindings[attr.binding].stride,
        .inputRate = VK_VERTEX_INPUT_RATE_VERTEX };
    }
  }

If specialization constants data is provided, copy it out of RenderPipelineDesc into local memory storage owned by the pipeline. This simplifies RenderPipelineDesc management on the application side, allowing it to be destroyed after the pipeline is created.

  if (desc.specInfo.data && desc.specInfo.dataSize) {
    rps.specConstantDataStorage_ =
      malloc(desc.specInfo.dataSize);
    memcpy(rps.specConstantDataStorage_,
      desc.specInfo.data, desc.specInfo.dataSize);
    rps.desc_.specInfo.data = rps.specConstantDataStorage_;
  }
  return {this, renderPipelinesPool_.create(std::move(rps))};
}

Now we can create actual Vulkan pipelines. Well, almost. A couple of very long code snippets await us. These are the longest functions in the entire book, but we have to go through them at least once. Though, error checking is skipped to simplify things a bit.

The getVkPipeline() functions retrieves a RenderPipelineState struct from a pool using a provided pipeline handle.

VkPipeline VulkanContext::getVkPipeline(
  RenderPipelineHandle handle)
{
  lvk::RenderPipelineState* rps =
    renderPipelinesPool_.get(handle);
  if (!rps) return VK_NULL_HANDLE;

Then we check if the descriptor set layout used to create a pipeline layout for this VkPipeline object has changed. Our implementation uses Vulkan descriptor indexing to manage all textures in a large descriptor set and creates a descriptor set layout to store them. When new textures are created, there might not be enough space to store them, requiring the creation of a new descriptor set layout. Every time this happens, we have to delete the old VkPipeline and VkPipelineLayout objects and create new ones.

  if (rps->lastVkDescriptorSetLayout_ != vkDSL_) {
    deferredTask(std::packaged_task<void()>(
      [device = getVkDevice(), pipeline = rps->pipeline_]() {
        vkDestroyPipeline(device, pipeline, nullptr); }));
    deferredTask(std::packaged_task<void()>(
      [device = getVkDevice(), layout = rps->pipelineLayout_]() {
        vkDestroyPipelineLayout(device, layout, nullptr); }));
    rps->pipeline_ = VK_NULL_HANDLE;
    rps->lastVkDescriptorSetLayout_ = vkDSL_;
  }

If there is already a valid Vulkan graphics pipeline compatible with the current descriptor set layout, we can simply return it.
```
  if (rps->pipeline_ != VK_NULL_HANDLE) {
    return rps->pipeline_;
  }
```

Let’s prepare to build a new Vulkan pipeline object. We need to create color blend attachments only for active color attachments. Helper functions, such as formatToVkFormat(), convert LightweightVK enumerations to Vulkan.

  VkPipelineLayout layout = VK_NULL_HANDLE;
  VkPipeline pipeline = VK_NULL_HANDLE;
  const RenderPipelineDesc& desc = rps->desc_;
  const uint32_t numColorAttachments =
    desc_.getNumColorAttachments();
  VkPipelineColorBlendAttachmentState
    colorBlendAttachmentStates[LVK_MAX_COLOR_ATTACHMENTS] = {};
  VkFormat colorAttachmentFormats[LVK_MAX_COLOR_ATTACHMENTS] ={};
  for (uint32_t i = 0; i != numColorAttachments; i++) {
    const lvk::ColorAttachment& attachment = desc_.color[i];
    colorAttachmentFormats[i] =
      formatToVkFormat(attachment.format);

Setting up blending states for color attachments is tedious but very simple.

    if (!attachment.blendEnabled) {
      colorBlendAttachmentStates[i] =
        VkPipelineColorBlendAttachmentState{
          .blendEnable = VK_FALSE,
          .srcColorBlendFactor = VK_BLEND_FACTOR_ONE,
          .dstColorBlendFactor = VK_BLEND_FACTOR_ZERO,
          .colorBlendOp = VK_BLEND_OP_ADD,
          .srcAlphaBlendFactor = VK_BLEND_FACTOR_ONE,
          .dstAlphaBlendFactor = VK_BLEND_FACTOR_ZERO,
          .alphaBlendOp = VK_BLEND_OP_ADD,
          .colorWriteMask = VK_COLOR_COMPONENT_R_BIT |
                            VK_COLOR_COMPONENT_G_BIT |
                            VK_COLOR_COMPONENT_B_BIT |
                            VK_COLOR_COMPONENT_A_BIT,
      };
    } else {
      colorBlendAttachmentStates[i] =
        VkPipelineColorBlendAttachmentState{
          .blendEnable = VK_TRUE,
          .srcColorBlendFactor = blendFactorToVkBlendFactor(
            attachment.srcRGBBlendFactor),
          .dstColorBlendFactor = blendFactorToVkBlendFactor(
            attachment.dstRGBBlendFactor),
          .colorBlendOp = blendOpToVkBlendOp(attachment.rgbBlendOp),
          .srcAlphaBlendFactor = blendFactorToVkBlendFactor(
            attachment.srcAlphaBlendFactor),
          .dstAlphaBlendFactor = blendFactorToVkBlendFactor(
            attachment.dstAlphaBlendFactor),
          .alphaBlendOp =
            blendOpToVkBlendOp(attachment.alphaBlendOp),
          .colorWriteMask = VK_COLOR_COMPONENT_R_BIT |
                            VK_COLOR_COMPONENT_G_BIT |
                            VK_COLOR_COMPONENT_B_BIT |
                            VK_COLOR_COMPONENT_A_BIT,
      };
    }
  }

Retrieve VkShaderModule objects from the pool using opaque handles. We will discuss how pools work in the next chapters. Here all we have to know is that they allow fast conversion of an integer handle into the actual data associated with it. The geometry shader is optional. We skip all other shaders here for the sake of brevity.
```
  const VkShaderModule* vert =
    ctx_->shaderModulesPool_.get(desc_.smVert);
  const VkShaderModule* geom =
    ctx_->shaderModulesPool_.get(desc_.smGeom);
  const VkShaderModule* frag =
    ctx_->shaderModulesPool_.get(desc_.smFrag);
```

Prepare the vertex input state.

  const VkPipelineVertexInputStateCreateInfo ciVertexInputState =
  {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_STATE_CREATE_INFO,
    .vertexBindingDescriptionCount = rps->numBindings_,
    .pVertexBindingDescriptions = rps->numBindings_ ?
      rps->vkBindings_ : nullptr,
    .vertexAttributeDescriptionCount = rps->numAttributes_,
    .pVertexAttributeDescriptions =
      rps->numAttributes_ ? rps->vkAttributes_ : nullptr,
  };

Populate the VkSpecializationInfo structure to describe specialization constants for this graphics pipeline.

  VkSpecializationMapEntry
    entries[LVK_SPECIALIZATION_CONSTANTS_MAX] = {};
  const VkSpecializationInfo si =
    lvk::getPipelineShaderStageSpecializationInfo(
      desc.specInfo, entries);

Create a suitable VkPipelineLayout object for this pipeline. Use the current descriptor set layout stored in VulkanContext. Here one descriptor set layout vkDSL_ is duplicated multiple times to create a pipeline layout. This is necessary to ensure compatibility with MoltenVK which does not allow aliasing of different descriptor types. Push constant sizes are retrieved from precompiled shader modules as was described in the previous recipe Initializing Vulkan shader modules.

    const VkDescriptorSetLayout dsls[] =
      { vkDSL_, vkDSL_, vkDSL_, vkDSL_ };
    const VkPushConstantRange range = {
      .stageFlags = rps->shaderStageFlags_,
      .offset = 0,
      .size = pushConstantsSize,
    };
    const VkPipelineLayoutCreateInfo ci = {
      .sType = VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO,
      .setLayoutCount = (uint32_t)LVK_ARRAY_NUM_ELEMENTS(dsls),
      .pSetLayouts = dsls,
      .pushConstantRangeCount = pushConstantsSize ? 1u : 0u,
      .pPushConstantRanges = pushConstantsSize ? &range:nullptr,
  };
  vkCreatePipelineLayout(vkDevice_, &ci, nullptr, &layout);

More information

Here’s a snippet to retrieve precalculated push constant sizes from shader modules:

#define UPDATE_PUSH_CONSTANT_SIZE(sm, bit) if (sm) { \
  pushConstantsSize = std::max(pushConstantsSize,    \
  sm->pushConstantsSize);                            \
  rps->shaderStageFlags_ |= bit; }
rps->shaderStageFlags_ = 0;
uint32_t pushConstantsSize = 0;
UPDATE_PUSH_CONSTANT_SIZE(vertModule,
  VK_SHADER_STAGE_VERTEX_BIT);
UPDATE_PUSH_CONSTANT_SIZE(tescModule,
  VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT);
UPDATE_PUSH_CONSTANT_SIZE(teseModule,
  VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT);
UPDATE_PUSH_CONSTANT_SIZE(geomModule,
  VK_SHADER_STAGE_GEOMETRY_BIT);
UPDATE_PUSH_CONSTANT_SIZE(fragModule,
  VK_SHADER_STAGE_FRAGMENT_BIT);
#undef UPDATE_PUSH_CONSTANT_SIZE

As we peel more and more implementation layers, here is yet another level to peel. However, it is the last one. For convenience, the creation of actual VkPipeline objects is encapsulated in VulkanPipelineBuilder, which provides reasonable default values for all the numerous Vulkan data members that we do not want to set. Those familiar with Java will recognize a typical Builder design pattern here.

  lvk::vulkan::VulkanPipelineBuilder()
      // from Vulkan 1.0
      .dynamicState(VK_DYNAMIC_STATE_VIEWPORT)
      .dynamicState(VK_DYNAMIC_STATE_SCISSOR)
      .dynamicState(VK_DYNAMIC_STATE_DEPTH_BIAS)
      .dynamicState(VK_DYNAMIC_STATE_BLEND_CONSTANTS)
      // from Vulkan 1.3
      .dynamicState(VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE)
      .dynamicState(VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE)
      .dynamicState(VK_DYNAMIC_STATE_DEPTH_COMPARE_OP)
      .dynamicState(VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE)
      .primitiveTopology(
        topologyToVkPrimitiveTopology(desc.topology))
      .rasterizationSamples(
        getVulkanSampleCountFlags(desc.samplesCount,
          getFramebufferMSAABitMask()), desc.minSampleShading)
      .polygonMode(polygonModeToVkPolygonMode(desc_.polygonMode))
      .stencilStateOps(VK_STENCIL_FACE_FRONT_BIT,
        stencilOpToVkStencilOp(desc_.frontFaceStencil.stencilFailureOp),
        stencilOpToVkStencilOp(desc_.frontFaceStencil.depthStencilPassOp),
        stencilOpToVkStencilOp(desc_.frontFaceStencil.depthFailureOp),
        compareOpToVkCompareOp(desc_.frontFaceStencil.stencilCompareOp))
      .stencilStateOps(VK_STENCIL_FACE_BACK_BIT,
        stencilOpToVkStencilOp(desc_.backFaceStencil.stencilFailureOp),
        stencilOpToVkStencilOp(desc_.backFaceStencil.depthStencilPassOp),
        stencilOpToVkStencilOp(desc_.backFaceStencil.depthFailureOp),
        compareOpToVkCompareOp(desc_.backFaceStencil.stencilCompareOp))
      .stencilMasks(VK_STENCIL_FACE_FRONT_BIT, 0xFF,
        desc_.frontFaceStencil.writeMask,
        desc_.frontFaceStencil.readMask)
      .stencilMasks(VK_STENCIL_FACE_BACK_BIT, 0xFF,
        desc_.backFaceStencil.writeMask,
        desc_.backFaceStencil.readMask)

Shader modules are provided one by one. Only the vertex and fragment shaders are mandatory. We skip the other shaders for the sake of brevity.

      .shaderStage(lvk::getPipelineShaderStageCreateInfo(
        VK_SHADER_STAGE_VERTEX_BIT,
        vertModule->sm, desc.entryPointVert, &si))
      .shaderStage(lvk::getPipelineShaderStageCreateInfo(
        VK_SHADER_STAGE_FRAGMENT_BIT,
        fragModule->sm, desc.entryPointFrag, &si))
      .shaderStage(geomModule ?
        lvk::getPipelineShaderStageCreateInfo(
          VK_SHADER_STAGE_GEOMETRY_BIT,
          geomModule->sm, desc.entryPointGeom, &si) :
        VkPipelineShaderStageCreateInfo{ .module = VK_NULL_HANDLE } )
      .cullMode(cullModeToVkCullMode(desc_.cullMode))
      .frontFace(windingModeToVkFrontFace(desc_.frontFaceWinding))
      .vertexInputState(vertexInputStateCreateInfo_)
      .colorAttachments(colorBlendAttachmentStates,
        colorAttachmentFormats, numColorAttachments)
      .depthAttachmentFormat(formatToVkFormat(desc.depthFormat))
      .stencilAttachmentFormat(formatToVkFormat(desc.stencilFormat))
      .patchControlPoints(desc.patchControlPoints)

Finally, we call the VulkanPipelineBuilder::build() method, which creates a VkPipeline object and we can store it in our RenderPipelineState structure together with the pipeline layout.
```
      .build(vkDevice_, pipelineCache_, layout, &pipeline, desc.debugName);
  rps->pipeline_ = pipeline;
  rps->pipelineLayout_ = layout;
  return pipeline;
}
```

The last method we want to explore here is VulkanPipelineBuilder::build() which is pure Vulkan. Let’s take a look at it to conclude the pipeline creation process.

First, we put provided dynamic states into VkPipelineDynamicStateCreateInfo.

VkResult VulkanPipelineBuilder::build(
  VkDevice device,
  VkPipelineCache pipelineCache,
  VkPipelineLayout pipelineLayout,
  VkPipeline* outPipeline,
  const char* debugName)
{
  const VkPipelineDynamicStateCreateInfo dynamicState = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO,
    .dynamicStateCount = numDynamicStates_,
    .pDynamicStates = dynamicStates_,
  };

The Vulkan specification says viewport and scissor can be nullptr if the viewport and scissor states are dynamic. We are definitely happy to make the most of this opportunity.

  const VkPipelineViewportStateCreateInfo viewportState = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_STATE_CREATE_INFO,
    .viewportCount = 1,
    .pViewports = nullptr,
    .scissorCount = 1,
    .pScissors = nullptr,
  };

Use the color blend states and attachments we prepared earlier in this recipe. The VkPipelineRenderingCreateInfo is necessary for the Vulkan 1.3 dynamic rendering feature.

  const VkPipelineColorBlendStateCreateInfo colorBlendState = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_STATE_CREATE_INFO,
    .logicOpEnable = VK_FALSE,
    .logicOp = VK_LOGIC_OP_COPY,
    .attachmentCount = numColorAttachments_,
    .pAttachments = colorBlendAttachmentStates_,
  };
  const VkPipelineRenderingCreateInfo renderingInfo = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO_KHR,
    .colorAttachmentCount = numColorAttachments_,
    .pColorAttachmentFormats = colorAttachmentFormats_,
    .depthAttachmentFormat   = depthAttachmentFormat_,
    .stencilAttachmentFormat = stencilAttachmentFormat_,
  };

Put everything together into VkGraphicsPipelineCreateInfo and call vkCreateGraphicsPipelines().

  const VkGraphicsPipelineCreateInfo ci = {
    .sType = VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO,
    .pNext = &renderingInfo,
    .flags = 0,
    .stageCount = numShaderStages_,
    .pStages = shaderStages_,
    .pVertexInputState = &vertexInputState_,
    .pInputAssemblyState = &inputAssembly_,
    .pTessellationState = &tessellationState_,
    .pViewportState = &viewportState,
    .pRasterizationState = &rasterizationState_,
    .pMultisampleState = &multisampleState_,
    .pDepthStencilState = &depthStencilState_,
    .pColorBlendState = &colorBlendState,
    .pDynamicState = &dynamicState,
    .layout = pipelineLayout,
    .renderPass = VK_NULL_HANDLE,
    .subpass = 0,
    .basePipelineHandle = VK_NULL_HANDLE,
    .basePipelineIndex = -1,
  };
  vkCreateGraphicsPipelines(
    device, pipelineCache, 1, &ci, nullptr, outPipeline);
  numPipelinesCreated_++;
}

This code concludes the pipeline creation process. In addition to the very simple example in Chapter02/02_HelloTriangle, we created a slightly more elaborate app in Chapter02/03_GLM to demonstrate how to use multiple render pipelines to render a rotating cube with a wireframe overlay. This app uses the GLM library for matrix math. You can check it out in Chapter02/03_GLM/src/main.cpp, where it uses cmdPushConstants() to animate the cube and specialization constants to use the same set of shaders for both solid and wireframe rendering. It should look as shown in the following screenshot.

Figure 2.3: GLM usage example

There’s more…

If you are familiar with older versions of Vulkan, you might have noticed that in this recipe we completely left out any references to render passes. They are also not mentioned in any of the data structures. The reason for that is that we use Vulkan 1.3 dynamic rendering functionality, which allows VkPipeline objects to operate without needing a render pass.

In case you want to implement a similar wrapper for older versions of Vulkan and without using the VK_KHR_dynamic_rendering extension, you can maintain a “global” collection of render passes in an array inside VulkanContext and add an integer index of a corresponding render pass as a data member to RenderPipelineDynamicState. Since we can use only a very restricted number of distinct rendering passes — let’s say a maximum of 256 — the index can be saved as uint8_t. This would enable us to store them in array inside VulkanContext.

If you want to explore an actual working implementation of this approach, take a look at Meta’s IGL library https://github.com/facebook/igl/blob/main/src/igl/vulkan/RenderPipelineState.h and check out how renderPassIndex is handled there.

Now let’s jump to the next Chapter 3 to learn how to use Vulkan in a user-friendly way to build more interesting examples.