Skip to content

Most visited

Recently visited

navigation

Vulkan Setup

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.

Downloading

Before getting started, you must download several tools and other software.

  1. If you don’t already have Android Studio, download it. This includes the most recent version of Android SDK.
  2. Download the latest version of the NDK. Vulkan requires NDK r12 or later.
  3. (Optional) Build shaderc by navigating to <ndk-root>/sources/third_party/shaderc/, then running the following command.

    On Mac or Linux:

    $ ../../../ndk-build NDK_PROJECT_PATH=. APP_BUILD_SCRIPT=Android.mk \
     APP_STL:=c++_shared APP_ABI=all libshaderc_combined
    

    On Windows:

    ..\..\..\ndk-build NDK_PROJECT_PATH=. APP_BUILD_SCRIPT=Android.mk ^
     APP_STL:=c++_shared APP_ABI=all libshaderc_combined
    
    You can specify APP_STL as gnustl_static, gnustl_shared, c++_static, or c++_shared.
  4. Open a terminal window, and use git to clone the Android Vulkan samples from the repository in which they reside.
    $ git clone https://github.com/googlesamples/vulkan-basic-samples.git
    
  5. Navigate to the LunarGSamples/ directory, which is in the local repository that you checked out in the previous step.
  6. Update the gslang source by running the following command.

    On Mac or Linux:

    $ ./update_external_sources.sh -s -g
    

    On Windows:

    update_external_sources.bat --sync-glslang --sync-spirv-tools
    

Testing Installation

To confirm that Vulkan is set up properly, you can test it with the set of Vulkan API samples provided partly for that purpose. Follow these steps to build and execute these samples:

  1. (Optional) Build the source by entering the following commands:
    $ cd API-samples
    $ cmake -DANDROID=ON -DANDROID_ABI=[armeabi-v7a|arm64-v8a| x86|x86_64|all(default)]
    
  2. Import the samples into Android Studio. To do so, choose File > New > Import Sample, then select NDK > Vulkan API Samples.

    You may see an error about missing components or missing SDK version. Ignore this error message, and follow the installation prompts.

    After several minutes, the Project pane should resemble 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.

Compiling Your Project

To compile your project, follow these steps:

  1. Select your project in the Android Studio Project panel.
  2. From the Build menu, choose Make Module <module-name> ; or select Build APK to generate APK.
  3. 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.
  4. Selecting the

    Figure 2. Selecting an individual project to compile.

Note: Additional tutorial samples illustrate the use of shaders compiled with off-line compilation integrated into Android Studio. For simplicity, each tutorial is self-contained, and builds according to standard Android Studio build procedures.

Running Your Project

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 each project, there’s a Java version and a native (C or C++) version. Run the native version of the app. For example, for drawcube, run drawcube-native.

Most of the samples have simple functionality, and most stop automatically after running. The drawcube example is one of the more 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.

Using 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, which 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();
This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)