Vulkan-Samples: one binary, six sample families, and a benchmark mode

Donated by Arm, extended by the people you would expect

The provenance line in the README is specific: the project was donated to Khronos by Arm Limited, with further contributions by Sascha Willems and Adam Sawicki. That matters more than it usually does, because it explains the shape of the collection. Arm is a mobile GPU vendor, so the tile based rendering material and the Mali GPU documentation link at the end are not an afterthought; they reflect where the original work came from.

Sascha Willems is the author of the sample applications that most Vulkan tutorials on the internet link to, and Adam Sawicki is the author of one of the long-standing Vulkan benchmarking tools. Having both contributing is a reasonable explanation for why this repository reads as a reference rather than a tutorial.

The repository is Apache-2.0, written in C++, and carries 5,381 stars with 836 forks, which makes it the most starred of the Vulkan repositories in this set. It was last pushed on 2026-09-21. It has no tagged releases in the repository history, so tracking a specific sample version means pinning a commit rather than a version number.

The stated goals are two sentences long: create a collection of resources demonstrating best-practice recommendations in Vulkan, and create tutorials explaining the implementation of those best practices including performance analysis guides. Both goals point at the same thing, which is that the advice and the measurement ship together.

One binary with a subcommand per sample

The application is a single executable called `vulkan_samples` rather than a directory of separate programs, which changes how you explore the collection. Everything runs through a `sample` subcommand, and the help system works at two levels:

# For the entire usage use
vulkan_samples --help

# For subcommand usage use
vulkan_samples <sub_command> --help

# Run Swapchain Images sample
vulkan_samples sample swapchain_images

The subcommand name matches the sample directory name, so browsing `samples/` gives you the exact string to type. That is a small design decision that removes a real source of friction.

Two more modes matter more than the individual samples. Benchmark mode runs a sample for a fixed number of frames instead of opening a window and waiting for you to close it:

# Run AFBC sample in benchmark mode for 5000 frames
vulkan_samples sample afbc --benchmark --stop-after-frame 5000

And batch mode runs a whole category, which is the right way to compare your hardware against the published figures:

# Run all the performance samples for 10 seconds in each configuration
vulkan_samples batch --category performance --duration 10

There is one operational warning worth reading carefully: you must run from the root directory of the repository, because otherwise the samples cannot find the assets. The path to the binary depends on build type and architecture and lands under `build/app/bin/`, so a relative path from the wrong working directory is the first thing to check when a sample starts and immediately exits.

Running without a GPU through headless surface

The headless mode is the feature that makes this collection usable in CI, and it is worth understanding what it does rather than just copying the flag.

# Run compute nbody using headless-surface and take a screenshot of frame 5 
# Note: headless-surface uses VK_EXT_headless_surface.
# This will create a surface and a Swapchain, but present will be a no op.
# The extension is supported by Swiftshader(https://github.com/google/swiftshader).
# It allows to quickly test content in environments without a GPU.
vulkan_samples sample compute_nbody --headless-surface --screenshot 5

So a surface and a swapchain are still created, the full rendering path still executes, and only the present operation becomes a no-op. That is meaningfully different from not rendering at all, because the swapchain and image acquisition code paths still run. The README credits Swiftshader as an implementation supporting the extension, which gives you a CPU rasteriser option for machines with no Vulkan driver at all.

Combined with the screenshot flag, this makes the samples usable as a smoke test: run compute_nbody headless, screenshot frame 5, and you have something a build system can compare. The Android path is supported too, launching a named activity on a connected device rather than running the binary locally.

Six families of samples, ordered by how much they assume

The `samples/` directory splits into `api/`, `complex/`, `extensions/`, `general/`, `performance/` and `tooling/`, and the split is the clearest way to decide where to begin.

`api/` is the entry point for newcomers, which the README says outright. These are small, single-concept programs that show one Vulkan mechanism doing one thing, and reading them in order is a reasonable approximation of learning the API. If you have never written Vulkan code, start here.

`extensions/` is the same idea applied to one extension at a time, which is the format to reach for when you know you need `VK_KHR_` something and want the smallest working example.

`performance/` is where this repository justifies itself. The README describes these as showing the recommended best practice together with real-time profiling information, more advanced, and containing a detailed tutorial with more in-depth explanations. A sample that shows a performance figure next to the code pattern is the artifact most tutorials cannot provide, because producing those figures requires instrumented hardware runs.

`complex/` and `general/` cover larger and more situational cases, and `tooling/` covers the surrounding tooling. There is also a `vulkan_basics.adoc` document asking how Vulkan compares to OpenGL ES and what to expect when targeting Vulkan, which is the right pre-reading before the API samples if your background is OpenGL.

Requirements across the collection: a compiler supporting at least C++20, and a device supporting Vulkan 1.1 or newer. Some samples need a higher Vulkan version or specific extensions.

Cloning is where people give up first

The repository is large and the README spends a long NOTE block on why, which is unusual and useful. It requires git and git large file storage, and the clone command uses submodules:

git clone --recurse-submodules https://github.com/KhronosGroup/Vulkan-Samples.git
cd Vulkan-Samples

The warning is that some ISPs have trouble providing a reliable connection to GitHub while the clone is in progress, and the symptoms to look for are submodule downloads at rates in the tens of kB/s or fatal timeout errors. The README is careful to say these are likely network routing issues inside an ISP's network rather than anything wrong locally, and acknowledges that getting an ISP to acknowledge such a problem is hard.

Two workarounds are offered. One is to switch the repository to the ssh protocol before the submodule download:

git clone [email protected]:KhronosGroup/Vulkan-Samples.git
cd Vulkan-Samples
perl -i -p -e 's|https://(.*?)/|git@\1:|g' .gitmodules
git submodule sync
git submodule update

The README notes this requires GitHub ssh key authentication, and says plainly that it cannot be made the repository default, which is an honest framing of why a workaround stays a workaround. The second option is running GitHub through a VPN.

Build guides are per platform for Windows, Linux, Android, macOS and iOS. The tree also shows a `bldsys/` directory for build systems, a `framework/` shared layer, a `components/` directory, `shaders/`, and a `third_party/` set with its own licences.

Documentation lives on the site, not on GitHub

The README points documentation to docs.vulkan.org/samples/latest/README.html and explains why: the documentation is written in AsciiDoc, which GitHub does not fully support. So the AsciiDoc files in the repository render poorly for anyone browsing it, and the rendered version is the one to read.

That single fact changes how you should treat the repository as a learning resource. If you plan to learn from these samples, work on the documentation site and treat the clone as something you build rather than something you read.

The sample documentation is linked from three places: the Vulkan Guide, which is the problem-oriented index, and Get Started in Vulkan, which is the tutorial. All three are separate Khronos projects and this README cross-links rather than duplicates them. That division of labour is a strength. The Guide explains why Vulkan is shaped as it is, the tutorial walks a first program, and this repository supplies the code.

There is also general information linked under Vulkan Essentials, including a controls reference, a debug window description, and a script for creating a sample, which tells you the collection expects to grow. A memory limits document and a driver version page sit alongside.

Assets come from a separate Vulkan-Samples-Assets repository under their own licences, and the `assets` entry in the tree is the large file storage content. If your clone is slow, that directory is the reason.

Editorial conclusion

Vulkan-Samples earns its reputation for a specific reason: it ships a profiler next to the advice. The performance samples show the recommended pattern and the real time it takes, which is the thing tutorials usually leave out. Requirements are a C++20 compiler and a Vulkan 1.1 device, individual samples may ask for more. Start with the API samples from the repository root, since running from anywhere else loses the assets, and use `vulkan_samples --help` rather than guessing subcommand names.

Frequently asked questions

Official sources

1. Issues
2. KhronosGroup/Vulkan-Samples on GitHub
3. License: Apache-2.0
4. README