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.
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.
- If you don’t already have Android Studio, download it. This includes the most recent Android SDK.
- Install NDK from within Android Studio or download it manually.
- Build Shaderc by navigating to
<ndk-root>/sources/third_party/shaderc/, and executing the following command:
On Mac or Linux:
$ ../../../ndk-build NDK_PROJECT_PATH=. APP_BUILD_SCRIPT=Android.mk \ APP_ABI=all APP_PLATFORM=android-24 APP_STL:=c++_static \ -j8 clean libshaderc_combined
..\..\..\ndk-build NDK_PROJECT_PATH=. APP_BUILD_SCRIPT=Android.mk ^ APP_ABI=all APP_PLATFORM=android-24 APP_STL=c++_static ^ -j8 clean libshaderc_combined
Refer to Shader Compilers for more Shaderc documentation.
You could import Vulkan© API samples into Android Studio in one of the following ways:
Automatically with Android Studio. To do so, choose File >
New > Import Sample, then select NDK > Vulkan API Samples.
You may see errors about missing components or missing SDK version. When these messages appear, follow the installation prompts that Android Studio shows you. These steps should fix the errors automatically.
After several minutes, the Project pane should resemble the window shown in Figure 1.
Manually with a terminal:
- Download the source code:
git clone https://github.com/googlesamples/vulkan-basic-samples.git
- Open samples with Android Studio. To do so, choose File > Open, navigate to the cloned source directory, and click OK.
- Download the source code:
To compile your project, follow these steps:
- Select your project in the Android Studio Project panel.
- From the Build menu, choose Make Module <module-name> ; or select Build APK to generate APK.
- 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.
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.
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.
Using the Dynamic Loader
The samples use a dynamic loader helper function defined in
retrieve Vulkan API pointers using
dlsym(). It does this rather
than statically linking them with
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();
- Source Code the upstream repo, follow the build instructions there to generate the latest version.