Hello Triangle:

This tutorial covers rendering an introductory Hello Triangle program in Vulkan and C++.

A bare bones Vulkan set up can be simplified down into the steps:

Create the window
Create the Vulkan instance
Enumerate the available GPUs
Create the Vulkan device
Create the graphics queue
Initialize memory heaps/buffers
Create the swapchain
Create the render pass
Create the framebuffers

Once that is set up, we can implement the actual rendering logic for Hello Triangle as follows:

Create/upload the triangle vertex buffer
Create the vertex/fragment shaders
Create the graphics pipeline
Implement the main loop and render function

The complete source code for this tutorial can be found in this github repository.

0 - Setup:

Before we start writing code, please make sure you have followed this tutorial to set up the required SDKs/libraries.

Once we have the required setup complete, we can start implementing our logic. We begin by including the required library headers and defining some required definitions/helper functions.

                                 1.#include <cstdio>
                                 2.#include <cstdarg>
                                 3.#include <cstdint>
                                 4.
                                 5.#include <functional>
                                 6.#include <map>
                                 7.#include <vector>
                                 8.
                                 9.#include <SDL3/SDL.h>
                                10.#include <SDL3/SDL_vulkan.h>
                                11.
                                12.#include <vulkan/vulkan.h>
                                13.
                                14.enum
                                15.{
                                16.    
KB
 = 
1024
,
                                17.    
MB
 = 
1024
 * 
KB
,
                                18.    
GB
 = 
1024
 * 
MB
                                19.};
                                20.
                                21.const
 
char
* 
APP_NAME
 = 
"Hello Triangle"
;
                                22.
                                23.enum
                                24.{
                                25.    
WIDTH
  = 
1024
,
                                26.    
HEIGHT
 = 
1024
                                27.};
                                28.
                                29.#define ALIGN(size, alignment) (((size) + ((alignment) - 1)) & ~((alignment) - 1))
                                30.
                                31.enum
 : 
uint64_t
 { 
NANOSECONDS_PER_SECOND
 = 
1000000000
 };
                                32.
                                33.void
 Assert(
bool
 Condition, 
const
 
char
* ErrorMessage, ...)
                                34.{
                                35.    
if
 (!Condition)
                                36.    {
                                37.        std::
va_list
 Args;
                                38.        va_start(Args, ErrorMessage);
                                39.
                                40.        vprintf(ErrorMessage, Args);
                                41.        putc(
'\n'
, stdout
);
                                42.
                                43.        va_end(Args);
                                44.        throw −
1
;
                                45.    }
                                46.}

1 - Creating the window:

We will use the SDL library to create the window. SDL is a very popular/well supported cross platform library, and makes it very easy to create windows.

We start by initializing SDL and loading the Vulkan library, then we can create the SDL window.

                                 1.SDL_Window
* Window { 
nullptr
 };
                                 2.
                                 3....
                                 4.
                                 5.Assert(SDL_Init(
SDL_INIT_VIDEO
 | 
SDL_INIT_AUDIO
 | 
SDL_INIT_EVENTS
), 
"Could not initialize SDL"
);
                                 6.Assert(SDL_Vulkan_LoadLibrary(
nullptr
), 
"Could not load the vulkan library"
);
                                 7.
                                 8.SDL_PropertiesID
 WindowProperties = SDL_CreateProperties();
                                 9.SDL_SetNumberProperty(WindowProperties, 
SDL_PROP_WINDOW_CREATE_X_NUMBER
, 
SDL_WINDOWPOS_CENTERED
);
                                10.SDL_SetNumberProperty(WindowProperties, 
SDL_PROP_WINDOW_CREATE_Y_NUMBER
, 
SDL_WINDOWPOS_CENTERED
);
                                11.SDL_SetNumberProperty(WindowProperties, 
SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER
, 
WIDTH
);
                                12.SDL_SetNumberProperty(WindowProperties, 
SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER
, 
HEIGHT
);
                                13.SDL_SetStringProperty(WindowProperties, 
SDL_PROP_WINDOW_CREATE_TITLE_STRING
, 
APP_NAME
);
                                14.SDL_SetNumberProperty(WindowProperties, 
SDL_PROP_WINDOW_CREATE_VULKAN_BOOLEAN
, 
true
);
                                15.
                                16.Window = SDL_CreateWindowWithProperties(WindowProperties);
                                17.
                                18.SDL_DestroyProperties(WindowProperties);
                                19.
                                20.Assert(Window != 
nullptr
, 
"Could not create SDL window"
);

After the window is created, the user has pressed the close

  1. 2. 3.  4. 5. 6.  7.  8.  9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33.





we need to poll and handle SDL's events. The main one being SDL_EVENT_QUIT, which tells the application button. Here we also exit if the user presses the escape key. class="keyword">bool

Running {

true

};

e> ...

e> class="keyword">void

Before creating the Vulkan instance, the application can enumerate all the available layers/extensions available from the API/driver. These layers/extensions can give optional functionality/features if the application requests them during instance creation. We can enumerate the layers and extensions using the vkEnumerateDeviceLayerProperties and vkEnumerateDeviceExtensionProperties functions.

Normally an application will validate if its required layers/extensions are available, but here we simply print them out.

SDL requires certain extensions to be enabled when the Vulkan instance is created. We can get these using SDL_Vulkan_GetInstanceExtensions.

If you want to be thorough, you can validate these required extensions are supported by following the code in section A.

The validation layer can help catch bad parameters, memory leaks, invalid API calls, and many other errors. It is very useful for catching bugs. To enable it, simply add it to the required layer/extension list.

Note that enabling this validation extension is not enough, we need to do some additional set up after creating the instance. This will be covered in section 2.E.

To create the actual instance, we fill out the VkApplicationInfo and VkInstanceCreateInfo structures, and call vkCreateInstance. The application structure specifies the app and engine names/versions, and the required Vulkan API version. The instance structure will take a pointer to the application structure and the lists of the required layers/extensions.

If you followed 2.C, once the instance is created, we need to set up the debug report callback which Vulkan will use to send the debug messages. We first need to use vkGetInstanceProcAddr to get the function pointers to the callbacks vkCreateDebugReportCallback and vkDestroyDebugReportCallback. After getting the function addresses, we can create the debug report callback VulkanDebugReportCb and object VkDebugReportCallbackEXT.

Vulkan gives a list of all the GPUs in the current system through the vkEnumeratePhysicalDevices function.

Once we have all the device handles, we can get the properties of each device. This includes:

We will be using a simple algorithm which selects the most preferred GPU based off the following criteria: GPU type (discrete vs integrated), the number of graphics queues available, and the amount of local memory available.

Note we also store the graphics queue group index because this will be used to create the graphics queue later on.

Similar to when we had created the instance, we can get the device's available layers/extensions using the functions vkEnumerateDeviceLayerProperties and vkEnumerateDeviceExtensionProperties.

Note that we require the VK_KHR_SWAPCHAIN_EXTENSION_NAME extension when creating the logical device, because we will be creating a swapchain on this device.

Once we have figured out which layers/extensions are available and which ones we need, we can create the device. Note that we also have to request the queues we will be using at the device creation time in the VkDeviceQueueCreateInfo structure. Here we only request the one graphics queue from the group we picked in section 3.

We already created the graphics queue in section 4, so we can simply get a handle to it using vkGetDeviceQueue.

However, the queue still needs a couple more objects for us to be able to use it. Those objects are:

A command pool, represented by the structure VkCommandPool, is used to allocate command buffers. Command buffers, represented by the structure VkCommandBuffer, are used to record commands (i.e. rendering/compute/copy commands, etc.). A command pool can be used to allocate many command buffers, but we will only need one for our simple app. And lastly, the fence is used for syncronizing work between the CPU and GPU. We will give this fence object to the graphics queue when we submit work to it, and this fence will get signalled once the workload finishes. This will let us synchronize the CPU by waiting on the fence for the GPU submission to finish.

Memory management is a very important concept in Vulkan. The developer is responsible for figuring out which parts of the memory to use, how to manage the memory usage, etc. In this program, we are only concerned with two categories of memory:

Discrete GPUs usually have their own onboard local video memory (VRAM) which is optimal for GPU access. Integrated GPUs usually use the system RAM and do not have dedicated VRAM like discrete GPUs.

On older systems/discrete GPUs, only a small portion (usually 256 MB) of the GPU VRAM is visible (readable/writable) by the CPU. Modern systems/discrete GPUs have resizable bar, which makes the entire GPU VRAM visible to the CPU.

The GPU is able to access system RAM, but it not as fast as its own local VRAM. There are scenarios where the system RAM is needed. It is up to the developer to determine what type of memory is most appropriate for their purpose. This makes vulkan as powerful as it is, giving the developer a lot of control and optimization oppurtunity.

If resizable bar is enabled, our memory management logic is very simple as we can copy our data directly to the GPU's VRAM.

However, if resizable is not enabled, we need to have two heaps. Our primary heap will be on the GPU's VRAM as that is the most optimal for GPU access. We will have a secondary upload heap on the system RAM which will act as a staging area. Data will be copied to the upload heap (system RAM) first, and then a copy command will be submitted to the GPU to copy the contents from the upload heap to its primary heap (local VRAM).

We begin by getting the device's memory properties, using vkGetPhysicalDeviceMemoryProperties. This will populate the VkPhysicalDeviceMemoryProperties structure, giving us information on all the memory heaps and types available for the device we selected. From there we will figure out the most optimal heaps for our application, as described above. Note that our logic uses coherent memory wherever it can - this is because coherent memory is more optimal as sequential CPU writes will be write combined, making them much faster. Also note that a benefit of coherent memory types is that we don't need to flush our writes using vkFlushMappedMemoryRanges; however we still do this in this program to keep the code simpler. In actual programs, it will be more optimal to skip the vkFlushMappedMemoryRanges when coherent memory types are being used.

If we are using an upload heap we need to allocate a large buffer in that heap. This buffer will be used as the intermediate staging buffer for data before it gets transferred to the primary heap for future resources. Note that after we create the upload buffer, we also have to map it to the CPU address space using vkMapMemory, so that the CPU can access it.

This is the helper function used above, which allocates memory directly from a heap given its index. This will be useful for other allocations as well, such as the vertex buffer, and any other future allocations we need.

The swapchain contains the sequence of images which we will render to and present on the screen.

Before we create the swapchain, we need to create a Vulkan surface for our SDL window. This surface will allow Vulkan to render on SDL's window, and will be required for creating the swapchain. SDL provides a function SDL_Vulkan_CreateSurface to create this surface.

After we create the surface, we need to check if our required surface formats and presentation mode are supported. The surface format is the format of the swapchain images - in our case VK_FORMAT_B8G8R8A8_UNORM, which gives 8 bits to each red/green/blue/alpha component. The presentation mode controls how the images of the swapchain are presented. We will be using VK_PRESENT_MODE_FIFO_KHR, which will present the swapchain images one by one in a queue and will only present an image once the previous one has been fully presented (i.e. vertically synced).

We also need to tell the swapchain the size of the images to use and the minimum numbers of swapchain images to create. For that information we first call vkGetPhysicalDeviceSurfaceCapabilitiesKHR to get the surface capabilities, which will tell us the current surface's dimensions in the currentExtent field, and the minimum number of images required in the minImageCount field. Once we have this information, we can create the swapchain.

After we create the swapchain, we can get the swapchain's images using vkGetSwapchainImagesKHR. This will be useful for section 9 when we create the framebuffers.

Lastly, we need to create semaphores to syncronize access to the swapchain's images. We will need two sets of them for section 13 - one set for waiting for access to the swapchain's image before rendering, and one set for waiting for the swapchain's image to become ready to be presented after rendering is finished.

The render pass is used to describe the render targets/attachments the current rendering workload will use. This object will be is necessary to create the framebuffer, and also required by Vulkan in the main rendering logic since rendering operations can only be done in render passes. In this example, we will only be rendering to the swapchain surfaces.

We begin by describing the attachment format, the color/depth/stencil buffer content load/store behaviours, and image layout at the beginning and end of the render pass. This information is specified an array of VkAttachmentDescription structures, and one is needed for each attachment the render pass will use. In our case, we will only have one color attachment, which will be the swapchain surface.

After describing the attachments, we must describe the subpasses. The subpass will list and index the attachments defined in the render pass by their index and define the corresponding layouts during the subpass. We will only have one pass, so we only define one VkSubpassDescription.

After the swapchain and renderpass are created, we must create a framebuffer for each of the swapchain images. The framebuffer will be bound in our rendering commands, and the backing swapchain image will be rendered to.

We begin by creating a VkImageView for each swapchain image, which is necessary for each framebuffer.

After we have created all the necessary image views, we can create the framebuffers.

At this point, the required Vulkan objects have been set up to provide an equivalent "context" like what OpenGL would provide, and we can start implementing the Hello Triangle logic. The first step is to create the vertex buffer for the triangle we will be rendering.

We begin by defining the actual vertices. Each vertex has 2 attributes, the position and color, both of which are 3D floating point values.

The next step is to create the buffer, allocate the memory, and bind the memory to that new buffer. Vulkan requires the buffer creation and memory allocation to be seperate because it gives the programmer flexibility for memory management. For example, if we want, we can create a single memory allocation and sub-allocate that amoungst different buffers. Note that we are using the AllocateMemory helper function we created in section 6 to allocate the memory in our primary heap.

After the vertex buffer has been prepared, we can copy the vertex data into the upload buffer we created in section 6. Here we also tell Vulkan to flush the memory to make sure all the writes have gone through before moving onto the next steps where we will transfer the data to the primary allocation.

After the vertex buffer is allocated in the primary heap, we have to populate it with the vertex data. Recall from section 6 on the memory heaps, we have 2 cases here:

If it is the first case, then it is very simple. We simply write the vertex data directly into the primary heap.

The next step is to create the vertex and fragment shaders for rendering our triangle.

The vertex shader will be run once per vertex of our triangle. We will take in the vertex position from the vertex buffer in index 0, and the color in index 1. Remember these indices, they will be important for the next section where we will create the graphics pipeline. The vertex's position will to be written to gl_Position, which tells Vulkan the coordinate of the vertex, and the color will be sent to the fragment shader at index 0.

The fragment shader will also be simple - it will simply output the color it receives from the vertex shader. Vulkan will automatically interpolate the colors between the vertices.

After the shaders are implemented, we have to compile them into an intermediate representation for Vulkan. This can be done using the glslangvalidator compiler. There are two options - we can either output a binary file which we can read/load at runtime, or we can produce header files which we can simply include into our source code and bake the intermediate code into our application. We will be going with the second approach.

Once the intermediate representation headers are generated, we can include those headers and create VkShaderModule objects for each shader. This will be required for the graphics pipeline in the next section.

Once we have the shaders ready, we have to create the graphics pipeline. The graphics pipeline is a very important object which controls many rendering options/parameters and contains the shaders that will be used for rendering. Before creating the graphics pipeline, we have to create a pipeline layout and also configure several required structures.

The VkPipelineLayout tells Vulkan the descriptor sets and push constants which will be able to this graphics pipeline. In this example, we don't have any of those, so we simply create the layout.

The first structure we have to configure is VkPipelineShaderStageCreateInfo. This structure will tell Vulkan the shaders this pipeline will use for rendering. We have to fill out two of these, one for the vertex shader and one for the fragment shader. The graphics pipeline creation structure will take in an array of this structure, so we define it as an array of size two. The shader modules we created in the previous section will be used in the module field; and the pName field tells Vulkan the entry point/function of the shader, which is main in both of our shader implementations.

Next is the VkPipelineVertexInputStateCreateInfo structure, which describes the vertex buffers and data format to Vulkan. This structure takes in an array of two other structures - VkVertexInputBindingDescription and VkVertexInputAttributeDescription. The VkVertexInputBindingDescription structure describes each vertex buffer which will be bound to this pipeline for rendering. We have all our data in one buffer, so we only create one. The stride tells Vulkan how far apart each vertex's data is; in our case its the size of a vertex. The inputRate specifies whether the vertex data is per vertex or per instance. The other structure, VkVertexInputAttributeDescription, will be used to describe each vertex attribute this pipeline will work with. The location field tells Vulkan the index of the attribute, recall the vertex shader indices from the previous section. The binding field specifies which vertex buffer, from the VkVertexInputBindingDescription array, it will get this attribute from. The format just tells Vulkan the format of this attribute, i.e. the number of components, the number of bits per component, etc. Lastly the offset is used to determine the offset at which the first attribute is located in the buffer.

The next required structure is VkPipelineInputAssemblyStateCreateInfo, which tells the Vulkan how to assemble the primitives for rendering. We want our vertex data to be assembled into triangles, so we use VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST.

Next is the VkPipelineViewportStateCreateInfo structure which tells Vulkan the rendering viewport and the scissor test rectangle. Vulkan will render into the area given by the viewport rectangle, and discard pixels outside of the scissor test rectangle. For this program Vulkan can render to the entire screen, so we construct both the viewport and scissor test rectangle to cover the entire screen.

Next is the VkPipelineRasterizationStateCreateInfo structure which controls rasterization options. We are interested in polygonMode, cullMode, and frontFace. The polygonMode field controls how the rasterizer will render polygons, in our case we want it to fill them in so we use VK_POLYGON_MODE_FILL. The frontFace field tells the rasterizer which triangles are considered facing "front". We use VK_FRONT_FACE_COUNTER_CLOCKWISE, which means that triangles with their vertices ordered in a counter clockwise order will be considered to be facing the front. This is important because we can use an important optimization called back face culling, which will skip rendering triangles facing away from the viewer. Back face culling can be enabled by setting the cullMode to VK_CULL_MODE_BACK_BIT. This won't affect this program since our triangle always faces in front, but eventually when we start rendering 3D models/scenes it will matter. The rest of the options will be left to the defaults/zero.

Next is the VkPipelineMultisampleStateCreateInfo structure. This structure controls the multisampling options. In this program we do not need to change anything, we just leave it with the defaults.

The next structure is VkPipelineColorBlendStateCreateInfo which controls the color blending options. This structure requires an array of VkPipelineColorBlendAttachmentState structures, and the length of the array should match the number of color attachments which this pipeline will render to. In our case we are only rendering to one attachment, so our array will be of size one. We are not using any blending in this program, so we will leave everything default, except for the colorWriteMask field of the VkPipelineColorBlendAttachmentState structure, because that controls the components that can be written to the color attachment.

The next structure is VkPipelineDepthStencilStateCreateInfo, which controls the depth and stencil test options. We are not using the depth or stencil test in this program, so we leave all the parameters as default.

Once we have all these structures prepared, we can create the graphics pipeline.

Once we have the vertex buffer and graphics pipeline set up, we can implement the actual rendering logic! The main loop will call this code every frame to render the triangle, until the user closes the program.

The first step is to get the next swapchain image using vkAcquireNextImageKHR. This will give us the index of the next available image. We use the RenderSemaphore from section 7 here. When the image is available/ready to be rendered to, this semaphore will be signalled. When we submit the work to the graphics queue, the graphics queue will wait for this semaphore to become signalled before beginning rendering.

After we know which framebuffer/swapchain image we will be rendering to, we begin preparing the command buffer which will contain all our rendering commands.

The first command we insert into the command buffer is to set up the render pass. This will prepare the framebuffer which we are rendering to. Here we use the render pass object we created earlier and the current framebuffer, and we also specify the rendering area (the whole screen) and the clear color (blue in this case).

After we are done with our rendering commands, we can end the render pass, and finalize the command buffer.

Once the command buffer is populated, we have to submit it to our graphics queue. The VkSubmitInfo structure will specify the command buffer we are submitting, and it will also specify the semaphores which the queue should wait on before beginning rendering. As mentioned before, we want the graphics queue to wait for the framebuffer to become available before it starts rendering, so we use our RenderSemaphore from earlier here. We want the graphics queue to wait at the top of the pipe, meaning before any of the shader stages begin, so we use VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT as the waiting stage. Note that we also give another semaphore, PresentSemaphore , to be signalled once the command buffer is finished executing/rendering - this will be required to know when the image can be presented.

At this point, the command buffer has been submitted to the queue, and we can ask Vulkan to present the new image when its available. The PresentSemaphore will be signalled once the rendering operations finish and the next image is ready to be presented. We will out the structure VkPresentInfoKHR with the swapchain, current swapchain index, and the PresentSemaphore, and call vkQueuePresentKHR.

The semaphores we used above will insert the waits into the command queue and syncronize the GPU commands, but we also need to make sure the CPU is syncronized. We will accomplish this by waiting on the vkQueueSubmit fence. Once this fence comes back, it will mean that the previous rendering operation is finished and we can begin preparing the next frame. Note that this does not mean presentation has also finished, but that is ok because the next frame will be rendered to the next swapchain image. Even if we fill all the available swapchain images, eventually the queue will have to wait for the next swapchain image to become available, and the wait on the fence will block the CPU.

In other words, fences are used to syncronize the CPU and GPU, and semaphores are used to syncronize GPU commands. Note that waiting on this fence after every submission is not optimal. In an actual application, you would start preparing the next frame while the GPU works on the current one. This is Vulkan's biggest advantage, it allows the CPU and GPU to work in parallel and minimize bottlenecking/idling. However, to keep this tutorial as simple as possible, we wait after every submission.

Lastly, we add our infinite loop to render and then update, until the user closes our application.

When the application is closed, we have to free all our allocations/objects otherwise we will leak the memory. For that please see the destructor ~HelloTriangle in the source code.