Refactor: modernize Vulkan tutorial with RAII and dynamic rendering

Simplified examples by updating to RAII patterns for Vulkan-Hpp bindings. Added dynamic rendering to replace render pass and framebuffer usage, aligning with Vulkan 1.3+. Improved code readability with structured initialization and fixed typos in documentation.

Author: gpx1000

en/03_Drawing_a_triangle/00_Setup/00_Base_code.adoc

@@ -5,7 +5,7 @@
 == General structure
 
 In the previous chapter, you've created a Vulkan project with all the proper
-configuration and tested it with the sample code. In this chapter, we're starting
+ configurations and tested it with the sample code. In this chapter, we're starting
 from scratch with the following code:
 
 [,c++]
@@ -143,14 +143,34 @@ can be directly replaced by this:
         vk::raii::instance = std::make_unique<vk::raii::Instance>(context, createInfo);
 ----
 
+As this can be a little hard to read when we look at the structures.  We have
+ opted to turn on VULKAN_HPP_NO_STRUCT_CONSTRUCTORS.  This option means that
+ the above code will look like this throughout the tutorial:
+
+[,c++]
+----
+    constexpr vk::ApplicationInfo appInfo{ .pApplicationName   = "Hello Triangle",
+        .applicationVersion = VK_MAKE_VERSION( 1, 0, 0 ),
+        .pEngineName        = "No Engine",
+        .engineVersion      = VK_MAKE_VERSION( 1, 0, 0 ),
+        .apiVersion         = vk::ApiVersion14 };
+    vk::InstanceCreateInfo createInfo{
+        .pApplicationInfo = &appInfo
+    };
+    instance = vk::raii::Instance(context, createInfo);
+----
+
+This provides a better meaning towards what each option relates to in the
+structures that we're depending upon.
+
 == Integrating GLFW
 
 Vulkan works perfectly fine without creating a window if you want to use it for
 off-screen rendering, but it's a lot more exciting to actually show something!
 First, let's add GLFW: NB: we will continue to use the GLFW_INCLUDE_VULKAN as
 GLFW is designed to get a Vulkan Surface, but it uses the C surface directly.
 Other than that task, we can use GLFW_INCLUDE_NONE or not make that
-specification and everything else works perfectly fine.
+specification, and everything else works perfectly fine.
 
 [,c++]
 ----

en/03_Drawing_a_triangle/00_Setup/01_Instance.adoc

@@ -38,7 +38,11 @@ certain special behavior). This struct is called `VkApplicationInfo`:
 [,c++]
 ----
 void createInstance() {
-    constexpr auto appInfo = vk::ApplicationInfo("Hello Triangle", 1, "No  Engine", 1, vk::ApiVersion14);
+    constexpr vk::ApplicationInfo appInfo{ .pApplicationName   = "Hello Triangle",
+            .applicationVersion = VK_MAKE_VERSION( 1, 0, 0 ),
+            .pEngineName        = "No Engine",
+            .engineVersion      = VK_MAKE_VERSION( 1, 0, 0 ),
+            .apiVersion         = vk::ApiVersion14 };
 }
 ----
 
@@ -58,7 +62,9 @@ device, which will become clear in the next few chapters.
 
 [,c++]
 ----
-vk::InstanceCreateInfo createInfo({}, &appInfo, {}, {});
+vk::InstanceCreateInfo createInfo{
+    .pApplicationInfo = &appInfo
+};
 ----
 
 The first parameter is the flags for the structure, the second is the
@@ -76,12 +82,14 @@ const char** glfwExtensions;
 
 glfwExtensions = glfwGetRequiredInstanceExtensions(&glfwExtensionCount);
 
-vk::InstanceCreateInfo createInfo({}, &appInfo, {}, glfwExtensions);
+vk::InstanceCreateInfo createInfo{
+    .pApplicationInfo = &appInfo,
+    .ppEnabledLayerNames = glfwExtensions};
 ----
 
 The other missing piece is the Layers to enable. Here is where we'll talk
 about how to enable validation layers, which is one of the most useful and
-important layers to enable for any project. We'll talk about these more
+important layers to enable for any project. We'll talk about this more
 in-depth in the next chapter, so leave this empty for now.
 
 We've now specified everything Vulkan needs to create an instance, and we can
@@ -160,8 +168,16 @@ Typically, the code could be like this:
 
 [,c++]
 ----
-constexpr auto appInfo = vk::ApplicationInfo("Hello Triangle", 1, "No Engine", 1, vk::ApiVersion11);
-vk::InstanceCreateInfo createInfo(vk::InstanceCreateFlagBits::eEnumeratePortabilityKHR, &appInfo, {}, { vk::KHRPortabilityEnumerationExtensionName });
+constexpr vk::ApplicationInfo appInfo{ .pApplicationName   = "Hello Triangle",
+            .applicationVersion = VK_MAKE_VERSION( 1, 0, 0 ),
+            .pEngineName        = "No Engine",
+            .engineVersion      = VK_MAKE_VERSION( 1, 0, 0 ),
+            .apiVersion         = vk::ApiVersion14 };
+vk::InstanceCreateInfo createInfo{
+    .flas = vk::InstanceCreateFlagBits::eEnumeratePortabilityKHR,
+    .pApplicationInfo = &appInfo,
+    .ppEnabledExtensionNames = { vk::KHRPortabilityEnumerationExtensionName }
+};
 instance = std::make_unique<vk::raii::Instance>(context, createInfo);
 ----
 
@@ -175,7 +191,7 @@ what if we want to check for optional functionality?
 
 To retrieve a list of supported extensions before creating an instance, there's
 the `vkEnumerateInstanceExtensionProperties` function. We can call it on the
-context object; it returns a vector of the extensions available which
+context object; it returns a vector of the extensions available, which
 allows us to filter extensions by a specific validation layer, which we'll
 ignore for now.
 

en/03_Drawing_a_triangle/00_Setup/02_Validation_layers.adoc

@@ -20,7 +20,7 @@ layers are optional components that hook into Vulkan function calls to apply
 additional operations. Common operations in validation layers are:
 
 * Checking the values of parameters against the specification to detect misuse
-* Tracking creation and destruction of objects to find resource leaks
+* Tracking the creation and destruction of objects to find resource leaks
 * Checking thread safety by tracking the threads that calls originate from
 * Logging every call and its parameters to the standard output
 * Tracing Vulkan calls for profiling and replaying

en/03_Drawing_a_triangle/00_Setup/03_Physical_devices_and_queue_families.adoc

@@ -157,13 +157,47 @@ You don't need to implement all that for this tutorial, but it's to give you an
 idea of how you could design your device selection process. Of course, you can
 also display the names of the choices and allow the user to select.
 
-Because we're just starting out, Vulkan support is the only thing we need, and
-therefore we'll settle for just any GPU:
+Because we're just starting out, Vulkan 1.3 support is the only thing we need,
+ and therefore we'll search for that and the extensions that we actually are
+ going to be demonstrating:
 
 [,c++]
 ----
+std::vector<const char*> deviceExtensions = {
+    vk::KHRSwapchainExtensionName,
+    vk::KHRSpirv14ExtensionName,
+    vk::KHRSynchronization2ExtensionName,
+    vk::KHRCreateRenderpass2ExtensionName
+};
+
 void pickPhysicalDevice() {
-    physicalDevice = std::make_unique<vk::raii::PhysicalDevice>(vk::raii::PhysicalDevices( *instance ).front());
+    std::vector<vk::raii::PhysicalDevice> devices = instance.enumeratePhysicalDevices();
+    const auto devIter = std::ranges::find_if(devices,
+    [&](auto const & device) {
+            auto queueFamilies = device.getQueueFamilyProperties();
+            bool isSuitable = device.getProperties().apiVersion >= VK_API_VERSION_1_3;
+            const auto qfpIter = std::ranges::find_if(queueFamilies,
+            []( vk::QueueFamilyProperties const & qfp )
+                    {
+                        return (qfp.queueFlags & vk::QueueFlagBits::eGraphics) != static_cast<vk::QueueFlags>(0);
+                    } );
+            isSuitable = isSuitable && ( qfpIter != queueFamilies.end() );
+            auto extensions = device.enumerateDeviceExtensionProperties( );
+            bool found = true;
+            for (auto const & extension : deviceExtensions) {
+                auto extensionIter = std::ranges::find_if(extensions, [extension](auto const & ext) {return strcmp(ext.extensionName, extension) == 0;});
+                found = found &&  extensionIter != extensions.end();
+            }
+            isSuitable = isSuitable && found;
+            printf("\n");
+            if (isSuitable) {
+                physicalDevice = device;
+            }
+            return isSuitable;
+    });
+    if (devIter == devices.end()) {
+        throw std::runtime_error("failed to find a suitable GPU!");
+    }
 }
 ----
 

en/03_Drawing_a_triangle/00_Setup/04_Logical_device_and_queues.adoc

@@ -43,9 +43,9 @@ Right now we're only interested in a queue with graphics capabilities.
 
 [,c++]
 ----
-std::vector<vk::QueueFamilyProperties> queueFamilyProperties = physicalDevice->getQueueFamilyProperties();
+std::vector<vk::QueueFamilyProperties> queueFamilyProperties = physicalDevice.getQueueFamilyProperties();
 
-vk::DeviceQueueCreateInfo deviceQueueCreateInfo( {}, graphicsIndex, {} );
+vk::DeviceQueueCreateInfo deviceQueueCreateInfo { .queueFamilyIndex = graphicsIndex };
 ----
 
 The currently available drivers will only allow you to create a small number of
@@ -59,8 +59,8 @@ This is required even if there is only a single queue:
 
 [,c++]
 ----
-float queuePriority = 1.0f;
-vk::DeviceQueueCreateInfo deviceQueueCreateInfo( {}, graphicsIndex, &queuePriority );
+float queuePriority = 0.0f;
+vk::DeviceQueueCreateInfo deviceQueueCreateInfo { .queueFamilyIndex = graphicsIndex, .queueCount = 1, .pQueuePriorities = &queuePriority };
 ----
 
 == Specifying used device features
@@ -77,14 +77,77 @@ start doing more interesting things with Vulkan.
 vk::PhysicalDeviceFeatures deviceFeatures;
 ----
 
+== Specifying any extra features or updates we'd like our device to support
+
+Vulkan is built to be backwards compatible.  Thus, if you do nothing else,
+you will get a Vulkan instance just as it was originally released in Vulkan 1
+.0.  This is necessary as code written back then would need to still work so
+any additional features must be new code which would need to be turned on.
+So, let's tell Vulkan that we use some of the more modern features which make
+ it easier to work with.
+
+First, let's query for the features of the physical device:
+
+[,c++]
+----
+ // query for Vulkan 1.3 features
+ auto features = physicalDevice.getFeatures2();
+----
+
+Now, let's tell Vulkan that there's a few features we wish to use, by turning
+ on dynamicRendering and the extendedDynamicState.
+
+[,c++]
+----
+vk::PhysicalDeviceVulkan13Features vulkan13Features;
+vk::PhysicalDeviceExtendedDynamicStateFeaturesEXT extendedDynamicStateFeatures;
+vulkan13Features.dynamicRendering = vk::True;
+extendedDynamicStateFeatures.extendedDynamicState = vk::True;
+----
+
+Note that these are just variables that we created, and aren't part of the
+device create info logic structure.  In Vulkan, all structures have a .pNext
+member variable which allows for chaining.  So, we need to tell each object
+about the next object in the chain like this:
+
+[,c++]
+----
+vulkan13Features.pNext = &extendedDynamicStateFeatures;
+features.pNext = &vulkan13Features;
+----
+
+Note here that features is the same object that we got when we queried the
+physical device for the features.  Each pNext member variable points to the
+next feature structure in the chain.  So all that's left is to ensure that
+when we create the logical device with a VkDeviceCreateInfo structure we set
+.pNext in that structure to the pointer to the features.
+
+== Specifying device extensions
+
+For our application to work properly, we need to enable certain device extensions. These extensions provide additional functionality that we'll need later in the tutorial.
+
+[,c++]
+----
+std::vector<const char*> deviceExtensions = {
+    vk::KHRSwapchainExtensionName,
+    vk::KHRSpirv14ExtensionName,
+    vk::KHRSynchronization2ExtensionName,
+    vk::KHRCreateRenderpass2ExtensionName
+};
+----
+
+The `VK_KHR_swapchain` extension is required for presenting rendered images to the window. The other extensions provide additional functionality that we'll use in later parts of the tutorial.
+
 == Creating the logical device
 
-With the previous two structures in place, we can start filling in the main
+With the previous structures in place, we can start filling in the main
 `VkDeviceCreateInfo` structure.
 
 [,c++]
 ----
-vk::DeviceCreateInfo createInfo( {}, deviceQueueCreateInfo, {}, deviceExtensions, &deviceFeatures );
+vk::DeviceCreateInfo      deviceCreateInfo{ .pNext =  &features, .queueCreateInfoCount = 1, .pQueueCreateInfos = &deviceQueueCreateInfo };
+deviceCreateInfo.enabledExtensionCount = deviceExtensions.size();
+deviceCreateInfo.ppEnabledExtensionNames = deviceExtensions.data();
 ----
 
 The remainder of the information bears a resemblance to the
@@ -103,11 +166,11 @@ device-specific validation layers, but this is [no longer the case]
 That means that the `enabledLayerCount` and `ppEnabledLayerNames` fields of
 `VkDeviceCreateInfo` are ignored by up-to-date implementations.
 
-We won't need any device-specific extensions for now.
+As mentioned earlier, we need several device-specific extensions for our application to work properly.
 
 [,c++]
 ----
-device = std::make_unique<vk::raii::Device>( *physicalDevice, deviceCreateInfo );
+device = vk::raii::Device( physicalDevice, deviceCreateInfo );
 ----
 
 The parameters are the physical device to interface with, and the usage
@@ -139,7 +202,7 @@ creating a single queue from this family, we'll simply use index `0`.
 
 [,c++]
 ----
-graphicsQueue = std::make_unique<vk::raii::Queue>( *device, graphicsIndex, 0 );
+graphicsQueue = vk::raii::Queue( device, graphicsIndex, 0 );
 ----
 
 With the logical device and queue handles, we can now actually start using the