Vulkan Best Practice for Mobile Developers

This project has been donated to Khronos Group. Development has now moved to:

• Vulkan-Samples

Please open issues and pull requests there.

Contents

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

Introduction

The Vulkan Best Practice for Mobile Developers is collection of resources to help you develop optimized Vulkan applications for mobile platforms.

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

Disclaimer: This project covers advanced Vulkan concepts. If you are new to Vulkan here are a few links to get you started:

• Beginners Guide to Vulkan
• Get Started in Vulkan

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
• Render Passes
  • Appropriate use of load/store operations, and use of transient attachments
  • Choosing the correct layout when transitioning images
• 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
• AFBC
  • Appropriate use of AFBC
• Misc
  • Driver version
  • Memory limits
  • Vulkan FAQ

Setup

Clone the repo with submodules using the following command:

git clone --recurse-submodules https://github.com/ARM-software/vulkan_best_practice_for_mobile_developers.git
cd vulkan_best_practice_for_mobile_developers

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 Best Practices.

# Run Swapchain Images sample
vulkan_best_practice swapchain_images

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

# Run bonza test offscreen
vulkan_best_practice --test bonza --hide

# Run all the performance samples
vulkan_best_practice --batch performance

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 tiny glTF 2.0 library
  • 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 the following 3D models. Each one has its own licence.

• Sponza: CC BY 3.0 license with the following modifications:
  • All textures are converted to ASTC in .ktx format.
  • Converted to gltf using Blender exporter.
• Bonza: MIT license
• Space Module: MIT license

Sponza model downloaded from Morgan McGuire's Computer Graphics Archive.

Fonts downloaded from Google Fonts, under license Apache 2.0

PBR References:

• Frostbite to PBR course notes
• Learn OpenGL

Trademarks

Vulkan is a registered trademark of the Khronos Group Inc.

Contributions

All contributions are accepted under the same LICENSE.

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