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

<ol style="1">

<ol style="1">

<li>Select your project in the Android Studio <em>Project</em> panel.</li>

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

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

<img src="../images/config-pulldown.png"

      <h2>On this page</h2>

      <h2>On this page</h2>

      <ol>

      <ol>

        <li><a href="#ilp">Add Validation Layers to Project</a></li>

        <li><a href="#gls">Getting Layer Source</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="#verifying">Verifying Layer Build</a></li>

        <li><a href="#enabling">Enabling Layers</a></li>

        <li><a href="#enabling">Enabling Layers</a></li>

        <li><a href="#debug">Enabling the Debug Callback</a></li>

        <li><a href="#debug">Enabling the Debug Callback</a></li>

<p>

<p>

This page explains how to:

This page explains how to:

<ul>

<ul>

   <li>Integrate NDK's Layer Binaries.</li>

   <li>Get source code for validation layers.</li>

   <li>Get source code for validation layers.</li>

   <li>Build the layers.</li>

   <li>Verifying Layer Build.</li>

   <li>Incorporate the layers into your app.</li>

   <li>Enabling Layers in Vulkan Application.</li>

</ul>

</ul>

</p>

</p>

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

<h2 id="ilp">Add Validation Layers to Project</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>

<p>

<a href="{@docRoot}ndk/downloads/index.html">NDK Revision 12</a> and later contains source

  NDK release 12 and higher includes pre-built validation layer binaries. At

code for Android validation layers that is known-good, and ready to build. This code resides under

  instance and device creation time, when requested by your application, the

the {@code <ndk-root>/sources/third_party/vulkan/src/build-android/generated/gradle-build}

  Vulkan loader finds them in the APK installed location and loads them.

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>

</p>

<h3 id="ftr">From the repository</h3>

<p>

<p>

Although we recommend that you use the source code provided with the NDK, you can also pull more

  To use the pre-built validation layer binaries, either modify the gradle build

recent versions of the source code directly from the

  configuration of your project or manually add the binaries into the JNI

<a class="external-link" href="https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers">

  libraries directory of your project.

GitHub repository</a> belonging to the Khronos Group. To do so, perform the following steps.

</p>

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

<p>

Android Studio builds the validation layers when it builds the rest of the app.

  You can add the validation layer your project using either Andorid Studio's

This flow makes it easier for you to trace through the layers at runtime. Each layer's

  support for CMake and Ndk-build, or using Studio's experimental plugin for

source code corresponds to a single Gradle project, which you can specify directly in your Android

  Gradle. In general, you should use the CMake and Ndk-build configuration.

Studio app. For example, there is a {@code build.gradle} project for threading, and another

one for parameter validation.

</p>

</p>

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

<p>

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

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

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

To install your layers, add the layer Gradle projects to your application's jniLibs dependencies

sourceSets {

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 {

  main {

        jni { ... }

    jniLibs {

    jniLibs {

            dependencies {

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

                project ":threading"

                project ":parameter_validation"

                project ":object_tracker"

                project ":core_validation"

                project ":device_limits"

                project ":image"

                project ":swapchain"

                project ":unique_objects"

            }

    }

    }

  }

  }

} // android.sources

}</pre>

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

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

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

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

> ndk-build.cmd

sources {

</pre>

  main {

</li>

    jniLibs {

</ul>

      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>

<p>

After building the layers, you must provide them to your app. To do so, you must first

  If configuring your project's gradle build file is not working, you can

create a {@code jniLibs} folder in your app's project directory under

  manually add the validation layer binaries to your project's JNI libraries

{@code ./src/main/}, and copy the libs to it. The following example shows how to do this.

  directory by using the following command line options:

</p>

</p>

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

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

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

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

with one {@code lib} folder under each architecture’s root directory. Consolidate the

<p>

makefiles under the {@code jniLibs} directory as this example shows:

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>

</p>

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

$ cp -r .../build-android/libs/* ./src/main/jniLibs/

</pre>

</li>

</ol>

<h2 id="verifying">Verifying Layer Build</h2>

<h2 id="verifying">Verifying Layer Build</h2>

<p>

<p>

Regardless of whether you build using Gradle or Android makefiles, the build process produces

Regardless of whether you build with NDK's prebuilt layers or you build from the latest source code,

a file structure like the following:

the build process produces final file structure like the following:

</p>

</p>

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

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

</pre>

</pre>

<p>

Once your app has registered and enabled the debug callback, the system routes debugging

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:

messages to a callback that you register. An example of such a callback appears below:

</p>

</p>