Vulkan Cookbook

By : Pawel Lapinski

Vulkan Cookbook

By: Pawel Lapinski

Overview of this book

Vulkan is the next generation graphics API released by the Khronos group. It is expected to be the successor to OpenGL and OpenGL ES, which it shares some similarities with such as its cross-platform capabilities, programmed pipeline stages, or nomenclature. Vulkan is a low-level API that gives developers much more control over the hardware, but also adds new responsibilities such as explicit memory and resources management. With it, though, Vulkan is expected to be much faster. This book is your guide to understanding Vulkan through a series of recipes. We start off by teaching you how to create instances in Vulkan and choose the device on which operations will be performed. You will then explore more complex topics such as command buffers, resources and memory management, pipelines, GLSL shaders, render passes, and more. Gradually, the book moves on to teach you advanced rendering techniques, how to draw 3D scenes, and how to improve the performance of your applications. By the end of the book, you will be familiar with the latest advanced techniques implemented with the Vulkan API, which can be used on a wide range of platforms.

Preface

What this book covers

What you need for this book

Free Chapter

Instance and Devices

Introduction

Downloading Vulkan's SDK

Enabling validation layers

Connecting with a Vulkan Loader library

Preparing for loading Vulkan API functions

Loading functions exported from a Vulkan Loader library

Loading global-level functions

Checking available Instance extensions

Creating a Vulkan Instance

Loading instance-level functions

Enumerating available physical devices

Checking available device extensions

Getting features and properties of a physical device

Checking available queue families and their properties

Selecting the index of a queue family with the desired capabilities

Creating a logical device

Loading device-level functions

Getting a device queue

Creating a logical device with geometry shaders, graphics, and compute queues

Destroying a logical device

Destroying a Vulkan Instance

Releasing a Vulkan Loader library

Image Presentation

Introduction

Creating a Vulkan Instance with WSI extensions enabled

Creating a presentation surface

Selecting a queue family that supports presentation to a given surface

Creating a logical device with WSI extensions enabled

Selecting a desired presentation mode

Getting the capabilities of a presentation surface

Selecting a number of swapchain images

Choosing a size of swapchain images

Selecting desired usage scenarios of swapchain images

Selecting a transformation of swapchain images

Selecting a format of swapchain images

Creating a swapchain

Getting handles of swapchain images

Creating a swapchain with R8G8B8A8 format and a mailbox present mode

Acquiring a swapchain image

Presenting an image

Destroying a swapchain

Destroying a presentation surface

Command Buffers and Synchronization

Introduction

Creating a command pool

Allocating command buffers

Beginning a command buffer recording operation

Ending a command buffer recording operation

Resetting a command buffer

Resetting a command pool

Submitting command buffers to a queue

Synchronizing two command buffers

Checking if processing of a submitted command buffer has finished

Waiting until all commands submitted to a queue are finished

Waiting for all submitted commands to be finished

Destroying a fence

Destroying a semaphore

Freeing command buffers

Destroying a command pool

Resources and Memory

Introduction

Creating a buffer

Allocating and binding a memory object for a buffer

Setting a buffer memory barrier

Creating a buffer view

Creating an image

Allocating and binding a memory object to an image

Setting an image memory barrier

Creating an image view

Creating a 2D image and view

Creating a layered 2D image with a CUBEMAP view

Mapping, updating and unmapping host-visible memory

Copying data between buffers

Copying data from a buffer to an image

Copying data from an image to a buffer

Using a staging buffer to update a buffer with a device-local memory bound

Using a staging buffer to update an image with a device-local memory bound

Destroying an image view

Destroying an image

Destroying a buffer view

Freeing a memory object

Destroying a buffer

Descriptor Sets

Introduction

Creating a sampler

Creating a sampled image

Creating a combined image sampler

Creating a storage image

Creating a uniform texel buffer

Creating a storage texel buffer

Creating a uniform buffer

Creating a storage buffer

Creating an input attachment

Creating a descriptor set layout

Creating a descriptor pool

Allocating descriptor sets

Updating descriptor sets

Binding descriptor sets

Creating descriptors with a texture and a uniform buffer

Freeing descriptor sets

Resetting a descriptor pool

Destroying a descriptor pool

Destroying a descriptor set layout

Destroying a sampler

Render Passes and Framebuffers

Introduction

Specifying attachments descriptions

Specifying subpass descriptions

Specifying dependencies between subpasses

Creating a render pass

Creating a framebuffer

Preparing a render pass for geometry rendering and postprocess subpasses

Preparing a render pass and a framebuffer with color and depth attachments

Beginning a render pass

Progressing to the next subpass

Ending a render pass

Destroying a framebuffer

Destroying a render pass

Shaders

Introduction

Converting GLSL shaders to SPIR-V assemblies

Writing vertex shaders

Writing tessellation control shaders

Writing tessellation evaluation shaders

Writing geometry shaders

Writing fragment shaders

Writing compute shaders

Writing a vertex shader that multiplies vertex position by a projection matrix

Using push constants in shaders

Writing texturing vertex and fragment shaders

Displaying polygon normals with a geometry shader

Graphics and Compute Pipelines

Introduction

Creating a shader module

Specifying pipeline shader stages

Specifying a pipeline vertex binding description, attribute description, and input state

Specifying a pipeline input assembly state

Specifying a pipeline tessellation state

Specifying a pipeline viewport and scissor test state

Specifying a pipeline rasterization state

Specifying a pipeline multisample state

Specifying a pipeline depth and stencil state

Specifying a pipeline blend state

Specifying pipeline dynamic states

Creating a pipeline layout

Specifying graphics pipeline creation parameters

Creating a pipeline cache object

Retrieving data from a pipeline cache

Merging multiple pipeline cache objects

Creating a graphics pipeline

Creating a compute pipeline

Binding a pipeline object

Creating a pipeline layout with a combined image sampler, a buffer, and push constant ranges

Creating a graphics pipeline with vertex and fragment shaders, depth test enabled, and with dynamic viewport and scissor tests

Creating multiple graphics pipelines on multiple threads

Destroying a pipeline

Destroying a pipeline cache

Destroying a pipeline layout

Destroying a shader module

Command Recording and Drawing

Introduction

Clearing a color image

Clearing a depth-stencil image

Clearing render pass attachments

Binding vertex buffers

Binding an index buffer

Providing data to shaders through push constants

Setting viewport states dynamically

Setting scissor states dynamically

Setting line width states dynamically

Setting depth bias states dynamically

Setting blend constants states dynamically

Drawing a geometry

Drawing an indexed geometry

Dispatching compute work

Executing a secondary command buffer inside a primary command buffer

Recording a command buffer that draws a geometry with dynamic viewport and scissor states

Recording command buffers on multiple threads

Preparing a single frame of animation

Increasing the performance through increasing the number of separately rendered frames

Helper Recipes

Introduction

Preparing a translation matrix

Preparing a rotation matrix

Preparing a scaling matrix

Preparing a perspective projection matrix

Preparing an orthographic projection matrix

Loading texture data from a file

Loading a 3D model from an OBJ file

Lighting

Introduction

Rendering a geometry with a vertex diffuse lighting

Rendering a geometry with a fragment specular lighting

Rendering a normal mapped geometry

Drawing a reflective and refractive geometry using cubemaps

Adding shadows to the scene

Advanced Rendering Techniques

Introduction

Drawing a skybox

Drawing billboards using geometry shaders

Drawing particles using compute and graphics pipelines

Rendering a tessellated terrain

Rendering a full-screen quad for post-processing

Using input attachments for a color correction post-process effect

Customer Reviews

5 star

4 star

3 star

2 star

1 star

Preparing for loading Vulkan API functions

When we want to use Vulkan API in our application, we need to acquire procedures specified in the Vulkan documentation. In order to do that, we can add a dependency to the Vulkan Loader library, statically link with it in our project, and use function prototypes defined in the vulkan.h header file. The second approach is to disable the function prototypes defined in the vulkan.h header file and load function pointers dynamically in our application.

The first approach is little bit easier, but it uses functions defined directly in the Vulkan Loader library. When we perform operations on a given device, Vulkan Loader needs to redirect function calls to the proper implementation based on the handle of the device we provide as an argument. This redirection takes some time, and thus impacts performance.

The second option requires more work on the application side, but allows us to skip the preceding redirection (jump) and save some performance. It is performed by loading functions directly from the device we want to use. This way, we can also choose only the subset of Vulkan functions if we don't need them all.

In this book, the second approach is presented, as this gives developers more control over the things that are going in their applications. To dynamically load functions from a Vulkan Loader library, it is convenient to wrap the names of all Vulkan API functions into a set of simple macros and divide declarations, definitions and function loading into multiple files.

How to do it...

Define the VK_NO_PROTOTYPES preprocessor definition in the project: do this in the project properties (when using development environments such as Microsoft Visual Studio or Qt Creator), or by using the #define VK_NO_PROTOTYPES preprocessor directive just before the vulkan.h file is included in the source code of our application.
Create a new file, named ListOfVulkanFunctions.inl.
Type the following contents into the file:

      #ifndef EXPORTED_VULKAN_FUNCTION 
      #define EXPORTED_VULKAN_FUNCTION( function ) 
      #endif 

      #undef EXPORTED_VULKAN_FUNCTION 
      // 
      #ifndef GLOBAL_LEVEL_VULKAN_FUNCTION 
      #define GLOBAL_LEVEL_VULKAN_FUNCTION( function ) 
      #endif 

      #undef GLOBAL_LEVEL_VULKAN_FUNCTION 
      // 
      #ifndef INSTANCE_LEVEL_VULKAN_FUNCTION 
      #define INSTANCE_LEVEL_VULKAN_FUNCTION( function ) 
      #endif 

      #undef INSTANCE_LEVEL_VULKAN_FUNCTION 
      // 
      #ifndef INSTANCE_LEVEL_VULKAN_FUNCTION_FROM_EXTENSION 
      #define INSTANCE_LEVEL_VULKAN_FUNCTION_FROM_EXTENSION( function,       extension ) 
      #endif 

      #undef INSTANCE_LEVEL_VULKAN_FUNCTION_FROM_EXTENSION 
      // 
      #ifndef DEVICE_LEVEL_VULKAN_FUNCTION 
      #define DEVICE_LEVEL_VULKAN_FUNCTION( function ) 
      #endif 

      #undef DEVICE_LEVEL_VULKAN_FUNCTION 
      // 
      #ifndef DEVICE_LEVEL_VULKAN_FUNCTION_FROM_EXTENSION 
      #define DEVICE_LEVEL_VULKAN_FUNCTION_FROM_EXTENSION( function,
      extension ) 
      #endif 
       
      #undef DEVICE_LEVEL_VULKAN_FUNCTION_FROM_EXTENSION

Create a new header file, named VulkanFunctions.h.
Insert the following contents into the file:

      #include "vulkan.h" 

      namespace VulkanCookbook { 

      #define EXPORTED_VULKAN_FUNCTION( name ) extern PFN_##name name; 
      #define GLOBAL_LEVEL_VULKAN_FUNCTION( name ) extern PFN_##name 
      name; 
      #define INSTANCE_LEVEL_VULKAN_FUNCTION( name ) extern PFN_##name 
      name; 
      #define INSTANCE_LEVEL_VULKAN_FUNCTION_FROM_EXTENSION( name,
      extension ) extern PFN_##name name; 
      #define DEVICE_LEVEL_VULKAN_FUNCTION( name ) extern PFN_##name 
      name; 
      #define DEVICE_LEVEL_VULKAN_FUNCTION_FROM_EXTENSION( name, 
      extension ) extern PFN_##name name; 

      #include "ListOfVulkanFunctions.inl" 

      } // namespace VulkanCookbook

Create a new file with a source code named VulkanFunctions.cpp.
Insert the following contents into the file:

      #include "VulkanFunctions.h" 

      namespace VulkanCookbook { 

      #define EXPORTED_VULKAN_FUNCTION( name ) PFN_##name name; 
      #define GLOBAL_LEVEL_VULKAN_FUNCTION( name ) PFN_##name name; 
      #define INSTANCE_LEVEL_VULKAN_FUNCTION( name ) PFN_##name name; 
      #define INSTANCE_LEVEL_VULKAN_FUNCTION_FROM_EXTENSION( name, 
      extension ) PFN_##name name; 
      #define DEVICE_LEVEL_VULKAN_FUNCTION( name ) PFN_##name name; 
      #define DEVICE_LEVEL_VULKAN_FUNCTION_FROM_EXTENSION( name, 
      extension ) PFN_##name name; 

      #include "ListOfVulkanFunctions.inl" 

      } // namespace VulkanCookbook

How it works...

The preceding set of files may seem unnecessary, or even overwhelming, at first. VulkanFunctions.h and VulkanFunctions.cpp files are used to declare and define variables in which we will store pointers to Vulkan API functions. Declarations and definitions are done through a convenient macro definition and an inclusion of a ListOfVulkanFunctions.inl file. We will update this file and add the names of many Vulkan functions, from various levels. This way, we don't need to repeat the names of functions multiple times, in multiple places, which helps us avoid making mistakes and typos. We can just write the required names of Vulkan functions only once, in the ListOfVulkanFunctions.inl file, and include it when it's needed.

How do we know the types of variables for storing pointers to Vulkan API functions? It's quite simple. The type of each function's prototype is derived directly from the function's name. When a function is named <name>, its type is PFN_<name>. For example, a function that creates an image is called vkCreateImage(), so the type of this function is PFN_vkCreateImage. That's why macros defined in the presented set of files have just one parameter for function name, from which the type can be easily derived.

Last, but not least, remember that declarations and definitions of variables, in which we will store addresses of the Vulkan functions, should be placed inside a namespace, a class, or a structure. This is because, if they are made global, this could lead to problems on some operating systems. It's better to remember about namespaces and increase the portability of our code.

Place declarations and definitions of variables containing Vulkan API function pointers inside a structure, class, or namespace.

Now that we are prepared, we can start loading Vulkan functions.

Vulkan Cookbook

By : Pawel Lapinski

Vulkan Cookbook

By: Pawel Lapinski

Overview of this book

Related Content you might be interested in

Current Title:

Vulkan Cookbook

The Modern Vulkan Cookbook

C++ Game Development By Example

3D Graphics Rendering Cookbook