Docs: Getting Started guide for Vulkan on Android am: a357c3f

am: 0603232

* commit '0603232e6ee73d7907ffb2f8e4911d7d9a5d1068':
  Docs: Getting Started guide for Vulkan on Android

Change-Id: I4c717fc24f3265fca1838c0bbde88e3e88d58acd

docs/html/ndk/guides/graphics/getting-started.jd

@@ -0,0 +1,200 @@
+page.title=Vulkan Setup
+@jd:body
+
+
+<div id="qv-wrapper">
+    <div id="qv">
+      <h2>On this page</h2>
+
+      <ol>
+        <li><a href="#downloading">Downloading</a></li>
+        <li><a href="#testing">Testing Installation</a></li>
+        <li><a href="#compiling">Compiling Your Project</a></li>
+        <li><a href="#running">Running Your Project</a></li>
+        <li><a href="#using">Using the Dynamic Loader</a></li>
+      </ol>
+
+    </div>
+  </div>
+
+<p>
+This document explains how to get started with the Vulkan graphics library by downloading,
+compiling, and running several sample apps.
+</p>
+
+<p>
+Before beginning, make sure you have the right hardware and platform version prepared. You should
+be using one of the following devices, running at least Android N, Developer Preview 2:
+</p>
+
+<ul>
+   <li>Nexus 6P.</li>
+   <li>Nexus 5X.</li>
+</ul>
+
+<p>
+You can confirm your Android version by going to the <strong>Settings</strong> menu, and
+selecting <strong>About &lt;device&gt;</strong> > <strong>Android Version</strong>.
+Once you’ve confirmed that you have the right hardware and platform version set up, you can
+download the necessary software.
+</p>
+
+<h2 id="downloading">Downloading</h2>
+
+<p>
+Before getting started, you must download several tools and other software.
+</p>
+
+<ol style="1">
+   <li>If you don’t already have Android Studio,
+   <a href="{@docRoot}sdk/index.html">download it.</a></li>
+
+<li><a href="https://github.com/android-ndk/ndk/wiki">Download</a> NDK r12-beta.</li>
+
+<li><a href="{@docRoot}preview/setup-sdk.html">Download and install
+the Android N-Preview SDK.</a></li>
+
+<li>(Optional) Build shaderc in NDK r12-beta by navigating to
+{@code &lt;ndk-root&gt;/sources/third_party/shaderc/},
+and running the following command:
+
+<pre class="no-pretty-print">
+../../../ndk-build NDK_PROJECT_PATH=. APP_BUILD_SCRIPT=Android.mk \
+ APP_STL:=c++_shared APP_ABI=all libshaderc_combined
+</pre>
+
+You can specify {@code APP_STL} as {@code gnustl_static},
+{@code gnustl_shared}, {@code c++_static},
+or {@code c++_shared}.</li>
+
+<li>Open a terminal window, and use git to clone the Android Vulkan samples from the
+repository in which they reside.
+
+<pre class="no-pretty-print">
+$ git clone https://github.com/googlesamples/vulkan-basic-samples.git
+</pre>
+</li>
+
+<li>
+Navigate to the {@code LunarGSamples/} directory, which is in the local repository
+that you checked out in the previous step.
+</li>
+
+<li>Update the gslang source by entering the following command:
+
+<pre class="no-pretty-print">
+$ ./update_external_sources.sh -s -g
+</pre>
+</li>
+
+</ol>
+
+
+<h2 id="testing">Testing Installation</h2>
+
+<p>
+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:
+</p>
+
+<ol style="1">
+
+
+<li>(Optional) Build the source by entering the following commands:
+
+<pre class="no-pretty-print">
+$ cd API-samples
+$ cmake -DANDROID=ON -DANDROID_ABI=[armeabi-v7a|arm64-v8a| x86|x86_64|all(default)]
+</pre>
+</li>
+
+<li>
+Import the samples into Android Studio. To do so, choose <strong>File</strong> >
+<strong>Import
+project (Eclipse, ADT, Gradle)</strong> and
+select the {@code LunarGSamples/API-Samples/android} directory.
+
+<p>You may see an error about missing components or missing SDK version.
+Ignore this error message, and follow the installation prompts.</p>
+
+<p>After several minutes, the <em>Project</em> pane should
+resemble the window shown in Figure 1.</p>
+
+<img src="../images/project-pane.png"
+alt="Project pane after importing samples into Android Studio" id="figure1" />
+
+<p class="img-caption">
+<strong>Figure 1.</strong> Project pane displaying samples after they've been imported.
+
+</li>
+</ol>
+
+<h2 id="compiling">Compiling Your Project</h2>
+
+<p>To compile your project, follow these steps:</p>
+
+<ol style="1">
+<li>Select your project in the Android Studio <em>Project</em> panel.</li>
+<li>From the <strong>Build</strong> menu, choose <strong>Make Module &lt;module-name&gt; </strong>.</li>
+<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>
+
+<img src="../images/config-pulldown.png"
+alt="Selecting the "drawcube" project from the config pulldown id="figure2" />
+
+<p class="img-caption">
+<strong>Figure 2.</strong> Selecting an individual project to compile.
+
+</ol>
+
+<p class="note"><strong>Note: </strong>
+<a href="https://github.com/googlesamples/android-vulkan-tutorials">Additional
+tutorial samples</a> 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
+<a href="{@docRoot}tools/studio/index.html">build procedures.</a>
+</p>
+
+<h2 id="running">Running Your Project</h2>
+
+<p>To run your project, choose an APK to run by choosing <strong>Run</strong> > <strong>Run &lt;project-name&gt;</strong>.</p>
+
+<p>To debug an APK, choose <strong>Run</strong> >
+<strong>Debug &lt;project-name&gt;</strong>.  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.</p>
+
+<p>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</p>.
+
+<img src="../images/drawcube-output.png"
+alt="Successfully running shows a multicolored cube" id="figure3" />
+
+<p class="img-caption">
+<strong>Figure 3.</strong> The successfully compiled program runs and produces a display.
+</p>
+
+<h2 id="using">Using the Dynamic Loader</h2>
+<p>
+The samples use a dynamic loader helper function defined in {@code vulkan_wrapper.h/cpp} to
+retrieve Vulkan API pointers using {@code dlopen()} and {@code dlsym()}. It does this rather
+than statically linking them with {@code vulkan.so}.
+</p>
+
+<p>
+Using 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.
+</p>
+
+<p>
+The following snippet shows how to use the dynamic loader.
+</p>
+
+<pre>
+#include "vulkan_wrapper.h" // Include Vulkan_wrapper and dynamically load symbols.
+...
+// Before any Vulkan API usage,
+InitVulkan();
+</pre>