At the core, Vulkan is an API Specification that conformant hardware implementations follow. The public specification is generated from the ./xml/vk.xml Vulkan Registry file in the official public copy of the Vulkan Specification repo found at Vulkan-Doc. Documentation of the XML schema is also available.

The Khronos Group, along with the Vulkan Specification, releases C99 header files generated from the API Registry that developers can use to interface with the Vulkan API.

For those who might not work with C code, there are various language bindings out there.

Some developers might be aware of the other Khronos Group standard OpenGL which is also a 3D Graphics API. Vulkan is not a direct replacement for OpenGL, but rather an explicit API that allows for more explicit control of the GPU.

Khronos' Vulkan Samples article on "How does Vulkan compare to OpenGL ES? What should you expect when targeting Vulkan? offers a more detailed comparison between the two APIs.

Vulkan puts more work and responsibility into the application. Not every developer will want to make that extra investment, but those that do so correctly can find power and performance improvements.

While some developers may want to try using Vulkan with no help, it is common to use some lighter libraries in your development flow to help abstract some of the more tedious aspect of Vulkan. Here are some libraries to help with development

Vulkan is a tool for developers to create hardware accelerated applications. The Vulkan Guide tries to cover the more logistical material such as extensions, versions, spec, etc. For more information how to “use” Vulkan to create something such as the Hello World Triangle, please take a look at resources such as those found in Khronos' Vulkan “learn” page. If you want to get more hands-on help and knowledge, feel free to join the Khronos Developer Slack or the Khronos Community Forums as well!

permalink: /Notes/004-3d-rendering/vulkan/chapters/what_vulkan_can_do.html ---

2D and 3D graphics are primarily what the Vulkan API is designed for. Vulkan is designed to allow developers to create hardware accelerated graphical applications.

Due to the parallel nature of GPUs, a new style of programming referred to as GPGPU can be used to exploit a GPU for computational tasks. Vulkan supports compute variations of VkQueues, VkPipelines, and more which allow Vulkan to be used for general computation.

Ray tracing is an alternative rendering technique, based around the concept of simulating the physical behavior of light.

Cross-vendor API support for ray tracing was added to Vulkan as a set of extensions in the 1.2.162 specification. These are primarily VK_KHR_ray_tracing_pipeline, VK_KHR_ray_query, and VK_KHR_acceleration_structure.

Vulkan Video has release a provisional specification as of the 1.2.175 spec release.

Vulkan Video adheres to the Vulkan philosophy of providing flexible, fine-grained control over video processing scheduling, synchronization, and memory utilization to the application.

Currently, the Vulkan Working Group is looking into how to make Vulkan a first class API for exposing ML compute capabilities of modern GPUs. More information was announced at Siggraph 2019.

Vulkan SC ("Safety Critical") aims to bring the graphics and compute capabilities of modern GPUs to safety-critical systems in the automotive, avionics, industrial and medical space. It was publicly launched on March 1st 2022 and the specification is available here.

permalink:/Notes/004-3d-rendering/vulkan/chapters/vulkan_spec.html layout: default ---

The Vulkan Spec can be built for any version and with any permutation of extensions. The Khronos Group hosts the Vulkan Spec Registry which contains a few publicly available variations that most developers will find sufficient. Anyone can build their own variation of the Vulkan Spec from Vulkan-Docs.

When building the Vulkan Spec, you pass in what version of Vulkan to build for as well as what extensions to include. A Vulkan Spec without any extensions is also referred to as the core version as it is the minimal amount of Vulkan an implementation needs to support in order to be conformant.

The Vulkan Spec can be built into different formats.

The Vulkan API is available on any Android device starting with API level 24 (Android Nougat), however not all devices will have a Vulkan driver.

Android uses its Hardware Abstraction Layer (HAL) to find the Vulkan Driver in a predefined path.

All 64-bit devices that launch with API level 29 (Android Q) or later must include a Vulkan 1.1 driver.

Vulkan is supported on many BSD Unix distributions.

Vulkan is supported on the Fuchsia operation system.

Vulkan is not natively supported on iOS, but can still be targeted with Vulkan Portability Tools.

Vulkan is supported on many Linux distributions.

Vulkan is not natively supported on MacOS, but can still be targeted with Vulkan Portability Tools.

The Nintendo Switch runs an NVIDIA Tegra chipset that supports native Vulkan.

Vulkan is supported on QNX operation system.

Google’s Stadia runs on AMD based Linux machines and Vulkan is the required graphics API.

Vulkan is supported on Windows 7, Windows 8, and Windows 10.

Some embedded systems support Vulkan by allowing presentation directly-to-display.

permalink: /Notes/004-3d-rendering/vulkan/chapters/checking_for_support.html ---

The first thing to check is if your platform even supports Vulkan. Each platform uses a different mechanism to manage how the Vulkan Loader is implemented. The loader is then in charge of determining if a Vulkan Driver is exposed correctly.

Just because the platform supports Vulkan does not mean there is device support. For device support, one will need to make sure a Vulkan Driver is available that fully implements Vulkan. There are a few different variations of a Vulkan Driver.

It is important to remember there is a difference between the instance-level version and device-level version. It is possible that the loader and implementations will support different versions.

The Querying Version Support section in the Vulkan Spec goes into details on how to query for supported versions at both the instance and device level.

There is only one supported header for all major releases of Vulkan. This means that there is no such thing as “Vulkan 1.0 headers” as all headers for a minor and patch version are unified. This should not be confused with the ability to generate a 1.0 version of the Vulkan Spec, as the Vulkan Spec and header of the same patch version will match. An example would be that the generated 1.0.42 Vulkan Spec will match the 1.x.42 header.

It is highly recommended that developers try to keep up to date with the latest header files released. The Vulkan SDK comes in many versions which map to the header version it will have been packaged for.

Between minor versions of Vulkan, some extensions get promoted to the core version. When targeting a newer minor version of Vulkan, an application will not need to enable the newly promoted extensions at the instance and device creation. However, if an application wants to keep backward compatibility, it will need to enable the extensions.

For a summary of what is new in each version, check out the Vulkan Release Summary

Structs and enums are dependent on the header file being used and not the version of the instance or device queried. For example, the struct VkPhysicalDeviceFeatures2 used to be VkPhysicalDeviceFeatures2KHR before Vulkan 1.1 was released. Regardless of the 1.x version of Vulkan being used, an application should use VkPhysicalDeviceFeatures2 in its code as it matches the newest header version. For applications that did have VkPhysicalDeviceFeatures2KHR in the code, there is no need to worry as the Vulkan header also aliases any promoted structs and enums (typedef VkPhysicalDeviceFeatures2 VkPhysicalDeviceFeatures2KHR;).

The reason for using the newer naming is that the Vulkan Spec itself will only refer to VkPhysicalDeviceFeatures2 regardless of what version of the Vulkan Spec is generated. Using the newer naming makes it easier to quickly search for where the structure is used.

Since functions are used to interact with the loader and implementations, there needs to be a little more care when working between minor versions. As an example, let’s look at vkGetPhysicalDeviceFeatures2KHR which was promoted to core as vkGetPhysicalDeviceFeatures2 from Vulkan 1.0 to Vulkan 1.1. Looking at the Vulkan header both are declared.

The main difference is when calling vkGetInstanceProcAddr(instance, “vkGetPhysicalDeviceFeatures2”); a Vulkan 1.0 implementation may not be aware of vkGetPhysicalDeviceFeatures2 existence and vkGetInstanceProcAddr will return NULL. To be backward compatible with Vulkan 1.0 in this situation, the application should query for vkGetPhysicalDeviceFeatures2KHR as a 1.1 Vulkan implementation will likely have the function directly pointed to the vkGetPhysicalDeviceFeatures2 function pointer internally.

Between minor versions, it is possible that some feature bits are added, removed, made optional, or made mandatory. All details of features that have changed are described in the Core Revisions section.

The Feature Requirements section in the Vulkan Spec can be used to view the list of features that are required from implementations across minor versions.

Currently, all versions of Vulkan share the same minimum/maximum limit requirements, but any changes would be listed in the Limit Requirements section of the Vulkan Spec.

Every minor version of Vulkan maps to a version of SPIR-V that must be supported.

It is up to the application to make sure that the SPIR-V in VkShaderModule is of a valid version to the corresponding Vulkan version.

permalink:/Notes/004-3d-rendering/vulkan/chapters/vulkan_release_summary.html layout: default ---

Vulkan 1.1 was released on March 7, 2018

Besides the listed extensions below, Vulkan 1.1 introduced the subgroups, protected memory, and the ability to query the instance version.

Vulkan 1.2 was released on January 15, 2020

Vulkan 1.3 was released on January 25, 2022

permalink: /Notes/004-3d-rendering/vulkan/chapters/what_is_spirv.html layout: default ---

Vulkan has an entire section that defines how Vulkan interfaces with SPIR-V shaders. Most valid usages of interfacing with SPIR-V occur during pipeline creation when shaders are compiled together.

SPIR-V has many capabilities as it has other targets than just Vulkan. To see the supported capabilities Vulkan requires, one can reference the Appendix. Some extensions and features in Vulkan are just designed to check if some SPIR-V capabilities are supported or not.

There is a rich ecosystem of tools to take advantage of SPIR-V. The Vulkan SDK gives an overview of all the SPIR-V tools that are built and packaged for developers.

Layered implementations fight industry fragmentation by enabling more applications to run on more platforms, even in a fragmented industry API landscape. For example, the first row in the diagram below shows how Vulkan is being used as a porting target to bring additional APIs to platforms to enable more content without the need for additional kernel-level drivers. Layered API implementations have been used to successfully ship production applications on multiple platforms.

The columns in the figure show layering projects being used to make APIs available across additional platforms, even if no native drivers are available, giving application developers the deployment flexibility they need to develop with the graphics API of their choice and ship across multiple platforms. The first column in the diagram is the work of the Vulkan Portability Initiative, enabling layered implementations of Vulkan functionality across diverse platforms.

Khronos Blog for information about macOS and iOS support

Mozilla is currently helping drive gfx-rs portability to use gfx-hal as a way to interface with various other APIs.

permalink:/Notes/004-3d-rendering/vulkan/chapters/vulkan_cts.html layout: default ---

Layers are optional components that augment the Vulkan system. They can intercept, evaluate, and modify existing Vulkan functions on their way from the application down to the hardware. Layers are implemented as libraries that can be enabled and configured using Vulkan Configurator.

Debugging something running on a GPU can be incredibly hard, luckily there are tools out there to help.

With anything related to a GPU it is best to not assume and profile when possible. Here is a list of known profilers to aid in your development.

permalink:/Notes/004-3d-rendering/vulkan/chapters/validation_overview.html layout: default ---

A VU is explicitly defined in the Vulkan Spec as:

One of the main advantages of Vulkan, as an explicit API, is that the implementation (driver) doesn’t waste time checking for valid input. In OpenGL, the implementation would have to always check for valid usage which added noticeable overhead. There is no glGetError equivalent in Vulkan.

The valid usages will be listed in the spec after every function and structure. For example, if a VUID checks for an invalid VkImage at VkBindImageMemory then the valid usage in the spec is found under VkBindImageMemory. This is because the Validation Layers will only know about all the information at VkBindImageMemory during the execution of the application.

When an application supplies invalid input, according to the valid usages in the spec, the result is undefined behavior. In this state, Vulkan makes no guarantees as anything is possible with undefined behavior.

VERY IMPORTANT: While undefined behavior might seem to work on one implementation, there is a good chance it will fail on another.

A VUID is an unique ID given to each valid usage. This allows a way to point to a valid usage in the spec easily.

Using VUID-vkBindImageMemory-memoryOffset-01046 as an example, it is as simple as adding the VUID to an anchor in the HMTL version of the spec (vkspec.html#VUID-vkBindImageMemory-memoryOffset-01046) and it will jump right to the VUID.

Since Vulkan doesn’t do any error checking, it is very important, when developing, to enable the Validation Layers right away to help catch invalid behavior. Applications should also never ship the Validation Layers with their application as they noticeably reduce performance and are designed for the development phase.

The Validation Layers attempt to supply as much useful information as possible when an error occurs. The following examples are to help show how to get the most information out of the Validation Layers

Currently, the spec is designed to only show the VUIDs depending on the version and extensions the spec was built with. Simply put, additions of extensions and versions may alter the VU language enough (from new API items added) that a separate VUID is created.

An example of this from the Vulkan-Docs where the spec in generated from

What this creates is two very similar VUIDs

In this example, both VUIDs are very similar and the only difference is the fact VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT is referenced in one and not this other. This is because the enum was added with the addition of VK_EXT_descriptor_indexing which is now part of Vulkan 1.2.

This means the 2 valid html links to the spec would look like

The Validation Layer uses the device properties of the application in order to decide which one to display. So in this case, if you are running on a Vulkan 1.2 implementation or a device that supports VK_EXT_descriptor_indexing it will display the VUID 03016.

The Best Practices layer will produce warnings when an application tries to use any extension with special usage tags. An example of such an extension is VK_EXT_transform_feedback which is only designed for emulation layers. If an application’s intended usage corresponds to one of the special use cases, the following approach will allow you to ignore the warnings.

Ignoring Special Usage Warnings with VK_EXT_debug_report

Ignoring Special Usage Warnings with VK_EXT_debug_utils

permalink: /Notes/004-3d-rendering/vulkan/chapters/decoder_ring.html ---

The Vulkan headers only provide the Vulkan function prototypes. When building a Vulkan application you have to link it to the loader or you will get errors about undefined references to the Vulkan functions. There are two ways of linking the loader, directly and indirectly, which should not be confused with “static and dynamic linking”.

Each platform can set its own rules on how to enforce the Vulkan Loader.

Layers are packaged as shared libraries that get dynamically loaded in by the loader and inserted between it and the application. The two things needed to use layers are the location of the binary files and which layers to enable. The layers to use can be either explicitly enabled by the application or implicitly enabled by telling the loader to use them. More details about implicit and explicit layers can be found in the Loader and Layer Interface.

The Vulkan SDK contains a layer configuration document that is very specific to how to discover and configure layers on each of the platforms.

Developers on Windows, Linux, and macOS can use the Vulkan Configurator, vkconfig, to enable explicit layers and disable implicit layers as well as change layer settings from a graphical user interface. Please see the Vulkan Configurator documentation in the Vulkan SDK for more information on using the Vulkan Configurator.

There used to be both instance layers and device layers, but device layers were deprecated early in Vulkan’s life and should be avoided.

Anyone can create a layer as long as it follows the loader to layer interface which is how the loader and layers agree to communicate with each other.

LunarG provides a framework for layer creation called the Layer Factory to help develop new layers (Video presentation). The layer factory hides the majority of the loader-layer interface, layer boilerplate, setup and initialization, and complexities of layer development. During application development, the ability to easily create a layer to aid in debugging your application can be useful. For more information, see the Vulkan Layer Factory documentation.

The way to load a layer in implicitly varies between loader and platform.

There are many other components in Vulkan that are labeled as properties. The term “properties” is an umbrella term for any read-only data that can be queried.

There are many times when a set of new functionality is desired in Vulkan that doesn’t currently exist. Extensions have the ability to add new functionality. Extensions may define new Vulkan functions, enums, structs, or feature bits. While all of these extended items are found by default in the Vulkan Headers, it is undefined behavior to use extended Vulkan if the extensions are not enabled.

Features describe functionality which is not supported on all implementations. Features can be queried and then enabled when creating the VkDevice. Besides the list of all features, some features are mandatory due to newer Vulkan versions or use of extensions.

A common technique is for an extension to expose a new struct that can be passed through pNext that adds more features to be queried.

Limits are implementation-dependent minimums, maximums, and other device characteristics that an application may need to be aware of. Besides the list of all limits, some limits also have minimum/maximum required values guaranteed from a Vulkan implementation.

Vulkan provides many VkFormat that have multiple VkFormatFeatureFlags each holding a various VkFormatFeatureFlagBits bitmasks that can be queried.

Checkout the Format chapter for more information.

There are a few tools to help with getting all the information in a quick and in a human readable format.

vulkaninfo is a command line utility for Windows, Linux, and macOS that enables you to see all the available items listed above about your GPU. Refer to the Vulkaninfo documentation in the Vulkan SDK.

The Vulkan Hardware Capability Viewer app developed by Sascha Willems, is an Android app to display all details for devices that support Vulkan.

permalink: /Notes/004-3d-rendering/vulkan/chapters/enabling_extensions.html ---

There are two groups of extensions, instance extensions and device extensions. Simply put, instance extensions are tied to the entire VkInstance while device extensions are tied to only a single VkDevice instance.

This information is documented under the “Extension Type” section of each extension reference page. Example below:

An application can query the physical device first to check if the extension is supported with vkEnumerateInstanceExtensionProperties or vkEnumerateDeviceExtensionProperties.

Even if the extension is supported by the implementation, it is undefined behavior to use the functionality of the extension unless it is enabled at VkInstance or VkDevice creation time.

Here is an example of what is needed to enable an extension such as VK_KHR_driver_properties.

It is important to remember that extensions add the existence of functionality to the Vulkan spec, but this doesn’t mean that all features of an extension are available if the extension is supported. An example is an extension such as VK_KHR_8bit_storage, which has 3 features it exposes in VkPhysicalDevice8BitStorageFeatures.

This means after enabling the extension, an application will still need to query and enable the features needed from an extension.

When minor versions of Vulkan are released, some extensions are promoted as defined in the spec. The goal of promotion is to have extended functionality, that the Vulkan Working Group has decided is widely supported, to be in the core Vulkan spec. More details about Vulkan versions can be found in the version chapter.

An example would be something such as VK_KHR_get_physical_device_properties2 which is used for most other extensions. In Vulkan 1.0, an application has to query for support of VK_KHR_get_physical_device_properties2 before being able to call a function such as vkGetPhysicalDeviceFeatures2KHR. Starting in Vulkan 1.1, the vkGetPhysicalDeviceFeatures2 function is guaranteed to be supported.

Another way to look at promotion is with the VK_KHR_8bit_storage as an example again. Since Vulkan 1.0 some features, such as textureCompressionASTC_LDR, are not required to be supported, but are available to query without needing to enable any extensions. Starting in Vulkan 1.2 when VK_KHR_8bit_storage was promoted to core, all the features in VkPhysicalDevice8BitStorageFeatures can now be found in VkPhysicalDeviceVulkan12Features.

All features in Vulkan can be categorized/found in 3 sections

All features must be enabled at VkDevice creation time inside the VkDeviceCreateInfo struct.

For the Core 1.0 Features, this is as simple as setting VkDeviceCreateInfo::pEnabledFeatures with the features desired to be turned on.

For all features, including the Core 1.0 Features, use VkPhysicalDeviceFeatures2 to pass into VkDeviceCreateInfo.pNext

The same works for the “Future Core Version Features” too.

permalink:/Notes/004-3d-rendering/vulkan/chapters/spirv_extensions.html layout: default ---

For this example, the VK_KHR_8bit_storage and SPV_KHR_8bit_storage will be used to expose the UniformAndStorageBuffer8BitAccess capability. The following is what the SPIR-V disassembled looks like:

It is important to understand that "format support" is not a single binary value per format, but rather each format has a set of VkFormatFeatureFlagBits that each describes with features are supported for a format.

The supported formats may vary across implementations, but a minimum set of format features are guaranteed. An application can query for the supported format properties.

Formats come in many variations, most can be grouped by the name of the format. When dealing with images, the VkImageAspectFlagBits values are used to represent which part of the data is being accessed for operations such as clears and copies.

There are various types of operations a VkQueue can support. A “Queue Family” just describes a set of VkQueue​s that have common properties and support the same functionality, as advertised in VkQueueFamilyProperties.

The following are the queue operations found in VkQueueFlagBits:

Unlike other handles such as VkDevice, VkBuffer, VkDeviceMemory, there is no vkCreateQueue or vkAllocateQueue. Instead, the driver is in charge of creating and destroying the VkQueue handles during vkCreateDevice/vkDestroyDevice time.

The following examples will use the hypothetical implementation which support 3 VkQueue​s from 2 Queue Families:

The following is an example how to create all 3 VkQueue​s with the logical device:

After creating the VkDevice the application can use vkGetDeviceQueue to get the VkQueue handles

permalink: /Notes/004-3d-rendering/vulkan/chapters/wsi.html ---

The VkSurfaceKHR object is platform agnostic and designed so the rest of the Vulkan API can use it for all WSI operations. It is enabled using the VK_KHR_surface extension.

Each platform that supports a Vulkan Surface has its own way to create a VkSurfaceKHR object from its respective platform-specific API.

Once a VkSurfaceKHR is created there are various capabilities, formats, and presentation modes to query for.

The VkSwapchainKHR object provides the ability to present rendering results to a surface through an array of VkImage objects. The swapchain’s various present modes determine how the presentation engine is implemented.

Khronos' sample and tutorial explain different considerations to make when creating a swapchain and selecting a presentation mode.

Mobile devices can be rotated, therefore the logical orientation of the application window and the physical orientation of the display may not match. Applications need to be able to operate in two modes: portrait and landscape. The difference between these two modes can be simplified to just a change in resolution. However, some display subsystems always work on the “native” (or “physical”) orientation of the display panel. Since the device has been rotated, to achieve the desired effect the application output must also rotate.

In order for your application to get the most out of Vulkan on mobile platforms, such as Android, implementing pre-rotation is a must. There is a detailed blog post from Google that goes over how to handle the surface rotation by specifying the orientation during swapchain creation and also comes with a standalone example. The Vulkan-Samples also has both a great write up of why pre-rotation is a problem as well as a sample to run that shows a way to solve it in the shader. If using an Adreno GPU powered device, Qualcomm suggests making use of the VK_QCOM_render_pass_transform extension to implement pre-rotation.

permalink:/Notes/004-3d-rendering/vulkan/chapters/pnext_and_stype.html layout: default ---

The Vulkan API provides two base structures, VkBaseInStructure and VkBaseOutStructure, to be used as a convenient way to iterate through a structure pointer chain.

The In of VkBaseInStructure refers to the fact pNext is a const * and are read-only to loader, layers, and driver receiving them. The Out of VkBaseOutStructure refers the pNext being used to return data back to the application.

Underneath, the loader, layers, and driver are now able to find the chained pNext structures. Here is an example to help illustrate how one could implement pNext from the loader, layer, or driver point of view.

permalink:/Notes/004-3d-rendering/vulkan/chapters/synchronization.html layout: default ---

The Khronos Validation Layer has implemented some validation for synchronization. It can easily be enabled by the Vulkan Configurator included with the Vulkan SDK. A detailed whitepaper discussing the synchronization validation has been written as well and released as a Khronos Blog.

Pipeline Barriers give control over which pipeline stages need to wait on previous pipeline stages when a command buffer is executed.

While Pipeline Barriers might be hard to understand at first, there are many great Khronos talks and other resources that go more in depth on the topic.

The VK_KHR_synchronization2 extension overhauls the original core synchronization APIs to reduce complexity for application developers, as well as adding a few additional features not present in the original APIs.

Read the VK_KHR_synchronization2 chapter for more info about the difference in the synchronization APIs and how to port over to using the new extension

permalink:/Notes/004-3d-rendering/vulkan/chapters/extensions/VK_KHR_synchronization2.html layout: default ---

One main change with the extension is to have pipeline stages and access flags now specified together in memory barrier structures. This makes the connection between the two more obvious.

The only new type of structure needed is VkDependencyInfoKHR, which wraps all the barriers into a single location.

Due to running out of the 32 bits for VkAccessFlag the VkAccessFlags2KHR type was created with a 64-bit range. To prevent the same issue for VkPipelineStageFlags, the VkPipelineStageFlags2KHR type was also created with a 64-bit range.

64-bit enumeration types are not available in all C/C++ compilers, so the code for the new fields uses static const values instead of an enum. As a result of this, there are no equivalent types to VkPipelineStageFlagBits and VkAccessFlagBits. Some code, including Vulkan functions such as vkCmdWriteTimestamp(), used the Bits type to indicate that the caller could only pass in a single bit value, rather than a mask of multiple bits. These calls need to be converted to take the Flags type and enforce the “only 1-bit” limitation via Valid Usage or the appropriate coding convention for your own code, as was done for vkCmdWriteTimestamp2KHR().

The new flags include identical bits to the original synchronization flags, with the same base name and identical values. Old flags can be used directly in the new APIs, subject to any typecasting constraints of the coding environment. The following 2 examples show the naming differences:

Updating the use of the pipeline stages and access flags in VkSubpassDependency requires simply using VkSubpassDependency2 which can have a VkMemoryBarrier2KHR passed in the pNext

Example would be taking

and turning it into

Some VkAccessFlags and VkPipelineStageFlags had values that were ambiguous to what it was targeting in hardware. The new VkAccessFlags2KHR and VkPipelineStageFlags2KHR break these up for some cases while leaving the old value for maintability.

The VK_ACCESS_SHADER_WRITE_BIT (now VK_ACCESS_2_SHADER_WRITE_BIT_KHR) was given an alias of VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT_KHR to better describe the scope of what resources in the shader are described by the access flag.

The use of VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT and VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT are now deprecated and updating is simple as following the following 4 case with the new equivalents.

VK_KHR_synchronization2 adds 2 new image layouts VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR and VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR to help with making layout transition easier.

The following uses the example of doing a draw thats writes to both a color attachment and depth/stencil attachment which then are both sampled in the next draw. Prior a developer needed to make sure they matched up the layouts and access mask correctly such as the following:

but with VK_KHR_synchronization2 this is made simple

In the new case VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR works by contextually appling itself based on the image format used. So as long as colorImageMemoryBarrier is used on a color format, VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR maps to VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

Additionally, with VK_KHR_synchronization2, if oldLayout is equal to newLayout, no layout transition is performed and the image contents are preserved. The layout used does not even need to match the layout of an image, so the following barrier is valid:

VK_KHR_synchronization2 adds the vkQueueSubmit2KHR command which main goal is to clean up the syntax for the function to wrap command buffers and semaphores in extensible structures, which incorporate changes from Vulkan 1.1, VK_KHR_device_group, and VK_KHR_timeline_semaphore.

Taking the following example of a normal queue submission call

this can now be transformed to vkQueueSubmit2KHR as

The difference between the two examples code snippets above is that the vkQueueSubmit2KHR will signal VkSemaphore signalSemaphore when the vertex shader stage is complete compared to the vkQueueSubmit call which will wait until the end of the submission.

To emulate the same behavior of semaphore signaling from vkQueueSubmit in vkQueueSubmit2KHR the stageMask can be set to VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT

For devices that do not natively support this extension, there is a portable implementation in the Vulkan-Extensionlayer repository. This layer should work with any Vulkan device. For more information see the layer documentation and the Sync2Compat.Vulkan10 test case.

permalink:/Notes/004-3d-rendering/vulkan/chapters/memory_allocation.html layout: default ---

Sub-allocation is considered to be a first-class approach when working in Vulkan. It is also important to realize there is a maxMemoryAllocationCount which creates a limit to the number of simultaneously active allocations an application can use at once. Memory allocation and deallocation at the OS/driver level is likely to be really slow which is another reason for sub-allocation. A Vulkan app should aim to create large allocations and then manage them itself.

The VkPhysicalDeviceType advertises two main different types of GPUs, discrete and integrated (also referred to as UMA (unified memory architecture). It is important for performance to understand the difference between the two.

Discrete graphics cards contain their own dedicated memory on the device. The data is transferred over a bus (such as PCIe) which is usually a bottleneck due to the physical speed limitation of transferring data. Some physical devices will advertise a queue with a VK_QUEUE_TRANSFER_BIT which allows for a dedicated queue for transferring data. The common practice is to create a staging buffer to copy the host data into before sending through a command buffer to copy over to the device local memory.

UMA systems share the memory between the device and host which is advertised with a VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT combination. The disadvantage of this is that system memory has to be shared with the GPU which requires being cautious of memory pressure. The main advantage is that there is no need to create a staging buffer and the transfer overhead is greatly reduced.

On tile-based architectures (virtually all mobile GPUs) the LAZILY_ALLOCATED_BIT memory type is not backed by actual memory. It can be used for attachments that can be held in tile memory, such as the G-buffer between subpasses, depth buffer, or multi-sampled images. This saves some significant bandwidth cost for writing the image back to memory. You can find more information in Khronos' tutorials on Render Passes and Subpasses.

permalink:/Notes/004-3d-rendering/vulkan/chapters/sparse_resources.html layout: default ---

Unlike normal resources that call vkBindBufferMemory() or vkBindImageMemory(), sparse memory is bound via a queue operation vkQueueBindSparse(). The main advantage of this is that an application can rebind memory to a sparse resource throughout its lifetime.

It is important to notice that this requires some extra consideration from the application. Applications must use synchronization primitives to guarantee that other queues do not access ranges of memory concurrently with a binding change. Also, freeing a VkDeviceMemory object with vkFreeMemory() will not cause resources (or resource regions) bound to the memory object to become unbound. Applications must not access resources bound to memory that has been freed.

The following example is used to help visually showcase how a sparse VkBuffer looks in memory. Note, it is not required, but most implementations will use sparse block sizes of 64 KB for VkBuffer (actual size is returned in VkMemoryRequirements::alignment).

Imagine a 256 KB VkBuffer where there are 3 parts that an application wants to update separately.

The following showcases how the application views the VkBuffer:

Protected memory was added in Vulkan 1.1 and there was no extension prior. This means any Vulkan 1.0 device will not be capable of supporting protected memory. To check for support, an application must query and enable the VkPhysicalDeviceProtectedMemoryFeatures::protectedMemory field.

A protected queue can read both protected and unprotected memory, but can only write to protected memory. If a queue can write to unprotected memory, then it can’t also read from protected memory.

Using vkGetPhysicalDeviceQueueFamilyProperties to get the VkQueueFlags of each queue, an application can find a queue family with VK_QUEUE_PROTECTED_BIT flag exposed. This does not mean the queues from the family are always protected, but rather the queues can be a protected queue.

To tell the driver to make the VkQueue protected, the VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT is needed in VkDeviceQueueCreateInfo during vkCreateDevice.

The following pseudo code is how an application could request for 2 protected VkQueue objects to be created from the same queue family:

It is also possible to split the queues in a queue family so some are protected and some are not. The following pseudo code is how an application could request for 1 protected VkQueue and 1 unprotected VkQueue objects to be created from the same queue family:

Now instead of using vkGetDeviceQueue an application has to use vkGetDeviceQueue2 in order to pass the VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT flag when getting the VkQueue handle.

When creating a VkImage or VkBuffer to make them protected is as simple as setting VK_IMAGE_CREATE_PROTECTED_BIT and VK_BUFFER_CREATE_PROTECTED_BIT respectively.

When binding memory to the protected resource, the VkDeviceMemory must have been allocated from a VkMemoryType with the VK_MEMORY_PROPERTY_PROTECTED_BIT bit.

When creating a swapchain the VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR bit is used to make a protected swapchain.

All VkImage from vkGetSwapchainImagesKHR using a protected swapchain are the same as if the image was created with VK_IMAGE_CREATE_PROTECTED_BIT.

Sometimes it is unknown whether swapchains can be created with the VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR flag set. The VK_KHR_surface_protected_capabilities extension is exposed on platforms where this might be unknown.

Using the protected VkQueue, an application can also use VK_COMMAND_POOL_CREATE_PROTECTED_BIT when creating a VkCommandPool

All command buffers allocated from the protected command pool become “protected command buffers”

When submitting work to be protected, all the VkCommandBuffer submitted must also be protected.

or using VK_KHR_synchronization2

permalink:/Notes/004-3d-rendering/vulkan/chapters/pipeline_cache.html layout: default ---

Command Pools are a system to allow recording command buffers across multiple threads. A single command pool must be externally synchronized; it must not be accessed simultaneously from multiple threads. By using a separate command pool in each host-thread the application can create multiple command buffers in parallel without any costly locks.

The idea is command buffers can be recorded on multiple threads while having a relatively light thread handle the submissions.

Khronos' sample and tutorial show in more detail how to record command buffers in parallel.

Descriptor Pools are used to allocate, free, reset, and update descriptor sets. By creating multiple descriptor pools, each application host thread is able to manage a descriptor set in each descriptor pool at the same time.

permalink: /Notes/004-3d-rendering/vulkan/chapters/depth.html layout: default ---

The concept of "depth" is only used for graphics pipelines in Vulkan and doesn’t take effect until a draw call is submitted.

Inside the VkGraphicsPipelineCreateInfo there are many different values related to depth that can be controlled. Some states are even dynamic as well.

There are a few different depth formats and an implementation may expose support for in Vulkan.

For reading from a depth image only VK_FORMAT_D16_UNORM and VK_FORMAT_D32_SFLOAT are required to support being read via sampling or blit operations.

For writing to a depth image VK_FORMAT_D16_UNORM is required to be supported. From here at least one of (VK_FORMAT_X8_D24_UNORM_PACK32 or VK_FORMAT_D32_SFLOAT) and (VK_FORMAT_D24_UNORM_S8_UINT or VK_FORMAT_D32_SFLOAT_S8_UINT) must also be supported. This will involve some extra logic when trying to find which format to use if both the depth and stencil are needed in the same format.

The term "depth buffer" is used a lot when talking about graphics, but in Vulkan, it is just a VkImage/VkImageView that a VkFramebuffer can reference at draw time. When creating a VkRenderPass the pDepthStencilAttachment value points to the depth attachment in the framebuffer.

In order to use pDepthStencilAttachment the backing VkImage must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT.

When performing operations such as image barriers or clearing where the VkImageAspectFlags is required, the VK_IMAGE_ASPECT_DEPTH_BIT is used to reference the depth memory.

In the graphics pipeline, there are a series of pre-rasterization shader stages that generate primitives to be rasterized. Before reaching the rasterization step, the final vec4 position (gl_Position) of the last pre-rasterization stage runs through Fixed-Function Vertex Post-Processing.

The following gives a high level overview of the various coordinates name and operations that occur before rasterization.

The only shader stage in core Vulkan that has an input attribute controlled by Vulkan is the vertex shader stage (VK_SHADER_STAGE_VERTEX_BIT). This involves declaring the interface slots when creating the VkPipeline and then binding the VkBuffer before draw time with the data to map. Other shaders stages, such as a fragment shader stage, has input attributes, but the values are determined from the output of the previous stages ran before it.

Before calling vkCreateGraphicsPipelines a VkPipelineVertexInputStateCreateInfo struct will need to be filled out with a list of VkVertexInputAttributeDescription mappings to the shader.

An example GLSL vertex shader:

There is only a single input attribute at location 0. This can also be seen in the generated SPIR-V assembly:

In this example, the following could be used for the VkVertexInputAttributeDescription:

The only thing left to do is bind the vertex buffer and optional index buffer prior to the draw call.

A resource descriptor is the core way to map data such as uniform buffers, storage buffers, samplers, etc. to any shader stage in Vulkan. One way to conceptualize a descriptor is by thinking of it as a pointer to memory that the shader can use.

There are various descriptor types in Vulkan, each with their own detailed description in what they allow.

Descriptors are grouped together in descriptor sets which get bound to the shader. Even if there is only a single descriptor in the descriptor set, the entire VkDescriptorSet is used when binding to the shader.

A push constant is a small bank of values accessible in shaders. Push constants allow the application to set values used in shaders without creating buffers or modifying and binding descriptor sets for each update.

These are designed for small amount (a few dwords) of high frequency data to be updated per-recording of the command buffer.

From a shader perspective, it is similar to a uniform buffer.

Resulting SPIR-V assembly:

While recording the command buffer the values of the push constants are decided.

Specialization constants are a mechanism allowing a constant value in SPIR-V to be specified at VkPipeline creation time. This is powerful as it replaces the idea of doing preprocessor macros in the high level shading language (GLSL, HLSL, etc).

The VK_KHR_buffer_device_address extension promoted to Vulkan 1.2 adds the ability to have “pointers in the shader”. Using the PhysicalStorageBuffer storage class in SPIR-V an application can call vkGetBufferDeviceAddress which will return the VkDeviceAddress to the memory.

While this is a way to map data to the shader, it is not a way to interface with the shader. For example, if an application wants to use this with a uniform buffer it would have to create a VkBuffer with both VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT and VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT. From here in this example, Vulkan would use a descriptor to interface with the shader, but could then use the physical storage buffer to update the value after.

With all the above examples it is important to be aware that there are limits in Vulkan that expose how much data can be bound at a single time.

permalink:/Notes/004-3d-rendering/vulkan/chapters/vertex_input_data_processing.html layout: default ---

A binding is tied to a position in the vertex buffer from which the vertex shader will start reading data out of during a vkCmdDraw* call. Changing the bindings does not require making any alterations to an app’s vertex shader source code.

As an example, the following code matches the diagram of how bindings work.

The following examples show various ways to set your binding and location values depending on your data input.

The VkVertexInputAttributeDescription::format can be the cause of confusion. The format field just describes the size and type of the data the shader should read in.

The reason for using the VkFormat values is they are well defined and match the input layouts of the vertex shader.

For this example the vertex data is just four floats:

The data being read will be overlapped from how the format and offset is set

When reading in the data in the shader the value will be the same where it overlaps

It is important to notice that in1 is a vec2 while the input attribute is VK_FORMAT_R32G32B32_SFLOAT which doesn’t fully match. According to the spec:

So in this case, the last component of location 1 (d) is discarded and would not be read in by the shader.

The spec explains more in detail about the Component assignment. The following is a general overview of the topic.

This example will have buffer of 32 bytes and 16 of the bytes will be set at vkUpdateDescriptorSets time. In this first example, we will not add any dynamic offset.

Our buffer now currently looks like the following:

Next, a 8 byte dynamic offset will applied at bind time.

Our buffer currently looks like the following:

This time the VK_WHOLE_SIZE value will be used for the range. Everything looks the same as the above example except the VkDescriptorBufferInfo::range

Our buffer currently looks like the following:

This time, if we attempt to apply a dynamic offset it will be met with undefined behavior and the validation layers will give an error

This is what it looks like with the invalid dynamic offset

It is important to also check the minUniformBufferOffsetAlignment and minStorageBufferOffsetAlignment as both the base offset and dynamic offset must be multiples of these limits.

permalink:/Notes/004-3d-rendering/vulkan/chapters/robustness.html layout: default ---

When a Vulkan application tries to access (load, store, or perform an atomic on) memory it doesn’t have access to, the implementation must react somehow. In the case where there is no robustness, it is undefined behavior and the implementation is even allowed to terminate the program. If robustness is enabled for the type of memory accessed, then the implementation must behave a certain way as defined by the spec.

The nature of some Vulkan applications requires the ability run shader code that cannot be guaranteed to avoid bad memory accesses. Robustness is needed for these applications.

All Vulkan implementations are required to support the robustBufferAccess feature. The spec describes what is considered out-of-bounds and also how it should be handled. Implementations are given some amount of flexibility for robustBufferAccess. An example would be accessing a vec4(x,y,z,w) where the w value is out-of-bounds as the spec allows the implementation to decide if the x, y, and z are also considered out-of-bounds or not.

If dealing with the update after bind functionality found in VK_EXT_descriptor_indexing (which is core as of Vulkan 1.2) it is important to be aware of the robustBufferAccessUpdateAfterBind which indicates if an implementation can support both robustBufferAccess and the ability to update the descriptor after binding it.

The robustBufferAccess feature has some limitations as it only covers buffers and not images. It also allows out-of-bounds writes and atomics to modify the data of the buffer being accessed. For applications looking for a stronger form of robustness, there is VK_EXT_robustness2.

When images are out-of-bounds core Vulkan provides the guarantee that stores and atomics have no effect on the memory being accessed.

Some applications, such as those being ported from other APIs such as D3D12, require stricter guarantees than robustBufferAccess and robustImageAccess provide. The VK_EXT_robustness2 extension adds this by exposing 3 new robustness features, described in the following sections. For some implementations these extra guarantees can come at a performance cost. Applications that don’t need the extra robustness are recommended to use robustBufferAccess and/or robustImageAccess instead where possible.

When creating a graphics VkPipeline object the logical flow for setting state is:

When the VkPipeline uses dynamic state, some pipeline information can be omitted at creation time and instead set during recording of the command buffer. The new logical flow is:

Some implementations might have a performance loss using some certain VkDynamicState state over a static value, but dynamic states might prevent an application from having to create many permutations of pipeline objects which might be a bigger desire for the application.

The full list of possible dynamic states can be found in VkDynamicState.

The VK_EXT_extended_dynamic_state, VK_EXT_extended_dynamic_state2, VK_EXT_vertex_input_dynamic_state, and VK_EXT_color_write_enable extensions were added with the goal to support applications that need to reduce the number of pipeline state objects they compile and bind.

permalink:/Notes/004-3d-rendering/vulkan/chapters/subgroups.html layout: default ---

For more detailed information about subgroups there is a great Khronos blog post as well as a presentation from Vulkan Developer Day 2018 (slides and video). GLSL support can be found in the GL_KHR_shader_subgroup extension.

It is important to also realize the size of a subgroup can be dynamic for an implementation. Some implementations may dispatch shaders with a varying subgroup size for different subgroups. As a result, they could implicitly split a large subgroup into smaller subgroups or represent a small subgroup as a larger subgroup, some of whose invocations were inactive on launch.

With Vulkan 1.1, all the information for subgroups is found in VkPhysicalDeviceSubgroupProperties

This extension allows subgroup operations to use 8-bit integer, 16-bit integer, 64-bit integer, 16-bit floating-point, and vectors of these types in group operations with subgroup scope if the implementation supports the types already.

For example, if an implementation supports 8-bit integers an application can now use the GLSL genI8Type subgroupAdd(genI8Type value); call which will get mapped to OpGroupNonUniformFAdd in SPIR-V.

VK_EXT_shader_subgroup_ballot and VK_EXT_shader_subgroup_vote were the original efforts to expose subgroups in Vulkan. If an application is using Vulkan 1.1 or greater, there is no need to use these extensions and should instead use the core API to query for subgroup support.

permalink:/Notes/004-3d-rendering/vulkan/chapters/shader_memory_layout.html layout: default ---

Vulkan has 3 alignment requirements that interface objects can be laid out in.

The spec language for alignment breaks down the rule for each of the following block member types.

This extension allows the use of std430 memory layout in UBOs. Vulkan Standard Buffer Layout Interface can be found outside this guide. These memory layout changes are only applied to Uniforms as other storage items such as Push Constants and SSBO already allow for std430 style layouts.

One example of when the uniformBufferStandardLayout feature is needed is when an application doesn’t want the array stride for a UBO to be restricted to extended alignment

Which translates in SPIR-V to

Make sure to set --uniform-buffer-standard-layout when running the SPIR-V Validator.

This extension allows implementations to indicate they can support more variation in block Offset decorations. This comes up when using std430 memory layout where a vec3 (which is 12 bytes) is still defined as a 16 byte alignment. With relaxed block layout an application can fit a float on either side of the vec3 and maintain the 16 byte alignment between them.

VK_KHR_relaxed_block_layout can also be seen as a subset of VK_EXT_scalar_block_layout

This extension allows most storage types to be aligned in scalar alignment. A big difference is being able to straddle the 16-byte boundary.

In GLSL this can be used with scalar keyword and extension

The following are some GLSL to SPIR-V examples to help better understand the difference in the alignments supported.

To better understand the different extensions, it is first important to be aware of the various types of atomics exposed.

With Vulkan 1.0 and no extensions, an application is allowed to use 32-bit int type for atomics. This can be used for all supported SPIR-V operations (load, store, exchange, etc). SPIR-V contains some atomic operations that are guarded with the Kernel capability and are not currently allowed in Vulkan.

This extension allows for 64-bit int atomic operations for buffers and shared memory. If the Int64Atomics SPIR-V capability is declared, all supported SPIR-V operations can be used with 64-bit int.

The two feature bits, shaderBufferInt64Atomics and shaderSharedInt64Atomics, are used to query what storage classes are supported for 64-bit int atomics.

The shaderBufferInt64Atomics is always guaranteed to be supported if using Vulkan 1.2+ or the extension is exposed.

This extension allows for 64-bit int atomic operations for images and sparse images. If the Int64Atomics and Int64ImageEXT SPIR-V capability is declared, all supported SPIR-V operations can be used with 64-bit int on images.

This extension allows for float atomic operations for buffers, shared memory, images, and sparse images. Only a subset of operations is supported for float types with this extension.

The extension lists many feature bits. One way to group them is by *Float*Atomics and *Float*AtomicAdd:

From here the rest of the permutations of features fall into the grouping of 32-bit float support:

and 64-bit float support:

This extension adds 2 additional sets of features missing in VK_EXT_shader_atomic_float

First, it adds 16-bit floats for both buffers and shared memory in the same fashion as found above for VK_EXT_shader_atomic_float.

Second, it adds float support for min and max atomic operations (OpAtomicFMinEXT and OpAtomicFMaxEXT)

For 16-bit float support (with AtomicFloat16MinMaxEXT capability):

For 32-bit float support (with AtomicFloat32MinMaxEXT capability):

For 64-bit float support (with AtomicFloat64MinMaxEXT capability):

permalink: /Notes/004-3d-rendering/vulkan/chapters/common_pitfalls.html ---

During development, ensure that the Validation Layers are enabled. They are an invaluable tool for catching mistakes while using the Vulkan API. Parameter checking, object lifetimes, and threading violations all are part of the provided error checks. A way to reassure that they are enabled is to verify if the text “Debug Messenger Added” is in the output stream. More info can be found in the Vulkan SDK layer documentation.

In Vulkan, most problems can be tackled with multiple methods, each with their own benefits and drawbacks. There is rarely a “perfect” solution and obsessing over finding one is often a fruitless effort. When faced with a problem, try to create an adequate solution that meets the current needs and isn’t overly convoluted. While the specification for Vulkan can be useful, it isn’t the best source for how to use Vulkan in practice. Instead, reference external sources, like this guide, hardware best practice guides, tutorials, and other articles for more in-depth information. Finally, profiling various solutions is an important part of discovering which solution to use.

Many early Vulkan tutorials and documents recommended writing a command buffer once and re-using it wherever possible. In practice however re-use rarely has the advertized performance benefit while incurring a non-trivial development burden due to the complexity of implementation. While it may appear counterintuitive, as re-using computed data is a common optimization, managing a scene with objects being added and removed as well as techniques such as frustum culling which vary the draw calls issued on a per frame basis make reusing command buffers a serious design challenge. It requires a caching scheme to manage command buffers and maintaining state for determining if and when re-recording becomes necessary. Instead, prefer to re-record fresh command buffers every frame. If performance is a problem, recording can be multithreaded as well as using secondary command buffers for non-variable draw calls, like post processing.

A graphics VkPipeline contains the combination of state needed to perform a draw call. Rendering a scene with different shaders, blending modes, vertex layouts, etc, will require a pipeline for each possibility. Because pipeline creation and swapping them between draw calls have an associated cost, it is a good practice to create and swap pipelines only as needed. However, by using various techniques and features to further reduce creation and swapping beyond the simple cases can be counterproductive, as it adds complexity with no guarantee of benefit. For large engines this may be necessary, but otherwise it is unlikely to be a bottleneck. Using the pipeline cache can further reduce the costs without resorting to more complex schemes.

Pipelining frames is a common way to improve performance. By having multiple frames rendering at the same time, each using their own copy of the required resources, it reduces latency by removing resource contention. A simple implementation of this will duplicate the resources needed by each image in the swapchain. The issue is that this leads to assuming rendering resources must be duplicated once for each swapchain image. While practical for some resources, like the command buffers and semaphores used for each frame, the one-to-one duplication with swapchain images isn’t often necessary. Vulkan offers a large amount of flexibility, letting the developer choose what level of duplication is right for their situation. Many resources may only need two copies, for example, uniform buffers or data which is updated once per frame, and others may not need any duplication at all.

Several hardware platforms have more than one VkQueue per queue family. This can be useful by being able to submit work to the same queue family from separate queues. While there can be advantages, it isn’t necessarily better to create or use the extra queues. For specific performance recommendations, refer to hardware vendors' best practices guides.

Descriptor Sets are designed to facilitate grouping data used in shaders by usage and update frequency. The Vulkan Spec mandates that hardware supports using at least 4 Descriptor Sets at a time, with most hardware supporting at least 8. Therefore there is very little reason not to use more than one where it is sensible.

While the Validation Layers can catch many types of errors, they are not perfect. Below is a short list of good habits and possible sources of error when encountering odd behavior.

permalink: /Notes/004-3d-rendering/vulkan/chapters/hlsl.html ---

From the application’s point-of-view, using HLSL is exactly the same as using GLSL. As the application always consumes shaders in the SPIR-V format, the only difference is in the tooling to generate the SPIR-V shaders from the desired shading language.

A great starting point on using HLSL in Vulkan via SPIR-V is the HLSL to SPIR-V feature mapping manual. It contains detailed information on semantics, syntax, supported features and extensions and much more and is a must-read. The decoder ring also has a translation table for concepts and terms used in Vulkan an DirectX.

To make HLSL compatible with Vulkan, an implicit namespace has been introduced that provides an interface for for Vulkan-specific features.

Similar to regular programming languages, HLSL and GLSL differ in their syntax. While GLSL is more procedural (like C), HLSL is more object-oriented (like C++).

Here is the same shader written in both languages to give quick comparison on how they basically differ, including the aforementioned namespace that e.g. adds explicit locations:

As is the case with GLSL to SPIR-V, to use HLSL with Vulkan, a shader compiler is required. Whereas glslang is the reference GLSL to SPIR-V compiler, the DirectXShaderCompiler (DXC) is the reference HLSL to SPIR-V compiler. Thanks to open source contributions, the SPIR-V backend of DXC is now supported and enabled in official release builds and can be used out-of-the box. While other shader compiling tools like glslang also offer HLSL support, DXC has the most complete and up-to-date support and is the recommended way of generating SPIR-V from HLSL.

DirectX and HLSL use a fixed shader model notion to describe the supported feature set. This is different from Vulkan and SPIR-V’s flexible extension based way of adding features to shaders. The following table tries to list Vulkan’s coverage for the HLSL shader models without guarantee of completeness:

This extension adds more information to query about each implementation. The VkDriverId will be a registered vendor’s ID for the implementation. The VkConformanceVersion displays which version of the Vulkan Conformance Test Suite the implementation passed.

This extension allows an application to call vkResetQueryPool from the host instead of needing to setup logic to submit vkCmdResetQueryPool since this is mainly just a quick write to memory for most implementations.

This extension allows an application when using a depth/stencil format to do an image translation on each the depth and stencil separately. Starting in Vulkan 1.2 this functionality is required for all implementations.

This extension adds support for automatically resolving multisampled depth/stencil attachments in a subpass in a similar manner as for color attachments.

For more information please check out the GDC presentation. (slides and video)

There are formats that express both the usage of depth and stencil, but there was no way to list a different usage for them. The VkImageStencilUsageCreateInfo now lets an application pass in a separate VkImageUsageFlags for the stencil usage of an image. The depth usage is the original usage passed into VkImageCreateInfo::usage and without using VkImageStencilUsageCreateInfo the stencil usage will be the same as well.

A good use case of this is when using the VK_KHR_image_format_list extension. This provides a way for the application to more explicitly describe the possible image views of their VkImage at creation time. This allows some implementations to possibly do implementation dependent optimization depending on the usages set.

Normally applications allocate large chunks for VkDeviceMemory and then suballocate to various buffers and images. There are times where it might be better to have a dedicated allocation for VkImage or VkBuffer. An application can pass VkMemoryDedicatedRequirements into vkGetBufferMemoryRequirements2 or vkGetImageMemoryRequirements2 to find out if a dedicated allocation is preferred or required. When dealing with external memory it will often require a dedicated allocation.

By default, Vulkan samplers using linear filtering return a filtered texel value produced by computing a weighted average of a collection of texels in the neighborhood of the texture coordinate provided. This extension provides a new sampler parameter which allows applications to produce a filtered texel value by computing a component-wise minimum (VK_SAMPLER_REDUCTION_MODE_MIN) or maximum (VK_SAMPLER_REDUCTION_MODE_MAX) of the texels that would normally be averaged. This is similar to GL EXT_texture_filter_minmax.

This extension adds a new sampler address mode (VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE) that effectively uses a texture map twice as large as the original image in which the additional half of the new image is a mirror image of the original image. This new mode relaxes the need to generate images whose opposite edges match by using the original image to generate a matching “mirror image”. This mode allows the texture to be mirrored only once in the negative s, t, and r directions.

These extensions add new VkFormat that were not originally in the spec

This extension adds a new VkFormatFeatureFlagBits2KHR 64bits format feature flag type to extend the existing VkFormatFeatureFlagBits which is limited to 31 flags.

This extension adds an exception for VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16 in the validation layers to allow being able to render to the format.

The maintenance extensions add a collection of minor features that were intentionally left out or overlooked from the original Vulkan 1.0 release.

Currently, there are 4 maintenance extensions. The first 3 were bundled in Vulkan 1.1 as core. All the details for each are well defined in the extension appendix page.

There have been a few times where the Vulkan Working Group realized that some structs in the original 1.0 Vulkan spec were missing the ability to be extended properly due to missing sType/pNext.

Keeping backward compatibility between versions is very important, so the best solution was to create an extension to amend the mistake. These extensions are mainly new structs, but also need to create new function entry points to make use of the new structs.

The current list of extensions that fit this category are:

All of these are very simple extensions and were promoted to core in their respective versions to make it easier to use without having to query for their support.

The VK_KHR_external_fence_capabilities, VK_KHR_external_semaphore_capabilities, and VK_KHR_external_memory_capabilities are simply just ways to query information about what external support an implementation provides.

There is a set of extensions to handle the importing/exporting of just the memory itself. The other set extensions are for the synchronization primitives (VkFence and VkSemaphore) used to control internal Vulkan commands. It is common practice that for each piece of memory imported/exported there is also a matching fence/semaphore to manage the memory access.

Here is a simple diagram showing the timeline of events between Vulkan and some other API talking to the GPU. This is used to represent a common use case for these external memory and synchronization extensions.

permalink:/Notes/004-3d-rendering/vulkan/chapters/extensions/ray_tracing.html layout: default ---

Acceleration structures are an implementation-dependent opaque representation of geometric objects, which are used for ray tracing. By building objects into acceleration structures, ray tracing can be performed against a known data layout, and in an efficient manner. The VK_KHR_acceleration_structure extension introduces functionality to build and copy acceleration structures, along with functionality to support serialization to/from memory.

Acceleration structures are required for both ray pipelines (VK_KHR_ray_tracing_pipeline) and ray queries (VK_KHR_ray_query).

To create an acceleration structure:

The VK_KHR_ray_tracing_pipeline extension introduces ray tracing pipelines. This new form of rendering pipeline is independent of the traditional rasterization pipeline. Ray tracing pipelines utilize a dedicated set of shader stages, distinct from the traditional vertex/geometry/fragment stages. Ray tracing pipelines also utilize dedicated commands to submit rendering work (vkCmdTraceRaysKHR and vkCmdTraceRaysIndirectKHR). These commands can be regarded as somewhat analagous to the drawing commands in traditional rasterization pipelines (vkCmdDraw and vkCmdDrawIndirect).

To trace rays:

Ray tracing pipelines introduce several new shader domains. These are described below:

The VK_KHR_ray_query extension provides support for tracing rays from all shader types, including graphics, compute, and ray tracing pipelines.

Ray query requires that ray traversal code is explicitly included within the shader. This differs from ray tracing pipelines, where ray generation, intersection testing and handling of ray-geometry hits are represented as separate shader stages. Consequently, whilst ray query allows rays to be traced from a wider range of shader stages, it also restricts the range of optimizations that a Vulkan implementation might apply to the scheduling and tracing of rays.

The extension does not introduce additional API entry-points. It simply provides API support for the related SPIR-V and GLSL extensions (SPV_KHR_ray_query and GLSL_EXT_ray_query).

The functionality provided by VK_KHR_ray_query is complementary to that provided by VK_KHR_ray_tracing_pipeline, and the two extensions can be used together.

VK_KHR_pipeline_library introduces pipeline libraries. A pipeline library is a special pipeline that was created using the VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and cannot be bound and used directly. Instead, these are pipelines that represent a collection of shaders, shader groups and related state which can be linked into other pipelines.

VK_KHR_pipeline_library does not introduce any new API functions directly, or define how to create a pipeline library. Instead, this functionality is left to other extensions which make use of the functionality provided by VK_KHR_pipeline_library. Currently, the only example of this is VK_KHR_ray_tracing_pipeline. VK_KHR_pipeline_library was defined as a separate extension to allow for the possibility of using the same functionality in other extensions in the future without introducing a dependency on the ray tracing extensions.

To create a ray tracing pipeline library:

To link ray tracing pipeline libraries into a full pipeline:

VK_KHR_deferred_host_operations introduces a mechanism for distributing expensive CPU tasks across multiple threads. Rather than introduce a thread pool into Vulkan drivers, VK_KHR_deferred_host_operations is designed to allow an application to create and manage the threads.

As with VK_KHR_pipeline_library, VK_KHR_deferred_host_operations was defined as a separate extension to allow for the possibility of using the same functionality in other extensions in the future without introducing a dependency on the ray tracing extensions.

Only operations that are specifically noted as supporting deferral may be deferred. Currently the only operations which support deferral are vkCreateRayTracingPipelinesKHR, vkBuildAccelerationStructuresKHR, vkCopyAccelerationStructureKHR, vkCopyMemoryToAccelerationStructureKHR, and vkCopyAccelerationStructureToMemoryKHR

To request that an operation is deferred:

To join a thread to a deferred operation, and contribute CPU time to progressing the operation:

After an operation has completed (i.e. vkDeferredOperationJoinKHR has returned VK_SUCCESS), call vkGetDeferredOperationResultKHR to get the result of the operation.

permalink:/Notes/004-3d-rendering/vulkan/chapters/extensions/shader_features.html layout: default ---

This extension is designed for a Vulkan 1.1 implementations to expose the SPIR-V 1.4 feature set. Vulkan 1.1 only requires SPIR-V 1.3 and some use cases were found where an implementation might not upgrade to Vulkan 1.2, but still want to offer SPIR-V 1.4 features.

Both VK_KHR_8bit_storage (promoted in Vulkan 1.2) and VK_KHR_16bit_storage (promoted in Vulkan 1.1) were added to allow the ability to use small values as input or output to a SPIR-V storage object. Prior to these extensions, all UBO, SSBO, and push constants needed to consume at least 4 bytes. With this, an application can now use 8-bit or 16-bit values directly from a buffer. It is also commonly paired with the use of VK_KHR_shader_float16_int8 as this extension only deals with the storage interfaces.

The following is an example of using SPV_KHR_8bit_storage with the GLSL extension:

With the extension

This extension allows the use of 8-bit integer types or 16-bit floating-point types for arithmetic operations. This does not allow for 8-bit integer types or 16-bit floating-point types in any shader input and output interfaces and therefore is commonly paired with the use of VK_KHR_8bit_storage and VK_KHR_16bit_storage.

This extension allows the ability to set how rounding of floats are handled. The VkPhysicalDeviceFloatControlsProperties shows the full list of features that can be queried. This is useful when converting OpenCL kernels to Vulkan.

Originally SPIR-V combined both UBO and SSBO into the 'Uniform' storage classes and differentiated them only through extra decorations. Because some hardware treats UBO an SSBO as two different storage objects, the SPIR-V wanted to reflect that. This extension serves the purpose of extending SPIR-V to have a new StorageBuffer class.

An example of this can be seen if you take the following GLSL shader snippet:

If you target Vulkan 1.0 (which requires SPIR-V 1.0), using glslang --target-env vulkan1.0, you will get something like:

Since SPV_KHR_storage_buffer_storage_class was added to SPIR-V 1.3, if you target Vulkan 1.1 (which requires SPIR-V 1.3) ,using glslang --target-env vulkan1.1, it will make use of the new StorageBuffer class.