From c1755d345d84e8c06b69a1f8bc2c69c7e4752885 Mon Sep 17 00:00:00 2001 From: ggfan Date: Thu, 9 Jun 2016 12:44:01 -0700 Subject: [PATCH] Update validation-layer.jd for NDK-R12: use packed layer binaries punt building layers to Khronos github repo Change-Id: Icf840de42856d2488a87174b2cd6c604ef8d8770 (cherry picked from commit f22d094a30c9446abe074b82bb84f6daf51e0534) --- .../ndk/guides/graphics/getting-started.jd | 2 +- .../ndk/guides/graphics/validation-layer.jd | 344 ++++-------------- 2 files changed, 79 insertions(+), 267 deletions(-) diff --git a/docs/html/ndk/guides/graphics/getting-started.jd b/docs/html/ndk/guides/graphics/getting-started.jd index 145e534783b1c..0c2d939f1182e 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" />
  1. Select your project in the Android Studio Project panel.
    2. -
  2. From the Build menu, choose Make Module <module-name> .
    3. +
  3. From the Build menu, choose Make Module <module-name> ; or select Build APK to generate APK.
  4. 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.
    5. On this page
      +
    1. Add Validation Layers to Project
    2. Getting Layer Source
      3. -
    3. Android Studio Integration -
        -
      1. Building Layers
        2. -
      2. Installing Layers
        3. -
      -
      4. -
    4. Integrating on the Command Line -
        -
      1. Building Layers
        2. -
      2. Installing Layers
        3. -
      -
    5. Verifying Layer Build
    6. Enabling Layers
    7. Enabling the Debug Callback
      8. @@ -52,272 +41,94 @@ during development.

      This page explains how to:

        +
      • Integrate NDK's Layer Binaries.
      • Get source code for validation layers.
        • -
      • Build the layers.
        • -
      • Incorporate the layers into your app.
        • +
      • Verifying Layer Build.
        • +
      • Enabling Layers in Vulkan Application.
        • +

      +

      Add Validation Layers to Project

      + +

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

      + +

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

      + + +

      Adding validation layers with Gradle

      + +

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

      + + +

      + To add the libraries using Android Studio's support for CMake/Ndk-build, + add the following to your project's gradle configuration: +

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

      + To add the libraries using Android Studio's experimental plugin for Gradle, + add the following to your project's gradle configuration: +

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

      Adding validation layers to JNI libraries

      + +

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

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

      Getting Layer Source

      -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 Android Studio or from the -command line. -

      -

      From the NDK (Recommended)

      - -

      -NDK Revision 12 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 build them. Alternatively, you can pull source code from the -Khronos Group repository. - -

      - -

      From the repository

      - -

      -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 -GitHub repository belonging to the Khronos Group. To do so, perform the following steps. +GitHub repository and follow the build instructions there.

      -
        -
      1. -Clone the Vulkan directory by entering the following command in your terminal window: - -
        -$ git clone git@github.com:KhronosGroup/Vulkan-LoaderAndValidationLayers.git
-
        - -

        Note: You must have a private SSH key associated with -GitHub, or this command fails with a {@code Permission denied (publickey)} message.

        -
        2. - -
      2. -Navigate to the directory containing the layer source code, and -check out the repo's stable Android branch, called {@code android_layers}: - -
        -$ cd Vulkan-LoaderAndValidationLayers
-$ git checkout android_layers
-
        -
        3. - -
      3. -Begin preparation for building by entering the following commands on the command line: -
          -
        • For Linux or OS X: -
            -
          • - 
            -$ cd build-android
-$ ./android-generate
            -
            • -
          -
          • - -
        • For Windows: -
            -
          • -
            -> cd build-android
-> android-generate.bat
            -
            • -
          -
          • -
        -
        4. - -
      4. -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. -
        5. - - -
      - -

      Android Studio Integration

      -

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

      - -

      Building layers

      - -

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

      -
    8. -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 -using the {@code build.gradle} files from the NDK. - -
      -// 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}")
-}
-
      -
      9. - -Your next step is to provide the built layers to the app by installing them. - -

      Installing layers

      - -
    9. -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: - -
      -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
-
      -
      10. -
    10. -Develop, build, and debug as you usually would. When you build, Android Studio automatically -builds the layers and copies them into your APK. -
      11. -
    11. -Debug your application. Android Studio allows you to trace through the layer source code. -
      12. -
    12. -For best performance, remove the layers before you do your release build. -
      13. -
    - - -

    From the Command Line

    - -This section explains how to build and install your layers if your project does not use -Android Studio. - -

    Building layers

    - -

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

    - - -

    -To build validation layers on Windows, enter these commands on the command line: -

    - - - - -

    - -
- -

Installing layers

- -

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

- -
-$ mkdir ./src/main/jniLibs
-
- -

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

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

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

Verifying Layer Build

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

@@ -571,6 +382,7 @@ if (vkDestroyDebugReportCallbackEXT) {
+

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: