Get started with Vulkan

This document outlines how to get started with the Vulkan graphics library by downloading, compiling, and running Khronos© sample app.

Prerequisites

Before beginning, make sure you have the right hardware and platform version prepared. You should use a device or an emulator that supports Vulkan, running Android 7.0 (Nougat), API level 24 or higher.

You can confirm your Android version by going to the Settings menu, and selecting About phone > Android Version. Once you’ve confirmed that you have the right hardware and platform version set up, you can download the necessary software.

Download

Before getting started, you must download several tools and other software. Note that on a Windows host, it is recommended that you avoid a deep file path hierarchy for tools and source code; this is to work around file path limits on some Windows OS versions.

  1. If you don’t already have Android Studio, download it. This includes the most recent Android SDK.
  2. Install the NDK and CMake from within Android Studio or download and install them separately.
  3. Build and Run the Hello JNI sample to ensure Android Studio is working properly.
  4. Install python3 and other components listed in build.md for your host platform.

Import

In this section, you download the Khronos© Vulkan© sample repository, generate an Android gradle project, then open it with the Android Studio IDE.

  1. Set the following environment variables: 
    export ANDROID_HOME=/path/to/sdk-directory
export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/{your-ndk-version-dir}
  2. Add CMake to the $PATH, which is used to generate Android build scripts: 
    export PATH=$PATH:$ANDROID_HOME/cmake/{your-cmake-version}/bin
  3. Open a terminal and download the source code to your development directory: 
    cd dev-directory
git clone --recursive https://github.com/KhronosGroup/Vulkan-Samples.git
  4. Follow these instructions (from Build.md) to generate the Android sample project: 
    cd Vulkan-Samples
./scripts/generate.py android
  5. Open Android Studio. Choose File > Open and select Vulkan-Samples/build/android_gradle/build.gradle. You should see something similar to the following after Android Studio loads the project:
    Importing sample project to Studio.

    Figure 1. The sample project inside Android Studio.

Compile

All samples in this repo are organized into one Android project. To compile the project, do one of the following:

  • To just compile the sources, use menu, Build > Make Project, or type the Ctrl-F9 shortcut key.
  • To generate the sample APK, select menu Build > Build Bundle(s)/APK(s) > Build APK(s).

You should see the build successful message inside Android Studio's Build window. In case there are errors showing up, fix them and re-compile.

Compiling sample project with Studio.

Figure 2. A successful sample build.

Execute

Before running the sample project, make sure Android Studio recognizes your connected Vulkan device or Android Emulator. You should see something like the following:

Connecting test device to Studio.

Figure 3. Connect the test device to Android Studio.

To run the project, do the following:

  1. Use menu Run > Run vulkan_sample, or click on the run button on the toolbar, and wait for the sample to get installed and started on your connected device.
  2. On your connected Android device, authorize the needed access requests.
    • enable Allow access to manage all files, then tap the arrow Back button to return the sample main start screen.
    • allow the disk access:
      allowing disk access.

      Figure 4. Enable disk access.

  3. You should see the sample main menu screen, similar to the following:
    sample main menu.

    Figure 5. Sample main menu.

  4. Browse through the sample list, and select a few to run. If you are new to Vulkan development, you can start with “API” samples. For example, tapping “Hello Triangle” should display a rendered triangle similar to the following:
    Triangle

    Figure 6. Hello Triange sample.

Your development system is now set up to run samples on your test device.

Vulkan Samples are developed for multiple operating systems, including those for desktop and mobile. Some samples under Performance, Extensions, and Tooling may be unstable and crash on your device. This might be due to various reasons, such as:

  • The specific Vulkan features weren't designed for Android.
  • Your Android OS version is unsupported.
  • The GPU capability of your hardware platform.

Explore

The Java section of the Vulkan sample derives from the NativeActivity class. It passes typical application lifecycle events, such as app creation, start, stop, and destroy to the C/C++ code. In the C/C++ section of the sample, there is a sample framework that implements the run-time sub sample switching functionality. At a very high level, Android system events/messages go through the following path to reach the sample app's Vulkan code:

  • NativeSampleActivity Java section
  • NativeSampleActivity C/C++ section
  • android_native_glue code
  • android_main
  • Sample framework
  • Individual sub sample’s code

android_main is the bridge between NativeSampleActivity and the app code, which can be the starting point for you to follow the sample code. If you just want to focus on the Vulkan specific sources, you can explore the code under Vulkan_Samples\samples, which contains the following:

  • The “api” category samples.
  • The “performance” category samples.
  • The “extensions” category samples.
  • The “tooling” samples.

The Vulkan_Samples\shaders are the home for all shaders.

You can start browsing the “API” category samples to get familiar with basic Vulkan usage and the sample framework. Then you can progress to the “Performance” and “Extenstions” category samples. For shader code, you can use the Project view in Android Studio.

Triangle shader.

Figure 7. Explore shader with Studio.

Additional resources

The Vulkan API has been through a few versions, so it is maturing. The Vulkan standard committee and the Vulkan community have created a rich set of Vulkan material that demonstrates the API's usage and best practices. The following list contains some resources for Vulkan application development:

  • Vulkan Specification. The Khronos Group maintains the Vulkan specification. See the Vulkan homepage for the full specification, training, guides and tutorials.

  • Validation Layers. Validation Layers are essential for application development. See the Vulkan validation layers on Android documentation for details.

  • Shaderc. Shaderc code in the NDK is the downstream of the Shaderc repo. For the usage documentation and instructions to get the latest version, see Shader compilers.