Get started with Vulkan

This document explains how to get started with the Vulkan graphics library by downloading, compiling, and running several sample apps.

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

You can confirm your Android version by going to the Settings menu, and selecting About <device> > 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 NDK from within Android Studio or download it manually.

Import

In this section, you download the LunarG Vulkan© repository, generate Android Studio projects for the API samples, and then import these projects into the IDE:

  1. Open a terminal and download the source code to your development directory:

    cd dev-directory
    git clone --recursive https://github.com/LunarG/VulkanSamples.git
    
  2. Follow these instructions (from Building on Android) to generate the sample projects for Android:

    cd VulkanSamples/API-Samples
    cmake -DANDROID=ON -DABI_NAME=abi
    cd android
    python3 compile_shaders.py
    

    Supported ABIs include the following:

    • armeabi-v7a
    • arm64-v8a
    • x86
    • x86_64
  3. Set environmental variables to specify the path to the Android NDK and SDK:

    export ANDROID_SDK_ROOT=/path/to/sdk-directory
    export ANDROID_NDK_HOME=/path/to/ndk-directory
    

    The current targetSdk version for the samples is 26 so you may need to update your tools with the SDK Manager.

  4. Open Android Studio. Choose File > Open and select VulkanSamples/API-Samples/android/build.gradle.

The Project pane resembles the window shown in Figure 1.

Project pane after importing samples into Android Studio

Figure 1. Project pane displaying samples after they've been imported.

Compile

You can compile your project in Android Studio or from the command line.

Android Studio

  1. Select File > Project Structure. Select SDK Location and ensure the SDK and NDK locations are set.
  2. Select your project in the Android Studio Project panel.
  3. From the Build menu, choose Make Module <module-name> ; or select Build APK to generate APK.
  4. Resolve any dependency issues, and then compile. As Figure 2 shows, you can select individual projects to compile by choosing them from the configuration pulldown.
  5. Selecting the drawcube project from the config pulldown

    Figure 2. Selecting an individual project to compile.

Command line

Use the following commands to build the projects from the command line (make sure you are still in directory VulkanSamples/API-Samples/android):

./gradlew build

Execute

To run your project, choose an APK to run by choosing Run > Run <project-name>.

To debug an APK, choose Run > Debug <project-name>. For example, for drawcube, run 15-draw_cube.

Most of the samples have simple functionality to demonstrate how to use one specific API, and most stop automatically after running. The drawcube example is one of the visually interesting examples. When you run it, it should display the image in Figure 3

. Successfully running shows a multicolored cube

Figure 3. The successfully compiled program runs and produces a display.

Use the dynamic loader

The samples use a dynamic loader helper function defined in vulkan_wrapper.h/cpp to retrieve Vulkan API pointers using dlopen() and dlsym(). It does this rather than statically linking them with vulkan.so.

Using this loader allows the code to link against API level 23 and earlier versions of the platform. Those earlier versions don’t include the vulkan.so shared library, but can run on devices that support Vulkan API.

The following snippet shows how to use the dynamic loader.

#include "vulkan_wrapper.h" // Include Vulkan_wrapper and dynamically load symbols.
...
// Before any Vulkan API usage,
InitVulkan();

Additional resources

  • Vulkan specification

    Khronos Group maintains the Vulkan specification. Please refer to the Vulkan homepage for the full specification, training, and tutorials.

  • Shaderc

    Shaderc code in NDK is downstream of the Shaderc repo. If you need the latest Shaderc, refer to Shader compilers.