diff options
| -rw-r--r-- | docs/html/ndk/guides/graphics/getting-started.jd | 2 | ||||
| -rw-r--r-- | docs/html/ndk/guides/graphics/validation-layer.jd | 286 |
2 files changed, 50 insertions, 238 deletions
diff --git a/docs/html/ndk/guides/graphics/getting-started.jd b/docs/html/ndk/guides/graphics/getting-started.jd index 145e534783b1..0c2d939f1182 100644 --- a/docs/html/ndk/guides/graphics/getting-started.jd +++ b/docs/html/ndk/guides/graphics/getting-started.jd @@ -137,7 +137,7 @@ alt="Project pane after importing samples into Android Studio" id="figure1" /> <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 beac1c09bbc8..1a7d83246d01 100644 --- a/docs/html/ndk/guides/graphics/validation-layer.jd +++ b/docs/html/ndk/guides/graphics/validation-layer.jd @@ -6,19 +6,8 @@ page.title=Vulkan Validation Layers on Android <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 @@ during development. <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 -> 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 { - 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" - } - } +<pre class="no-pretty-print"> +sourceSets { + main { + jniLibs { + 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"> @@ -571,6 +382,7 @@ if (vkDestroyDebugReportCallbackEXT) { </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> |