Merge \\"Update validation-layer.jd for NDK-R12: use packed layer binaries ...

<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>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>

<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"

      <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>

<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="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>

<h2 id="ilp">Add Validation Layers to Project</h2>

<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>

  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>

<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

<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.

  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>

<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

&gt; 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="vl-gradle">Adding validation layers with Gradle</h3>

<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.

  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>

<h4 id="asbl">Building layers</h4>

<p>

To integrate layers directory into Android Studio application, perform these steps:

  To add the libraries using Android Studio's support for CMake/Ndk-build,

  add the following to your project's gradle configuration:

</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 {

<pre class="no-pretty-print">

sourceSets {

  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"

            }

      srcDir "${your-ndk-dir}/sources/third_party/vulkan/src/build-android/jniLibs"

    }

  }

} // 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>

}</pre>

<p>

To build validation layers on Linux or OS X, enter these commands on the command line:

  To add the libraries using Android Studio's experimental plugin for Gradle,

  add the following to your project's gradle configuration:

</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>

sources {

  main {

    jniLibs {

      source.srcDir "${your-ndk-dir}/sources/third_party/vulkan/src/build-android/jniLibs"

    }

  }

}</pre>

</p>

</li>

</ol>

<h4 id="cliil">Installing layers</h4>

<h3 id="vl-jni-lib">Adding validation layers to JNI libraries</h3>

<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.

  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">

$ mkdir ./src/main/jniLibs

$ 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>

<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:

<h2 id="gls">Getting Layer Source</h2>

<p>

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> and follow the build instructions there.

</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">

</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>