This document explains how to get started with the Vulkan graphics library by downloading,compiling, and running several sample apps.
May 03, 2016 Import Android Code Sample: Choose Import an Android code sample, then search for and select Vulkan API samples. Android Studio downloads the sample code directly from Github. Import Project: Use this method only if you've already cloned this project from GitHub into a local repo. From Android Studio. Jun 30, 2016 OpenGL has always been the standard graphics API used in Android, but now that the Khronos Group announed Vulkan, that may change. Google gives you everything you need to incorporate Vulkan into your Android games and other apps where graphics performance is key. Visit the Android developer website to download the API, samples, and documentation: resources to help you hit the ground running. Develop for Android.
Before beginning, make sure you have the right hardware and platform version prepared. You shoulduse a device that supports Vulkan, running Android API level 24 or higher.
You can confirm your Android version by going to the Settings menu, andselecting About <device> >Android Version.Once you’ve confirmed that you have the right hardware and platform version set up, you candownload the necessary software.
Downloading
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:
On Windows:
Refer to Shader Compilers for more Shaderc documentation.
Importing
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 shouldresemble the window shown in Figure 1.
Figure 1. Project pane displaying samples after they've been imported.
- Manually with a terminal:
- Download the source code:
- Open samples with Android Studio. To do so, choose File > Open, navigate to the cloned source directory, and click OK.
Compiling
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.
Figure 2. Selecting an individual project to compile.
Executing
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 stopautomatically after running. The drawcube example is one ofthe visually interesting examples. When you run it, itshould display the image in Figure 3
.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 toretrieve Vulkan API pointers using dlopen() and dlsym(). It does this ratherthan 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 versionsdon’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.
Additional resources
- Source Code
Sources used in this doc are from Vulkan API Samples, refer to README.md for more descriptions.
Vulkan API Samples repo is a snapshot from the upstream repo, follow the build instructions there to generate the latest version. - Shaderc
Shaderc code in NDK is downstream of the Shaderc repo. If you need the latest Shaderc, refer to Shader Compilers.
how to enable ncnn vulkan capablity
follow the build and install instruction
make sure you have installed vulkan sdk from lunarg vulkan sdk website
Usually, you can enable the vulkan compute inference feature by adding only three lines of code to your application.
does my graphics device support vulkan
Some platforms have been tested and known working. In theory, if your platform support vulkan api, either 1.0 or 1.1, it shall work.
- Y = known work
- ? = shall work, not confirmed
- / = not applied
| windows | linux | android | mac | ios | |
|---|---|---|---|---|---|
| intel | Y | Y | ? | ? | / |
| amd | Y | Y | / | ? | / |
| nvidia | Y | Y | ? | / | / |
| qcom | / | / | Y | / | / |
| apple | / | / | / | ? | Y |
| arm | / | ? | Y | / | / |
You can search the vulkan database to see if your device supports vulkan.
Some old buggy drivers may produce wrong result, that are blacklisted in ncnn and treated as non-vulkan capable device.You could check if your device and driver have this issue with my conformance test here.Most of these systems are android with version lower than 8.1.
why using vulkan over cuda/opencl/metal
In the beginning, I had no GPGPU programming experience, and I had to learn one.
vulkan is considered more portable and well supported by venders and the cross-platform low-overhead graphics api. As a contrast, cuda is only available on nvidia device, metal is only available on macos and ios, while loading opencl library is banned in android 7.0+ and does not work on ios.
I got errors like 'vkCreateComputePipelines failed -1000012000' or random stalls or crashes
Upgrade your vulkan driver.
how to use ncnn vulkan on android
minimum android ndk version: android-ndk-r18b
minimum sdk platform api version: android-24
link your jni project with libvulkan.so
The squeezencnn example have equipped gpu inference, you could take it as reference.
How To Download Vulkan Api For Android Windows 10
how to use ncnn vulkan on ios
Vulkan Api Games List
setup vulkan sdk (https://vulkan.lunarg.com/sdk/home#mac)
metal only works on real device with arm64 cpu (iPhone 5s and later)
link your project with MoltenVK framework and Metal
what about the layers without vulkan support
These layers have vulkan support currently
AbsVal, BatchNorm, BinaryOp, Cast, Clip, Concat, Convolution, ConvolutionDepthWise, Crop, Deconvolution, DeconvolutionDepthWise, Dropout, Eltwise, Flatten, HardSigmoid, InnerProduct, Interp, LRN, Packing, Padding, Permute, Pooling(pad SAME not supported), PReLU, PriorBox, ReLU, Reorg, Reshape, Scale, ShuffleChannel, Sigmoid, Softmax, TanH, UnaryOp
For these layers without vulkan support, ncnn inference engine will automatically fallback to cpu path.
Thus, it is usually not a serious issue if your network only has some special head layers like SSD or YOLO. All examples in ncnn are known working properly with vulkan enabled.
my model runs slower on gpu than cpu
The current vulkan inference implementation is far from the preferred state. Many handful optimization techniques are planned, such as winograd convolution, operator fusion, fp16 storage and arithmetic etc.
It is common that your model runs slower on gpu than cpu on arm devices like mobile phones, since we have quite good arm optimization in ncnn ;)