This document contains the instructions for building this repository on Linux and Windows.
This repository contains additional layers and the VkTrace trace/replay tools, supplementing the loader and validation layer core components found at https://github.com/KhronosGroup.
This repository previously contained a sample Intel Vulkan driver that has since been deprecated. The final stable version of that source code is available from this repo by checking out the git tag “Vulkan-ICD-Snapshot”. This source code is no longer supported.
The public repository for the the LunarG VulkanTools is hosted at https://github.com/LunarG.
If you intend to contribute, the preferred work flow is to fork the repo, create a branch in your forked repo, do the work, and create a pull request on GitHub to integrate that work back into the repo.
Ubuntu 14.04.3 LTS, 14.10, 15.04,15.10, and 16.04 LTS have been tested with this repo.
These additional packages are needed for building the components in this repo.
# Dependencies from the LoaderAndValidationLayers repo: sudo apt-get install git cmake build-essential bison libx11-xcb-dev libxkbcommon-dev libmirclient-dev libwayland-dev libxrandr-dev # Additional dependencies for this repo: sudo apt-get install wget autotools-dev libxcb-keysyms1 libxcb-keysyms1-dev # If performing 32-bit builds, you'll also need: sudo apt-get install libc6-dev-i386 g++-multilib
Note that the Vulkan-LoaderAndValidationLayers repo content is included within the VulkanTools repo.
To create your local git repository of VulkanTools:
cd YOUR_DEV_DIRECTORY git clone git@github.com:LunarG/VulkanTools.git cd VulkanTools # This will fetch and build glslang and spriv-tools ./update_external_sources.sh # linux ./update_external_sources.bat --all # windows
This build process builds vktrace and the LVL tests.
Example debug build:
cd YOUR_DEV_DIRECTORY/VulkanTools # cd to the root of the VulkanTools git repository cmake -H. -Bdbuild -DCMAKE_BUILD_TYPE=Debug cd dbuild make
Windows 7+ with additional required software packages:
Optional software packages:
Cygwin is used in order to obtain a local copy of the Git repository, and to run the CMake command that creates Visual Studio files. Visual Studio is used to build the software, and will re-run CMake as appropriate.
To build all Windows targets (e.g. in a “Developer Command Prompt for VS2013” window):
cd VulkanTools # cd to the root of the VulkanTools git repository mkdir build cd build cmake -G "Visual Studio 12 Win64" ..
At this point, you can use Windows Explorer to launch Visual Studio by double-clicking on the “VULKAN.sln” file in the \build folder.
Once Visual Studio comes up, you can select “Debug” or “Release” from a drop-down list.
You can start a build with either the menu (Build->Build Solution), or a keyboard shortcut (Ctrl+Shift+B). As part of the build process, Python scripts will create additional Visual Studio files and projects, along with additional source files.
All of these auto-generated files are under the “build” folder.
Vulkan programs must be able to find and use the Vulkan-1.dll library. Make sure it is either installed in the C:\Windows\System32 folder, or the PATH environment variable includes the folder that it is located in.
If you plan on creating a Windows Install file (done in the windowsRuntimeInstaller sub-directory) you will need to build for both 32-bit and 64-bit Windows since both versions of EXEs and DLLs exist simultaneously on Windows 64.
To do this, simply create and build the release versions of each target:
cd VulkanTools # cd to the root of the Vulkan git repository mkdir build cd build cmake -G "Visual Studio 12 Win64" .. msbuild ALL_BUILD.vcxproj /p:Platform=x64 /p:Configuration=Release mkdir build32 cd build32 cmake -G "Visual Studio 12" .. msbuild ALL_BUILD.vcxproj /p:Platform=x86 /p:Configuration=Release
Install the required tools for Linux and Windows covered above, then add the following.
On Linux:
export PATH=$HOME/Android/sdk/ndk-bundle:$PATH
On Windows:
set PATH=%LOCALAPPDATA%\Android\sdk\ndk-bundle;%PATH%
On OSX:
export PATH=$HOME/Library/Android/sdk/ndk-bundle:$PATH
Tested on OSX version 10.11.4
Setup Homebrew and components
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
export PATH=/usr/local/bin:$PATH
brew install cmake python python3 git
Use the following to ensure the Android build works.
Follow the setup steps for Linux, then from your terminal:
cd build-android ./update_external_sources_android.sh ./android-generate.sh ndk-build -j $(nproc)
Follow the setup steps for OSX above, then from your terminal:
cd build-android ./update_external_sources_android.sh ./android-generate.sh ndk-build -j $(sysctl -n hw.ncpu)
Follow the setup steps for Windows above, then from Developer Command Prompt for VS2013:
cd build-android update_external_sources_android.bat android-generate.bat ndk-build
This documentation is preliminary and needs to be beefed up.
See the vktracereplay.sh file for a working example of how to use vktrace/vkreplay and screenshot layers.
Two additional scripts have been added to facilitate tracing and replaying any APK. Note that these two scripts do not install anything for you, so make sure your target APK, vktrace, vktrace_layer, and vkreplay all use the same ABI.
./create_trace.sh --serial 0123456789 --abi armeabi-v7a --package com.example.CubeWithLayers --activity android.app.NativeActivity adb install --abi armeabi-v7a ./replay_trace.sh --serial 0123456789 --tracefile com.example.CubeWithLayers0.vktrace
An example of using the scripts on Linux and macOS:
./build_vktracereplay.sh ./vktracereplay.sh \ --serial 12345678 \ --abi armeabi-v7a \ --apk ../demos/android/cube-with-layers/bin/NativeActivity-debug.apk \ --package com.example.CubeWithLayers \ --frame 50
And on Windows:
build_vktracereplay.bat ^ vktracereplay.bat ^ --serial 12345678 ^ --abi armeabi-v7a ^ --apk ..\demos\android\cube-with-layers\bin\NativeActivity-debug.apk ^ --package com.example.CubeWithLayers ^ --frame 50
To enable, make the following changes to vk_layer_settings.txt
-lunarg_api_dump.file = FALSE +lunarg_api_dump.file = TRUE -lunarg_api_dump.log_filename = stdout +lunarg_api_dump.log_filename = /sdcard/Android/vk_apidump.txt
Then:
adb push vk_layer_settings.txt /sdcard/Android
And run your application with the following layer enabled:
VK_LAYER_LUNARG_api_dump
To enable, set a property that contains target frame:
adb shell setprop debug.vulkan.screenshot <framenumber>
For production builds, be sure your application has access to read and write to external storage by adding the following to AndroidManifest.xml:
<!-- This allows writing log files to sdcard --> <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
You may also need to grant it access with package manager:
adb shell pm grant com.example.Cube android.permission.READ_EXTERNAL_STORAGE adb shell pm grant com.example.Cube android.permission.WRITE_EXTERNAL_STORAGE
Run your application with the following layer enabled:
VK_LAYER_LUNARG_screenshot
Result screenshot will be in:
/sdcard/Android/<framenumber>.ppm
To record a trace on Android, enable port forwarding from the device to the host:
adb reverse localabstract:vktrace tcp:34201
Start up vktrace on the host in server mode:
vktrace -v full -o cube.vktrace
Run your application with the following layer enabled:
VK_LAYER_LUNARG_vktrace
The trace will be recorded on the host.
To replay a trace, push the trace to your device
adb push cube.vktrace /sdcard/cube.vktrace
Grant vkreplay the ability to read it
adb shell pm grant com.example.vkreplay android.permission.READ_EXTERNAL_STORAGE adb shell pm grant com.example.vkreplay android.permission.WRITE_EXTERNAL_STORAGE
And start the native activity
adb shell am start -a android.intent.action.MAIN -c android-intent.category.LAUNCH -n com.example.vkreplay/android.app.NativeActivity --es args "-v\ full\ -t\ /sdcard/cube.vktrace"