1page.title=Vulkan Setup
2@jd:body
3
4
5<div id="qv-wrapper">
6    <div id="qv">
7      <h2>On this page</h2>
8
9      <ol>
10        <li><a href="#downloading">Downloading</a></li>
11        <li><a href="#testing">Testing Installation</a></li>
12        <li><a href="#compiling">Compiling Your Project</a></li>
13        <li><a href="#running">Running Your Project</a></li>
14        <li><a href="#using">Using the Dynamic Loader</a></li>
15      </ol>
16
17    </div>
18  </div>
19
20<p>
21This document explains how to get started with the Vulkan graphics library by downloading,
22compiling, and running several sample apps.
23</p>
24
25<p>
26Before beginning, make sure you have the right hardware and platform version prepared. You should
27be using one of the following devices, running at least Android N, Developer Preview 2:
28</p>
29
30<ul>
31   <li>Nexus 6P.</li>
32   <li>Nexus 5X.</li>
33   <li>Nexus Player.</li>
34</ul>
35
36<p>
37You can confirm your Android version by going to the <strong>Settings</strong> menu, and
38selecting <strong>About &lt;device&gt;</strong> > <strong>Android Version</strong>.
39Once you’ve confirmed that you have the right hardware and platform version set up, you can
40download the necessary software.
41</p>
42
43<h2 id="downloading">Downloading</h2>
44
45<p>
46Before getting started, you must download several tools and other software.
47</p>
48
49<ol style="1">
50   <li>If you don’t already have Android Studio,
51   <a href="{@docRoot}studio/index.html">download it.</a></li>
52
53<li><a href="https://github.com/android-ndk/ndk/wiki">Download</a> NDK r12-beta.</li>
54
55<li><a href="{@docRoot}preview/setup-sdk.html">Download and install
56the Android N-Preview SDK.</a></li>
57
58<li>(Optional) Build shaderc in NDK r12-beta by navigating to
59{@code &lt;ndk-root&gt;/sources/third_party/shaderc/},
60and running the following command:
61
62<pre class="no-pretty-print">
63../../../ndk-build NDK_PROJECT_PATH=. APP_BUILD_SCRIPT=Android.mk \
64 APP_STL:=c++_shared APP_ABI=all libshaderc_combined
65</pre>
66
67You can specify {@code APP_STL} as {@code gnustl_static},
68{@code gnustl_shared}, {@code c++_static},
69or {@code c++_shared}.</li>
70
71<li>Open a terminal window, and use git to clone the Android Vulkan samples from the
72repository in which they reside.
73
74<pre class="no-pretty-print">
75$ git clone https://github.com/googlesamples/vulkan-basic-samples.git
76</pre>
77</li>
78
79<li>
80Navigate to the {@code LunarGSamples/} directory, which is in the local repository
81that you checked out in the previous step.
82</li>
83
84<li>Update the gslang source by entering the following command:
85
86<pre class="no-pretty-print">
87$ ./update_external_sources.sh -s -g
88</pre>
89</li>
90
91</ol>
92
93
94<h2 id="testing">Testing Installation</h2>
95
96<p>
97To confirm that Vulkan is set up properly, you can test it with
98the set of Vulkan API samples provided partly for that purpose. Follow these steps to
99build and execute these samples:
100</p>
101
102<ol style="1">
103
104
105<li>(Optional) Build the source by entering the following commands:
106
107<pre class="no-pretty-print">
108$ cd API-samples
109$ cmake -DANDROID=ON -DANDROID_ABI=[armeabi-v7a|arm64-v8a| x86|x86_64|all(default)]
110</pre>
111</li>
112
113<li>
114Import the samples into Android Studio. To do so, choose <strong>File</strong> >
115<strong>Import
116project (Eclipse, ADT, Gradle)</strong> and
117select the {@code LunarGSamples/API-Samples/android} directory.
118
119<p>You may see an error about missing components or missing SDK version.
120Ignore this error message, and follow the installation prompts.</p>
121
122<p>After several minutes, the <em>Project</em> pane should
123resemble the window shown in Figure 1.</p>
124
125<img src="../images/project-pane.png"
126alt="Project pane after importing samples into Android Studio" id="figure1" />
127
128<p class="img-caption">
129<strong>Figure 1.</strong> Project pane displaying samples after they've been imported.
130
131</li>
132</ol>
133
134<h2 id="compiling">Compiling Your Project</h2>
135
136<p>To compile your project, follow these steps:</p>
137
138<ol style="1">
139<li>Select your project in the Android Studio <em>Project</em> panel.</li>
140<li>From the <strong>Build</strong> menu, choose <strong>Make Module &lt;module-name&gt; </strong>; or select <strong> Build APK </strong> to generate APK.</li>
141<li>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.</li>
142
143<img src="../images/config-pulldown.png"
144alt="Selecting the "drawcube" project from the config pulldown id="figure2" />
145
146<p class="img-caption">
147<strong>Figure 2.</strong> Selecting an individual project to compile.
148
149</ol>
150
151<p class="note"><strong>Note: </strong>
152<a href="https://github.com/googlesamples/android-vulkan-tutorials">Additional
153tutorial samples</a> illustrate the use of shaders compiled with off-line
154compilation integrated into Android Studio. For simplicity, each tutorial
155is self-contained, and builds according to standard Android Studio
156<a href="{@docRoot}tools/studio/index.html">build procedures.</a>
157</p>
158
159<h2 id="running">Running Your Project</h2>
160
161<p>To run your project, choose an APK to run by choosing <strong>Run</strong> > <strong>Run &lt;project-name&gt;</strong>.</p>
162
163<p>To debug an APK, choose <strong>Run</strong> >
164<strong>Debug &lt;project-name&gt;</strong>.  For each project,
165there’s a Java version and a native (C or C++) version.  Run the
166native version of the app. For example, for drawcube,
167run drawcube-native.</p>
168
169<p>Most of the samples have simple functionality, and most stop
170automatically after running.  The drawcube example is one of
171the more visually interesting examples. When you run it, it
172should display the image in Figure 3</p>.
173
174<img src="../images/drawcube-output.png"
175alt="Successfully running shows a multicolored cube" id="figure3" />
176
177<p class="img-caption">
178<strong>Figure 3.</strong> The successfully compiled program runs and produces a display.
179</p>
180
181<h2 id="using">Using the Dynamic Loader</h2>
182<p>
183The samples use a dynamic loader helper function defined in {@code vulkan_wrapper.h/cpp} to
184retrieve Vulkan API pointers using {@code dlopen()} and {@code dlsym()}. It does this rather
185than statically linking them with {@code vulkan.so}.
186</p>
187
188<p>
189Using this loader allows the code to link against API level 23 and earlier versions of the platform, which don’t include the {@code vulkan.so} shared library, but can run on devices that support Vulkan API.
190</p>
191
192<p>
193The following snippet shows how to use the dynamic loader.
194</p>
195
196<pre>
197#include "vulkan_wrapper.h" // Include Vulkan_wrapper and dynamically load symbols.
198...
199// Before any Vulkan API usage,
200InitVulkan();
201</pre>
202