Vulkan Samples

Contents

• Introduction
  • Goals
• Tutorials
• Samples
• Setup
• Build
  • Supported Platforms
• Usage
• Testing
• License
  • Trademarks
• Contributions
• Related resources

Introduction

The Vulkan Samples is collection of resources to help you develop optimized Vulkan applications.

If you are new to Vulkan the API samples are the right place to start. Additionally you may find the following links useful:

• Vulkan Guide
• Get Started in Vulkan

Performance samples show the recommended best practice together with real-time profiling information. They are more advanced but also contain a detailed tutorial with more in-detail explanations.

Goals

• Create a collection of resources that demonstrate best-practice recommendations in Vulkan
• Create tutorials that explain the implementation of best-practices and include performance analysis guides
• Create a framework that can be used as reference material and also as a sandbox for advanced experimentation with Vulkan

Samples

• Listing of all samples available in this repository

Tutorials

• Project Basics
  • Controls
  • Debug window
  • Create a Sample
• Vulkan Essentials
  • How does Vulkan compare to OpenGL ES? What should you expect when targeting Vulkan?
• Vulkan Swapchains
  • Appropriate use of N-buffering
  • Appropriate use of surface rotation
• Pipelines
  • Use of pipeline caches to avoid startup latency
  • Utilizing Specialization Constants
• Descriptors
  • Descriptor and buffer management
• Constant Data
  • Sending constant data to the shaders
• Render Passes
  • Appropriate use of load/store operations, and use of transient attachments
  • Choosing the correct layout when transitioning images
  • How to implement MSAA
• Render Subpasses
  • Benefits of subpasses over multiple render passes, use of transient attachments, and G-buffer recommended size
• Workload Synchronization
  • Using pipeline barriers efficiently
  • How to synchronize back to the CPU and avoid stalling
• Command Buffers
  • Allocation and management of command buffers
  • Multi-threaded recording with secondary command buffers
  • Multi-threaded recording with multiple render passes
• AFBC
  • Appropriate use of AFBC
• Textures
  • Run-time mip map generation
• Debugging
  • Using the debug utilities extension
• Misc
  • Driver version
  • Memory limits

Setup

Clone the repo with submodules using the following command:

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

Follow build instructions for your platform below.

Build

Supported Platforms

• Windows - Build Guide
• Linux - Build Guide
• macOS - Build Guide
• Android - Build Guide

Usage

The following shows some example command line usage on how to configure and run the Vulkan Samples.

# Run Swapchain Images sample
vulkan_samples swapchain_images

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

# Run bonza test offscreen
vulkan_samples --test bonza --hide

# Run all the performance samples
vulkan_samples --batch performance

# Run Swapchain Images sample on an Android device
adb shell am start-activity -n com.khronos.vulkan_samples/com.khronos.vulkan_samples.SampleLauncherActivity -e sample swapchain_images

Tests

• System Test - Usage Guide
• Generate Sample - Usage Guide

License

See LICENSE.

This project has some third-party dependencies, each of which may have independent licensing:

• astc-encoder: ASTC Evaluation Codec
• CTPL: Thread Pool Library
• docopt: A C++11 port of the Python argument parsing library
• glfw: A multi-platform library for OpenGL, OpenGL ES, Vulkan, window and input
• glm: OpenGL Mathematics
• glslang: Shader front end and validator
• dear imgui: Immediate Mode Graphical User Interface
  • dear imgui shaders: GLSL shaders for dear imgui
• HWCPipe: Interface to mobile Hardware Counters
• KTX-Software: Khronos Texture Library and Tools
• spdlog: Fast C++ logging library
• SPIRV-Cross: Parses and converts SPIR-V to other shader languages
• stb: Single-file public domain (or MIT licensed) libraries
• tinygltf: Header only C++11 glTF 2.0 file parser
• nlohmann json: C++ JSON Library (included by tinygltf)
• vma: Vulkan Memory Allocator
• volk: Meta loader for Vulkan API
• vulkan: Sources for the formal documentation of the Vulkan API

This project uses assets from vulkan-samples-assets. Each one has its own license.

Trademarks

Vulkan is a registered trademark of the Khronos Group Inc.

Contributions

Donated to Khronos by Arm, with further contributions by Sascha Willems and Adam Sawicki. See CONTRIBUTORS for the full contributor list.

Also see CONTRIBUTING for contribution guidelines.

Related resources

• Mali GPU Best Practices: A document with recommendations for efficient API usage
• PerfDoc: A Vulkan layer which aims to validate applications against Mali GPU Best Practices