Merge "Update validation-layer.jd for NDK-R12: use packed layer binaries punt building layers to Khronos github repo" into nyc-dev
diff --git a/docs/html/ndk/guides/graphics/getting-started.jd b/docs/html/ndk/guides/graphics/getting-started.jd
index 145e534..0c2d939 100644
--- a/docs/html/ndk/guides/graphics/getting-started.jd
+++ b/docs/html/ndk/guides/graphics/getting-started.jd
@@ -137,7 +137,7 @@
<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 <module-name> </strong>.</li>
+<li>From the <strong>Build</strong> menu, choose <strong>Make Module <module-name> </strong>; or select <strong> Build APK </strong> to generate APK.</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"
diff --git a/docs/html/ndk/guides/graphics/validation-layer.jd b/docs/html/ndk/guides/graphics/validation-layer.jd
index beac1c0..1a7d832 100644
--- a/docs/html/ndk/guides/graphics/validation-layer.jd
+++ b/docs/html/ndk/guides/graphics/validation-layer.jd
@@ -6,19 +6,8 @@
<h2>On this page</h2>
<ol>
+ <li><a href="#ilp">Add Validation Layers to Project</a></li>
<li><a href="#gls">Getting Layer Source</a></li>
- <li><a href="#ias">Android Studio Integration</a>
- <ol>
- <li><a href="#asbl">Building Layers</a></li>
- <li><a href="#asil">Installing Layers</a></li>
- </ol>
- </li>
- <li><a href="#cli">Integrating on the Command Line</a>
- <ol>
- <li><a href="#clibl">Building Layers</a></li>
- <li><a href="#cliil">Installing Layers</a></li>
- </ol>
- </li>
<li><a href="#verifying">Verifying Layer Build</a></li>
<li><a href="#enabling">Enabling Layers</a></li>
<li><a href="#debug">Enabling the Debug Callback</a></li>
@@ -52,272 +41,94 @@
<p>
This page explains how to:
<ul>
+ <li>Integrate NDK's Layer Binaries.</li>
<li>Get source code for validation layers.</li>
- <li>Build the layers.</li>
- <li>Incorporate the layers into your app.</li>
+ <li>Verifying Layer Build.</li>
+ <li>Enabling Layers in Vulkan Application.</li>
+
</ul>
</p>
+<h2 id="ilp">Add Validation Layers to Project</h2>
+
+<p>
+ NDK release 12 and higher includes pre-built validation layer binaries. At
+ instance and device creation time, when requested by your application, the
+ Vulkan loader finds them in the APK installed location and loads them.
+</p>
+
+<p>
+ To use the pre-built validation layer binaries, either modify the gradle build
+ configuration of your project or manually add the binaries into the JNI
+ libraries directory of your project.
+</p>
+
+
+<h3 id="vl-gradle">Adding validation layers with Gradle</h3>
+
+<p>
+ You can add the validation layer your project using either Andorid Studio's
+ support for CMake and Ndk-build, or using Studio's experimental plugin for
+ Gradle. In general, you should use the CMake and Ndk-build configuration.
+</p>
+
+
+<p>
+ To add the libraries using Android Studio's support for CMake/Ndk-build,
+ add the following to your project's gradle configuration:
+</p>
+
+<pre class="no-pretty-print">
+sourceSets {
+ main {
+ jniLibs {
+ srcDir "${your-ndk-dir}/sources/third_party/vulkan/src/build-android/jniLibs"
+ }
+ }
+}</pre>
+
+<p>
+ To add the libraries using Android Studio's experimental plugin for Gradle,
+ add the following to your project's gradle configuration:
+</p>
+
+<pre class="no-pretty-print">
+sources {
+ main {
+ jniLibs {
+ source.srcDir "${your-ndk-dir}/sources/third_party/vulkan/src/build-android/jniLibs"
+ }
+ }
+}</pre>
+
+
+<h3 id="vl-jni-lib">Adding validation layers to JNI libraries</h3>
+
+<p>
+ If configuring your project's gradle build file is not working, you can
+ manually add the validation layer binaries to your project's JNI libraries
+ directory by using the following command line options:
+</p>
+
+<pre class="no-pretty-print">
+$ cd ${your-app-project-root}
+$ mkdir -p app/src/main
+$ cp -fr ${your-ndk-dir}/sources/third_party/vulkan/src/build-android/jniLibs app/src/main/
+</pre>
+
+
<h2 id="gls">Getting Layer Source</h2>
<p>
-This section explains how to build layers from source.
-If you have precompiled layers, you can skip this section, and instead read about how to
-install your layers using <a href="#asil">Android Studio</a> or from the <a href="cliil">
-command line</a>.
-</p>
-<h3 id="ftn">From the NDK (Recommended)</h3>
-
-<p>
-<a href="{@docRoot}ndk/downloads/index.html">NDK Revision 12</a> and later contains source
-code for Android validation layers that is known-good, and ready to build. This code resides under
-the {@code <ndk-root>/sources/third_party/vulkan/src/build-android/generated/gradle-build}
-directory. This version of the layers should be sufficient for most needs. If so, your next task is
-to <a href="#building">build them</a>. Alternatively, you can pull source code from the
-Khronos Group repository.
-</pre>
-</p>
-
-<h3 id="ftr">From the repository</h3>
-
-<p>
-Although we recommend that you use the source code provided with the NDK, you can also pull more
-recent versions of the source code directly from the
+If your app needs the latest validation layer, you can pull the latest source from the Khronos Group
<a class="external-link" href="https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers">
-GitHub repository</a> belonging to the Khronos Group. To do so, perform the following steps.
+GitHub repository</a> and follow the build instructions there.
</p>
-<ol style="1">
-<li>
-Clone the Vulkan directory by entering the following command in your terminal window:
-
-<pre class="no-pretty-print">
-$ git clone git@github.com:KhronosGroup/Vulkan-LoaderAndValidationLayers.git
-</pre>
-
-<p class="note"><strong>Note: </strong>You must have a private SSH key associated with
-GitHub, or this command fails with a {@code Permission denied (publickey)} message.</p>
-</li>
-
-<li>
-Navigate to the directory containing the layer source code, and
-check out the repo's stable Android branch, called {@code android_layers}:
-
-<pre class="no-pretty-print">
-$ cd Vulkan-LoaderAndValidationLayers
-$ git checkout android_layers
-</pre>
-</li>
-
-<li>
-Begin preparation for building by entering the following commands on the command line:
-<ul>
- <li>For Linux or OS X:
- <ul>
- <li>
- <pre class="no-pretty-print">
-$ cd build-android
-$ ./android-generate</pre>
- </li>
- </ul>
- </li>
-
- <li>For Windows:
- <ul>
- <li>
-<pre class="no-pretty-print">
-> cd build-android
-> android-generate.bat</pre>
- </li>
- </ul>
- </li>
-</ul>
-</li>
-
-<li>
-Continue by following the build instructions for your platform.
-These instructions are in the {@code BUILD.md} file contained in the local instance of the
-repository you cloned.
-</li>
-</ul>
-
-</ol>
-
-<h3 id="ias">Android Studio Integration</h3>
-<p>
-Android Studio builds the validation layers when it builds the rest of the app.
-This flow makes it easier for you to trace through the layers at runtime. Each layer's
-source code corresponds to a single Gradle project, which you can specify directly in your Android
-Studio app. For example, there is a {@code build.gradle} project for threading, and another
-one for parameter validation.
-</p>
-
-<h4 id="asbl">Building layers</h4>
-
-<p>
-To integrate layers directory into Android Studio application, perform these steps:
-</p>
-<li>
-Add layers to your Android Studio application's project by specifying their corresponding
-Gradle projects in {@code settings.gradle}, which is normally a peer to app directory.
-The following example shows how to do this, based on the assumption that you're
-<a href="#ftn">using the {@code build.gradle} files from the NDK</a>.
-
-<pre>
-// configure your path to the source code generated on your machine
-def layerProjRoot = file('/path/to/ndk-root/.../build-android/generated/gradle-build')
-String[] layers = ['threading',
- 'parameter_validation',
- 'object_tracker',
- 'core_validation',
- 'device_limits',
- 'image',
- 'swapchain',
- 'unique_objects']
-for (layer in layers) {
- include ":"+ layer
- project(":" + layer.toString()).projectDir = new File("${layerProjRoot}/${layer}")
-}
-</pre>
-</li>
-
-Your next step is to provide the built layers to the app by installing them.
-
-<h4 id="asil">Installing layers</h4>
-
-<li>
-To install your layers, add the layer Gradle projects to your application's jniLibs dependencies
-in your {@code build.gradle} module. This module normally resides under the {@code app/} directory.
-The following example shows how to do this:
-
-<pre>
-android.sources {
- main {
- jni { ... }
- jniLibs {
- dependencies {
- project ":threading"
- project ":parameter_validation"
- project ":object_tracker"
- project ":core_validation"
- project ":device_limits"
- project ":image"
- project ":swapchain"
- project ":unique_objects"
- }
- }
- }
-} // android.sources
-</pre>
-</li>
-<li>
-Develop, build, and debug as you usually would. When you build, Android Studio automatically
-builds the layers and copies them into your APK.
-</li>
-<li>
-Debug your application. Android Studio allows you to trace through the layer source code.
-</li>
-<li>
-For best performance, remove the layers before you do your release build.
-</li>
-</ol>
-
-
-<h3 id="cli">From the Command Line</h3>
-
-This section explains how to build and install your layers if your project does not use
-Android Studio.
-
-<h4 id="clibl">Building layers</h4>
-
-<p>
-To build validation layers on Linux or OS X, enter these commands on the command line:
-</p>
-<ul>
-<li>
-Using Gradle:
-<pre class="no-pretty-print">
-$ cd generated/gradle-build
-$ # configure SDK and NDK path in local.properties
-$ gradlew assembleAllDebug
-</pre>
-</li>
-<li>
-Using Android makefiles:
-<pre class="no-pretty-print">
-$ ndk-build</pre>
-</li>
-</ul>
-
-<p>
-To build validation layers on Windows, enter these commands on the command line:
-</p>
-<ul>
-<li>
-Using Gradle:
-<pre class="no-pretty-print">
-> cd generated\gradle-build
-> REM configure SDK and NDK path in local.properties
-> gradlew.bat assembleAllDebug
-</pre>
-</li>
-<li>
-Using Android makefiles:
-<pre class="no-pretty-print">
-> ndk-build.cmd
-</pre>
-</li>
-</ul>
-
-
-
-</p>
-</li>
-</ol>
-
-<h4 id="cliil">Installing layers</h4>
-
-<p>
-After building the layers, you must provide them to your app. To do so, you must first
-create a {@code jniLibs} folder in your app's project directory under
-{@code ./src/main/}, and copy the libs to it. The following example shows how to do this.
-</p>
-
-<pre class="no-pretty-print">
-$ mkdir ./src/main/jniLibs
-</pre>
-
-<p>
-The next step depends on whether you are using Gradle or Android makefiles. If you're using
-Gradle, each built layer resides in its own directory. Consolidate the layers into a single
-directory, as the following example shows:
-</p>
-
-<pre class="no-pretty-print">
-$ cp -r .../build-android/generated/gradle-build/threading/build/outputs/native/debug/all/lib/* ./src/main/jniLibs/
-$ cp -r .../build-android/generated/gradle-build/parameter_validation/build/outputs/native/debug/all/lib/* ./src/main/jniLibs/
-$ cp -r .../build-android/generated/gradle-build/object_tracker/build/outputs/native/debug/all/lib/* ./src/main/jniLibs/
-$ cp -r .../build-android/generated/gradle-build/core_validation/build/outputs/native/debug/all/lib/* ./src/main/jniLibs/
-$ cp -r .../build-android/generated/gradle-build/device_limits/build/outputs/native/debug/all/lib/* ./src/main/jniLibs/
-$ cp -r .../build-android/generated/gradle-build/image/build/outputs/native/debug/all/lib/* ./src/main/jniLibs/
-$ cp -r .../build-android/generated/gradle-build/swapchain/build/outputs/native/debug/all/lib/* ./src/main/jniLibs/
-$ cp -r .../build-android/generated/gradle-build/unique_objects/build/outputs/native/debug/all/lib/* ./src/main/jniLibs/
-</pre>
-
-If you're using Android makefiles, the built layers reside in {@code lib} folders,
-with one {@code lib} folder under each architecture’s root directory. Consolidate the
-makefiles under the {@code jniLibs} directory as this example shows:
-</p>
-<pre class="no-pretty-print">
-$ cp -r .../build-android/libs/* ./src/main/jniLibs/
-</pre>
-</li>
-</ol>
-
<h2 id="verifying">Verifying Layer Build</h2>
<p>
-Regardless of whether you build using Gradle or Android makefiles, the build process produces
-a file structure like the following:
+Regardless of whether you build with NDK's prebuilt layers or you build from the latest source code,
+the build process produces final file structure like the following:
</p>
<pre class="no-pretty-print">
@@ -571,6 +382,7 @@
</pre>
+<p>
Once your app has registered and enabled the debug callback, the system routes debugging
messages to a callback that you register. An example of such a callback appears below:
</p>