Khronos Vulkan® Tutorial

Attribution

The Khronos Vulkan® Tutorial is based on the "Vulkan Tutorial" by Alexander Overvoorde licensed under CC BY-SA 4.0.

About

This tutorial will teach you the basics of using the Vulkan graphics and compute API. Vulkan is a new API by the Khronos group (known for OpenGL) that provides a much better abstraction of modern graphics cards. This new interface allows you to better describe what your application intends to do, which can lead to better performance and less surprising driver behavior compared to existing APIs like OpenGL and Direct3D. The ideas behind Vulkan are similar to those of Direct3D 12 and Metal, but Vulkan has the advantage of being fully cross-platform and allows you to develop for Windows, Linux and Android at the same time.

However, the price you pay for these benefits is that you have to work with a significantly more verbose API. Every detail related to the graphics API needs to be set up from scratch by your application, including initial frame buffer creation and memory management for objects like buffers and texture images. The graphics driver will do a lot less hand holding, which means that you will have to do more work in your application to ensure correct behavior.

The takeaway message here is that Vulkan is not for everyone. It is targeted at programmers who are enthusiastic about high performance computer graphics, and are willing to put some work in. If you are more interested in game development, rather than computer graphics, then you may wish to stick to OpenGL or Direct3D, which will not be deprecated in favor of Vulkan anytime soon. Another alternative is to use an engine like Unreal Engine or Unity, which will be able to use Vulkan while exposing a much higher level API to you.

With that out of the way, let’s cover some prerequisites for following this tutorial:

  • A device and driver compatible with Vulkan

    • Most GPU vendors support Vulkan in their consumer drivers or, for mobile, on their devices. For MacOS and iOS, Vulkan support is available through MoltenVK. You can look up Vulkan support in detail at the community driven Vulkan Hardware Database.

  • Experience with C++

    • Familiarity with RAII, initializer lists

  • A compiler with decent support of C++17 features

    • Visual Studio 2017+, GCC 7+, Or Clang 5+

  • Some existing experience with realtime 3D computer graphics

    • E.g. OpenGL or Direct3D

This tutorial will not assume knowledge of OpenGL or Direct3D concepts, but it does require you to know the basics of 3D computer graphics. It will not explain the math behind perspective projection, for example. See this online book for a great introduction of computer graphics concepts. Some other great computer graphics resources are:

You can use C instead of C++ if you want, but you will have to use a different linear algebra library and you will be on your own in terms of code structuring. We will use C++ features like classes and RAII to organize logic and resource lifetimes. There are also two alternative versions of this tutorial available for Rust developers: Vulkano based, Vulkanalia based.

To make it easier to follow along for developers using other programming languages, and to get some experience with the base API we’ll be using the original C API to work with Vulkan. If you are using C++, however, you may prefer using the newer Vulkan-Hpp bindings that abstract some of the dirty work and help prevent certain classes of errors.

License

The contents of this repository are licensed as CC BY-SA 4.0, unless stated otherwise. By contributing to this repository, you agree to license your contributions to the public under that same license.

Tutorial structure

We’ll start with an overview of how Vulkan works and the work we’ll have to do to get the first triangle on the screen. The purpose of all the smaller steps will make more sense after you’ve understood their basic role in the whole picture. Next, we’ll set up the development environment with the Vulkan SDK, the GLM library for linear algebra operations and GLFW for window creation. The tutorial will cover how to set these up on Windows with Visual Studio, and on Ubuntu Linux with GCC.

After that we’ll implement all of the basic components of a Vulkan program that are necessary to render your first triangle. Each chapter will follow roughly the following structure:

  • Introduce a new concept and its purpose

  • Use all of the relevant API calls to integrate it into your program

  • Abstract parts of it into helper functions

Although each chapter is written as a follow-up on the previous one, it is also possible to read the chapters as standalone articles introducing a certain Vulkan feature. That means that the site is also useful as a reference. All of the Vulkan functions and types are linked to the specification, so you can click them to learn more. Vulkan is a very new API, so there may be some shortcomings in the specification itself. You are encouraged to submit feedback to this Khronos repository.

As mentioned before, the Vulkan API has a rather verbose API with many parameters to give you maximum control over the graphics hardware. This causes basic operations like creating a texture to take a lot of steps that have to be repeated every time. Therefore we’ll be creating our own collection of helper functions throughout the tutorial.

Every chapter will also conclude with a link to the full code listing up to that point. You can refer to it if you have any doubts about the structure of the code, or if you’re dealing with a bug and want to compare. All of the code files have been tested on graphics cards from multiple vendors to verify correctness. Each chapter also has a comment section at the end where you can ask any questions that are relevant to the specific subject matter. Please specify your platform, driver version, source code, expected behavior and actual behavior to help us help you.

If you have any type of feedback on the tutorial and site itself, then please don’t hesitate to submit an issue or pull request to the GitHub repository. You can watch the repository to be notified of updates to the tutorial.

After you’ve gone through the ritual of drawing your very first Vulkan powered triangle onscreen, we’ll start expanding the program to include linear transformations, textures and 3D models.

If you’ve played with graphics APIs before, then you’ll know that there can be a lot of steps until the first geometry shows up on the screen. There are many of these initial steps in Vulkan, but you’ll see that each of the individual steps is easy to understand and does not feel redundant. It’s also important to keep in mind that once you have that boring looking triangle, drawing fully textured 3D models does not take that much extra work, and each step beyond that point is much more rewarding.

If you encounter any problems while following the tutorial, then first check the FAQ to see if your problem and its solution is already listed there. If you are still stuck after that, then feel free to ask for help in the comment section of the closest related chapter.

Ready to dive into the future of high performance graphics APIs? Let’s go!