Vulkan-Hpp/vk_raii_ProgrammingGuide.md

448 lines
27 KiB
Markdown
Raw Normal View History

2021-04-22 10:44:36 +00:00
# vulkan_raii.hpp: a programming guide
## Introduction
vulkan_raii.hpp is a C++ layer on top of vulkan.hpp that follows the RAII-principle (RAII: Resource Acquisition Is Initialization, see [https://en.cppreference.com/w/cpp/language/raii#:~:text=Resource%20Acquisition%20Is%20Initialization%20or,in%20limited%20supply](https://en.cppreference.com/w/cpp/language/raii#:~:text=Resource%20Acquisition%20Is%20Initialization%20or,in%20limited%20supply)). This header-only library uses all the enums and structure wrappers from vulkan.hpp and provides a new set of wrapper classes for the Vulkan handle types. Instead of creating Vulkan handles with vk*Allocate or vk*Create a constructor of the corresponding Vulkan handle wrapper class is used. And instead of destroying Vulkan handles with vk*Free or vk*Destroy, the destructor of that handle class is called.
## General Usage
As a simple example, instead of creating a `vk::Device`
// create a vk::Device, given a vk::PhysicalDevice physicalDevice and a vk::DeviceCreateInfo deviceCreateInfo
vk::Device device = physicalDevice.createDevice( deviceCreateInfo );
and destroying it at some point
// destroy a vk::Device
device.destroy();
you would create a `vk::raii::Device`
// create a vk::raii::Device, given a vk::raii::PhysicalDevice physicalDevice and a vk::DeviceCreateInfo deviceCreateInfo
vk::raii::Device device( physicalDevice, deviceCreateInfo );
That `vk::raii::Device` is automatically destroyed, when its scope is left.
Alternatively, you can use a creation function to create a `vk::raii::Device`:
// create a vk::raii::Device, given a vk::raii::PhysicalDevice physicalDevice and a vk::DeviceCreateInfo deviceCreateInfo
vk::raii::Device device = physicalDevice.createDevice( deviceCreateInfo );
Finally, if you have defined `VULKAN_HPP_NO_EXCEPTIONS` and compile for at least C++23, the constructors as described above are not available (they would potentially throw an exception which is not allowed then) but you have to use the construction functions. Those functions then do not return the created object, but a `std::expected<vk::raii::Object, vk::Result>`:
// create a vk::raii::Device, given a vk::raii::PhysicalDevice physicalDevice and a vk::DeviceCreateInfo deviceCreateInfo
// when VULKAN_HPP_NO_EXCEPTIONS is defined and your using at least C++23
auto deviceExpected = physicalDevice.createDevice( deviceCreateInfo );
if ( deviceExpected.has_value() )
{
device = std::move( *deviceExpected );
}
In the code snippets in this text, I will consistently use the constructor-approach.
2021-04-22 10:44:36 +00:00
Other than the `vk::Device`, you can assign the `vk::raii::Device` to a smart pointer:
// create a smart-pointer to a vk::raii::Device, given a smart-pointer to a vk::raii::PhysicalDevice pPhysicalDevice and a vk::DeviceCreateInfo deviceCreateInfo
std::unique_ptr<vk::raii::Device> pDevice;
pDevice = std::make_unique<vk::raii::Device>( *pPhysicalDevice, deviceCreateInfo );
Note that the vk::raii objects own the actual Vulkan resource. Therefore, all vk::raii objects that own destructable resources are just movable, but not copyable. Therefore, a few vk::raii objects, like vk::raii::PhysicalDevice are copyable as well.
2021-04-22 10:44:36 +00:00
For simplicity, in the rest of this document a vk::raii object is always directly instantiated on the stack. Obviously, that's not essential. You could assign them as well to a std::unique_ptr, a std::shared_ptr, or any other smart pointer or object managing data structure. And you can even assign them to a dumb pointer by using the new operator.
2021-04-22 10:44:36 +00:00
Similar to a `vk::Device`, a `vk::raii::Device` provides the functions related to that class. But other than the `vk::Device`, you don't need to provide a device-specific dispatcher to those functions to get multi-device functionality. That's already managed by the `vk::raii::Device`.
That is, calling a device-related function is identical for both cases:
// call waitIdle from a vk::Device
device.waitIdle();
// call waitIdle from a vk::raii::Device
device.waitIdle();
vk::raii goes one step further. In the vk namespace, most of the functions are members of `vk::Device`. In the vk::raii namespace functions strongly related to a non-dispatchable handle are members of the corresponding vi::raii object. For example, to bind memory to a buffer, in vk namespace you write
// bind vk::DeviceMemory memory to a vk::Buffer buffer, given vk::DeviceSize memoryOffset
device.bindBufferMemory( buffer, memory, memoryOffset );
In vk::raii namespace you write
// bind vk::raii::DeviceMemory memory to a vk::raii::Buffer buffer, given vk::DeviceSize memoryOffset
buffer.bindMemory( *memory, memoryOffset );
Note that `vk::raii::Buffer::bindMemory()`takes a `vk::DeviceMemory` as its first argument, not a `vk::raii::DeviceMemory`. From a vk::raii object you get to the corresponding vk object by just dereferencing the vk::raii object.
## First Steps
### 00 Create a vk::raii::Context
The very first step when using classes from the vk::raii namespace is to instantiate a `vk::raii::Context`. This class has no counterpart in either the vk namespace or the pure C-API of Vulkan. It is the handle to the few functions that are not bound to a `VkInstance` or a `VkDevice`:
// instantiate a vk::raii::Context
vk::raii::Context context;
To use any of those "global" functions, your code would look like that:
// get the API version, using that context
uint32_t apiVersion = context.enumerateInstanceVersion();
### 01 Create a vk::raii::Instance
To pass that information on to a `vk::raii::Instance`, its constructor gets a reference to that `vk::raii::Context`:
// instantiate a vk::raii::Instance, given a vk::raii::Context context and a vk::InstanceCreateInfo instanceCreateInfo
vk::raii::Instance instance( context, instanceCreateInfo );
The `vk::raii::Instance` now holds all the instance-related functions. For example, to get all the `vk::PhysicalDeviceGroupProperties` for an instance, your call would look like this:
// get all vk::PhysicalDeviceGroupProperties from a vk::raii::Instance instance
std::vector<vk::PhysicalDeviceGroupProperties> physicalDeviceGroupProperties = instance.enumeratePhysicalDeviceGroups();
### 02 Enumerate the vk::raii::PhysicalDevices
Enumerating the physical devices of an instance is slightly different in vk::raii namespace as you might be used to from the vk-namespace or the pure C-API. As there might be multiple physical devices attached, you would instantiate a `vk::raii::PhysicalDevices` (note the trailing 's' here!), which essentially is a `std::vector` of `vk::raii::PhysicalDevice`s (note the trailing 's' here!):
// enumerate the vk::raii::PhysicalDevices, given a vk::raii::Instance instance
vk::raii::PhysicalDevices physicalDevices( instance );
As vk::raii::PhysicalDevices is just a `std::vector<vk::raii::PhysicalDevice>`, you can access any specific `vk::raii:PhysicalDevice` by indexing into that `std::vector`:
// get the vk::LayerProperties of the vk::raii::PhysicalDevice with index physicalDeviceIndex, given a vk::raii::PhysicalDevices physicalDevices
std::vector<vk::LayerProperties> layerProperties = physicalDevices[physicalDeviceIndex].enumerateDeviceLayerProperties();
You can as well get one `vk::raii::PhysicalDevice` out of a `vk::raii::PhysicalDevices` like this:
// get the vk::raii::PhysicalDevice with index physicalDeviceIndex, given a vk::raii::PhysicalDevices physicalDevices object:
vk::raii::PhysicalDevice physicalDevice( std::move( physicalDevices[physicalDeviceIndex] ) );
Note, that even though the actual `VkPhysicalDevice` owned by a `vk::raii::PhysicalDevice` is not a destructible resource, for consistency reasons a `vk::raii::PhysicalDevice` is a movable but not copyable object just like all the other vk::raii objects.
### 03 Create a vk::raii::Device
To create a `vk::raii::Device`, you just instantiate an object of that class:
// create a vk::raii::Device, given a vk::raii::PhysicalDevice physicalDevice and a vk::DeviceCreateInfo deviceCreateInfo
vk::raii::Device device( physicalDevice, deviceCreateInfo );
For each instantiated `vk::raii::Device`, the device-specific Vulkan function pointers are resolved. That is, for multi-device programs, you automatically use the correct device-specific function pointers, and organizing a multi-device program is simplified:
// create a vk::raii::Device per vk::raii::PhysicalDevice, given a vk::raii::PhysicalDevices physicalDevices, and a corresponding array of vk::DeviceCreateInfo deviceCreateInfos
std::vector<vk::raii::Device> devices;
for ( size_t i = 0; i < physicalDevices.size(); i++ )
{
devices.push_back( vk::raii::Device( physicalDevices[i], deviceCreateInfos[i] ) );
}
### 04 Create a vk::raii::CommandPool and vk::raii::CommandBuffers
Creating a `vk::raii::CommandPool` is simply done by instantiating such an object:
// create a vk::raii::CommandPool, given a vk::raii::Device device and a vk::CommandPoolCreateInfo commandPoolCreateInfo
vk::raii::CommandPool commandPool( device, commandPoolCreateInfo );
As the number of `vk::raii::CommandBuffer`s to allocate from a `vk::raii::CommandPool` is given by the member `commandBufferCount` of a `vk::CommandBufferAllocateInfo` structure, it can't be instantiated as a single object. Instead you get a `vk::raii::CommandBuffers` (note the trailing 's' here!), which essentially is a `std::vector` of `vk::raii::CommandBuffer`s (note the trailing 's' here!).
// create a vk::raii::CommandBuffers, given a vk::raii::Device device and a vk::CommandBufferAllocateInfo commandBufferAllocateInfo
vk::raii::CommandBuffers commandBuffers( device, commandBufferAllocateInfo );
Note, that the `vk::CommandBufferAllocateInfo` holds a `vk::CommandPool` member `commandPool`. To assign that from a `vk::raii::CommandPool` you can use the `operator*()`:
// assign vk::CommandBufferAllocateInfo::commandPool, given a vk::raii::CommandPool commandPool
commandBufferAllocateInfo.commandPool = *commandPool;
As a `vk::raii::CommandBuffers` is just a `std::vector<vk::raii::CommandBuffer>`, you can access any specific `vk::raii:CommandBuffer` by indexing into that `std::vector`:
// start recording of the vk::raii::CommandBuffer with index commandBufferIndex, given a vk::raii::CommandBuffers commandBuffers
commandBuffers[commandBufferIndex].begin();
You can as well get one `vk::raii::CommandBuffer` out of a `vk::raii::CommandBuffers` like this:
// get the vk::raii::CommandBuffer with index commandBufferIndex, given a vk::raii::CommandBuffers commandBuffers
vk::raii::CommandBuffer commandBuffer( std::move( commandBuffers[commandBufferIndex] ) );
// start recording
commandBuffer.begin();
There is one important thing to note, regarding command pool and command buffer handling. When you destroy a `VkCommandPool`, all `VkCommandBuffer`s allocated from that pool are implicitly freed. That automatism does not work well with the raii-approach. As the `vk::raii::CommandBuffers` are independent objects, they are not automatically destroyed when the `vk::raii::CommandPool` they are created from is destroyed. Instead, their destructor would try to use an invalid `vk::raii::CommandPool`, which obviously is an error.
To handle that correctly, you have to make sure, that all `vk::raii::CommandBuffers` generated from a `vk::raii::CommandPool` are explicitly destroyed before that `vk::raii::CommandPool` is destroyed!
### 05 Create a vk::raii::SwapchainKHR
To initialize a swap chain, you first instantiate a `vk::raii::SwapchainKHR`:
// create a vk::raii::SwapchainKHR, given a vk::raii::Device device and a vk::SwapchainCreateInfoKHR swapChainCreateInfo
vk::raii::SwapchainKHR swapchain( device, swapChainCreateInfo );
You can get an array of presentable images associated with that swap chain:
// get presentable images associated with vk::raii::SwapchainKHR swapchain
std::vector<VkImage> images = swapchain.getImages();
Note, that you don't get `vk::raii::Image`s here, but plain `VkImage`s. They are controlled by the swap chain, and you should not destroy them.
But you can create `vk::raii::ImageView`s out of them:
// create a vk::raii::ImageView per VkImage, given a vk::raii::Device sevice, a vector of VkImages images and a vk::ImageViewCreateInfo imageViewCreateInfo
std::vector<vk::raii::ImageView> imageViews;
for ( auto image : images )
{
imageViewCreatInfo.image = image;
imageViews.push_back( vk::raii::ImageView( device, imageViewCreateInfo ) );
}
### 06 Create a Depth Buffer
For a depth buffer, you need an image and some device memory and bind the memory to that image. That is, you first create a vk::raii::Image
// create a vk::raii::Image image, given a vk::raii::Device device and a vk::ImageCreateInfo imageCreateInfo
// imageCreateInfo.usage should hold vk::ImageUsageFlagBits::eDepthStencilAttachment
vk::raii::Image depthImage( device, imageCreateInfo );
To create the corresponding vk::raii::DeviceMemory, you should determine appropriate values for the vk::MemoryAllocateInfo. That is, get the memory requirements from the pDepthImage, and determine some memoryTypeIndex from the pPhysicalDevice's memory properties, requiring vk::MemoryPropertyFlagBits::eDeviceLocal.
// get the vk::MemoryRequirements of the pDepthImage
vk::MemoryRequirements memoryRequirements = depthImage.getMemoryRequirements();
// determine appropriate memory type index, using some helper function determineMemoryTypeIndex
vk::PhysicalDeviceMemoryProperties memoryProperties = physicalDevice.getMemoryProperties();
uint32_t memoryTypeIndex = determineMemoryTypeIndex( memoryProperties, memoryRequirements.memoryTypeBits, vk::MemoryPropertyFlagBits::eDeviceLocal );
// create a vk::raii::DeviceMemory depthDeviceMemory for the depth buffer
vk::MemoryAllocateInfo memoryAllocateInfo( memoryRequirements.size, memoryTypeIndex );
vk::raii::DeviceMemory depthDeviceMemory( device, memoryAllocateInfo );
Then you can bind the depth memory to the depth image
// bind the pDepthMemory to the pDepthImage
depthImage.bindMemory( *depthDeviceMemory, 0 );
Finally, you can create an image view on that depth buffer image
// create a vk::raii::ImageView depthView, given a vk::ImageViewCreateInfo imageViewCreateInfo
imageViewCreateInfo.image = *depthImage;
vk::raii::ImageView depthImageView( device, imageViewCreateInfo );
### 07 Create a Uniform Buffer
Initializing a uniform buffer is very similar to initializing a depth buffer as described above. You just instantiate a `vk::raii::Buffer` instead of a `vk::raii::Image`, and a `vk::raii::DeviceMemory`, and bind the memory to the buffer:
// create a vk::raii::Buffer, given a vk::raii::Device device and a vk::BufferCreateInfo bufferCreateInfo
vk::raii::Buffer uniformBuffer( device, bufferCreateInfo );
// get memoryRequirements for this uniform buffer
vk::MemoryRequirements memoryRequirements = uniformBuffer.getMemoryRequirements();
// determine appropriate memory type index, using some helper function, given a vk::raii::PhysicalDevice physicalDevice and some memoryPropertyFlags
vk::PhysicalDeviceMemoryProperties memoryProperties = physicalDevice.getMemoryProperties();
uint32_t memoryTypeIndex = determineMemoryTypeIndex( memoryProperties, memoryRequirements.memoryTypeBits, memoryPropertyFlags );
// create a vk::raii::DeviceMemory uniformDeviceMemory for the uniform buffer
vk::MemoryAllocateInfo memoryAllocateInfo( memoryRequirements.size, memoryTypeIndex );
vk::raii::DeviceMemory uniformDeviceMemory( device, memoryAllocateInfo );
// bind the vk::raii::DeviceMemory uniformDeviceMemory to the vk::raii::Buffer uniformBuffer
uniformBuffer.bindMemory( *uniformDeviceMemory, 0 );
### 08 Create a vk::raii::PipelineLayout
To initialize a Pipeline Layout you just have to instantiate a `vk::raii::DescriptorSetLayout` and a `vk::raii::PipelineLayout` using that `vk::raii::DescriptorSetLayout`:
// create a vk::raii::DescriptorSetLayout, given a vk::raii::Device device and a vk::DescriptorSetLayoutCreateInfo descriptorSetLayoutCreateInfo
vk::raii::DescriptorSetLayout descriptorSetLayout( device, descriptorSetLayoutCreateInfo );
// create a vk::raii::PipelineLayout, given a vk::raii::Device device and a vk::raii::DescriptorSetLayout
vk::PipelineLayoutCreateInfo pipelineLayoutCreateInfo( {}, *descriptorSetLayout );
vk::raii::PipelineLayout pipelineLayout( device, pipelineLayoutCreateInfo );
### 09 Create a vk::raii::DescriptorPool and vk::raii::DescriptorSets
The Descriptor Set handling with `vk::raii` requires some special handling that is not needed when using the pure C-API or the vk-namespace!
As a `vk::raii::DescriptorSet` object destroys itself in the destructor, you have to instantiate the corresponding `vk::raii::DescriptorPool` with the `vk::DescriptorPoolCreateInfo::flags` set to (at least) `vk::DescriptorPoolCreateFlagBits::eFreeDescriptorSet`. Otherwise, such individual destruction of a `vk::raii::DescriptorSet` would not be allowed!
That is, an instantiation of a `vk::raii::DescriptorPool` would look like this:
// create a vk::raii::DescriptorPool, given a vk::raii::Device device and a vk::DescriptorPoolCreateInfo descriptorPoolCreateInfo
assert( descriptorPoolCreateInfo.flags & vk::DescriptorPoolCreateFlagBits::eFreeDescriptorSet );
vk::raii::DescriptorPool descriptorPool( device, descriptorPoolCreateInfo );
To actually instantiate a `vk::raii::DescriptorSet`, you need a `vk::raii::DescriptorPool`, as just described, and a `vk::raii::DescriptorSetLayout`, similar to the one described in the previous section.
Moreover, as the number of `vk::raii::DescriptorSet`s to allocate from a `vk::raii::DescriptorPool` is given by the number of `vk::DescriptorSetLayouts` held by a `vk::DescriptorSetAllocateInfo`, it can't be instantiated as a single object. Instead you get a `vk::raii::DescriptorSets` (note the trailing 's' here!), which essentially is a `std::vector` of `vk::raii::DescriptorSet`s (note the trailing 's' here!).
When you want to create just one `vk::raii::DescriptorSet`, using just one `vk::raii::DescriptorSetLayout`, your code might look like this:
// create a vk::raii::DescriptorSets, holding a single vk::raii::DescriptorSet, given a vk::raii::Device device, a vk::raii::DescriptorPool descriptorPool, and a single vk::raii::DescriptorSetLayout descriptorSetLayout
vk::DescriptorSetAllocateInfo descriptorSetAllocateInfo( *descriptorPool, *descriptorSetLayout );
vk::raii::DescriptorSets pDescriptorSets( device, descriptorSetAllocateInfo );
And, again similar to the vk::raii::CommandBuffers handling described above, you can get one `vk::raii::DescriptorSet` out of a `vk::raii::DescriptorSets` like this:
// get the vk::raii::DescriptorSet with index descriptorSetIndex, given a vk::raii::DescriptorSets descriptorSets
vk::raii::DescriptorSet descriptorSet( std::move( descriptorSets[descriptorSetIndex] ) );
### 10 Create a vk::raii::RenderPass
Creating a `vk::raii::RenderPass` is pretty simple, given you already have a meaningful `vk::RenderPassCreateInfo`:
// create a vk::raii::RenderPass, given a vk::raii::Device device and a vk::RenderPassCreateInfo renderPassCreateInfo
vk::raii::RenderPass renderPass( device, renderPassCreateInfo );
### 11 Create a vk::raii::ShaderModule
Again, creating a `vk::raii::ShaderModule` is simple, given a `vk::ShaderModuleCreateInfo` with some meaningful code:
// create a vk::raii::ShaderModule, given a vk::raii::Device device and a vk::ShaderModuleCreateInfo shaderModuleCreateInfo
vk::raii::ShaderModule shaderModule( device, shaderModuleCreateInfo );
### 12 Create vk::raii::Framebuffers
If you have a `std::vector<vk::raii::ImageView>` as described in chapter 05 above, with one view per `VkImage` that you got from a `vk::raii::SwapchainKHR`; and one `vk::raii::ImageView` as described in chapter 06 above, which is a view on a `vk::raii::Image`, that is supposed to be a depth buffer, you can create a `vk::raii::Framebuffer` per swapchain image.
// create a vector of vk::raii::Framebuffer, given a vk::raii::ImageView depthImageView, a vector of vk::raii::ImageView swapchainImageViews, a vk::raii::RenderPass renderPass, a vk::raii::Devie device, and some width and height
// use the depth image view as the second attachment for each vk::raii::Framebuffer
std::array<vk::ImageView, 2> attachments;
attachments[1] = *depthImageView;
std::vector<vk::raii::Framebuffer> framebuffers;
for ( auto const & imageView : swapchainImageViews )
{
// use each image view from the swapchain as the first attachment
attachments[0] = *imageView;
vk::FramebufferCreateInfo framebufferCreateInfo( {}, *renderPass, attachments, width, height, 1 );
framebuffers.push_back( vk::raii::Framebuffer( device, framebufferCreateInfo ) );
}
### 13 Initialize a Vertex Buffer
To initialize a vertex buffer, you essentially have to combine some of the pieces described in the chapters before. First, you need to create a `vk::raii::Buffer` and a `vk::raii::DeviceMemory` and bind them:
// create a vk::raii::Buffer vertexBuffer, given a vk::raii::Device device and some vertexData in host memory
vk::BufferCreateInfo bufferCreateInfo( {}, sizeof( vertexData ), vk::BufferUsageFlagBits::eVertexBuffer );
vk::raii::Buffer vertexBuffer( device, bufferCreateInfo );
// create a vk::raii::DeviceMemory vertexDeviceMemory, given a vk::raii::Device device and a uint32_t memoryTypeIndex
vk::MemoryRequirements memoryRequirements = vertexBuffer.getMemoryRequirements();
vk::MemoryAllocateInfo memoryAllocateInfo( memoryRequirements.size, memoryTypeIndex );
vk::raii::DeviceMemory vertexDeviceMemory( device, memoryAllocateInfo );
// bind the complete device memory to the vertex buffer
vertexBuffer.bindMemory( *vertexDeviceMemory, 0 );
// copy the vertex data into the vertexDeviceMemory
...
Later on, you can bind that vertex buffer to a command buffer:
// bind a complete single vk::raii::Buffer vertexBuffer as a vertex buffer, given a vk::raii::CommandBuffer commandBuffer
commandBuffer.bindVertexBuffer( 0, { *vertexBuffer }, { 0 } );
### 14 Initialize a Graphics Pipeline
Initializing a graphics pipeline is not very raii-specific. Just instantiate it, provided you have a valid vk::GraphicsPipelineCreateInfo:
// create a vk::raii::Pipeline, given a vk::raii::Device device and a vk::GraphicsPipelineCreateInfo graphicsPipelineCreateInfo
vk::raii::Pipeline graphicsPipeline( device, graphicsPipelineCreateInfo );
The only thing to keep in mind here is the dereferencing of raii handles, like `pipelineLayout` or `renderPass` in the `vk::GraphicsPipelineCreateInfo`:
vk::GraphicsPipelineCreateInfo graphicsPipelineCreateInfo(
{}, // flags
pipelineShaderStageCreateInfos, // stages
&pipelineVertexInputStateCreateInfo, // pVertexInputState
&pipelineInputAssemblyStateCreateInfo, // pInputAssemblyState
nullptr, // pTessellationState
&pipelineViewportStateCreateInfo, // pViewportState
&pipelineRasterizationStateCreateInfo, // pRasterizationState
&pipelineMultisampleStateCreateInfo, // pMultisampleState
&pipelineDepthStencilStateCreateInfo, // pDepthStencilState
&pipelineColorBlendStateCreateInfo, // pColorBlendState
&pipelineDynamicStateCreateInfo, // pDynamicState
*pipelineLayout, // layout
*renderPass // renderPass
);
### 15 Drawing a Cube
Finally, we get all those pieces together and draw a cube.
To do so, you need a `vk::raii::Semaphore`:
// create a vk::raii::Semaphore, given a vk::raii::Device
vk::raii::Semaphore imageAcquiredSemphore( device, vk::SemaphoreCreateInfo() );
That semaphore can be used, to acquire the next imageIndex from the `vk::raii::SwapchainKHR` swapchain:
vk::Result result;
uint32_t imageIndex;
std::tie( result, imageIndex ) = swapchain.acquireNextImage( timeout, *imageAcquiredSemaphore );
Note, `vk::raii::SwapchainKHR::acquireNextImage` returns a `std::pair<vk::Result, uint32_t>`, that can nicely be assigned onto two separate values using std::tie().
And also note, the returned `vk::Result` can not only be `vk::Result::eSuccess`, but also `vk::Result::eTimeout`, `vk::Result::eNotReady`, or `vk::Result::eSuboptimalKHR`, which should be handled here accordingly!
Next, you can record some commands into a `vk::raii::CommandBuffer`:
// open the commandBuffer for recording
commandBuffer.begin( {} );
// initialize a vk::RenderPassBeginInfo with the current imageIndex and some appropriate renderArea and clearValues
vk::RenderPassBeginInfo renderPassBeginInfo( *renderPass, *framebuffers[imageIndex], renderArea, clearValues );
// begin the render pass with an inlined subpass; no secondary command buffers allowed
commandBuffer.beginRenderPass( renderPassBeginInfo, vk::SubpassContents::eInline );
// bind the graphics pipeline
commandBuffer.bindPipeline( vk::PipelineBindPoint::eGraphics, *graphicsPipeline );
// bind an appropriate descriptor set
commandBuffer.bindDescriptorSets( vk::PipelineBindPoint::eGraphics, *pipelineLayout, 0, { *descriptorSet }, nullptr );
// bind the vertex buffer
commandBuffer.bindVertexBuffers( 0, { *vertexBuffer }, { 0 } );
// set viewport and scissor
commandBuffer.setViewport( 0, viewport );
commandBuffer.setScissor( renderArea );
// draw the 12 * 3 vertices once, starting with vertex 0 and instance 0
commandBuffer.draw( 12 * 3, 1, 0, 0 );
// end the render pass and stop recording
commandBuffer.endRenderPass();
commandBuffer.end();
To submit that command buffer to a `vk::raii::Queue` graphicsQueue you might want to use a `vk::raii::Fence`
// create a vk::raii::Fence, given a vk::raii::Device device
vk::raii::Fence fence( device, vk::FenceCreateInfo() );
With that, you can fill a `vk::SubmitInfo` and submit the command buffer
vk::PipelineStageFlags waitDestinationStageMask( vk::PipelineStageFlagBits::eColorAttachmentOutput );
vk::SubmitInfo submitInfo( *imageAcquiredSemaphore, waitDestinationStageMask, *commandBuffer );
graphicsQueue.submit( submitInfo, *fence );
At some later point, you can wait for that submit being ready by waiting for the fence
while ( vk::Result::eTimeout == device.waitForFences( { *fence }, VK_TRUE, timeout ) )
;
And finally, you can use the `vk::raii::Queue` presentQueue to, well, present that image
vk::PresentInfoKHR presentInfoKHR( nullptr, *swapChain, imageIndex );
result = presentQueue.presentKHR( presentInfoKHR );
Note here, again, that `result` can not only be `vk::Result::eSuccess`, but also `vk::Result::eSuboptimalKHR`, which should be handled accordingly.
## Conclusion
With the vk::raii namespace you've got a complete set of Vulkan handle wrapper classes following the RAII-paradigm. That is, they can easily be assigned to a smart pointer. And you can't miss their destruction.
Moreover, the actual function pointer handling is done automatically by `vk::raii::Context`, `vk::raii::Instance`, and `vk::raii::Device`. That is, you always use the correct device-specific functions, no matter how many devices you're using.
Note, though, that there are a few classes, like `vk::raii::CommandPool` and `vk::raii::DescriptorSet`, that need some special handling that deviates from what you can do with the pure C-API or the wrapper classes in the vk-namespace.