启用 ARCore

本页介绍如何在您的 Android NDK 项目中启用 ARCore 功能。 为此,您需要做的是:

向 manifest 添加 AR 必备或 AR 可选

AR 应用有两种类型:AR 必备AR 可选

AR 必备

AR 必备是指您的应用没有 AR 便无法使用,它使您的应用只能在支持 ARCore 的设备上使用。 如需了解详细信息,请参阅在应用商店中发布 AR 应用

要让您的应用成为 AR 必备应用,请修改您的应用 manifest,在其中加入下列条目:

<uses-sdk android:minSdkVersion="{24 or higher}" />

  ...
  <uses-feature android:name="android.hardware.camera.ar" android:required="true" />

  <application>
    ...
        <meta-data android:name="com.google.ar.core" android:value="required" />
    ...

AR 可选

AR 可选是指您的应用包括的一项或多项 AR 功能会在设备支持 ARCore 时启用。 但应用也可在不支持 ARCore 的设备上安装和运行。 当用户安装 AR 可选应用时,应用商店不会安装 ARCore

要将您的应用标记为 AR 可选,请修改您的应用 manifest,在其中加入下列条目:

  <uses-sdk android:minSdkVersion="{14 or higher}" />
  ...

  <application>
    ...
        <meta-data android:name="com.google.ar.core" android:value="optional" />
    ...

添加构建依赖项

要将 ARCore 库添加到您的 Android Studio 项目,请执行下列步骤:

  1. 确保您的项目build.gradle 文件包括 Google 的 Maven 代码库。

    allprojects {
    repositories {
        google()
            ...
    
  2. 从 ARCore aar 中提取本机库。

    本机库包含在 ARCore aar 文件中。 要在 C/C++ 项目中使用本机库,必须从归档中提取本机库,以便能够直接引用。 为此,向模块的 build.gradle 文件(例如 app/build.gradle)添加一个自定义任务。

    ARCore 的头文件 arcore_c_api.h 包含在 GitHub SDK 项目中:

    定义一个变量,指向 app/build 目录中的某个目录。 本机库将提取到该目录。 另外创建一个 gradle 配置,用于存放提取任务和数据。

    /*
    The arcore aar library contains the native shared libraries.  These are
    extracted before building to a temporary directory.
    */
    def arcore_libpath = "${buildDir}/arcore-native"
    
    // Create a configuration to mark which aars to extract .so files from
    configurations { natives }
    
    

    创建一个从 aar 文件复制本机库的任务,并将其添加到构建依赖项

      // Extracts the shared libraries from aars in the natives configuration.
      // This is done so that NDK builds can access these libraries.
      task extractNativeLibraries() {
         // Extract every time.
         outputs.upToDateWhen { false }
    
         doFirst {
              configurations.natives.files.each { f ->
                  copy {
                      from zipTree(f)
                      into arcore_libpath
                      include "jni/**/*"
                  }
              }
          }
      }
    
      tasks.whenTaskAdded {
          task-> if (task.name.contains("external") && !task.name.contains("Clean")) {
              task.dependsOn(extractNativeLibraries)
          }
      }
    
  3. 配置本机构建标志,将位置传递给外部构建工具。

    此示例源自 GitHub 项目中的示例。

          externalNativeBuild {
              cmake {
                  cppFlags "-std=c++11", "-Wall"
                  arguments "-DANDROID_STL=c++_static",
                          "-DARCORE_LIBPATH=${arcore_libpath}/jni",
                          "-DARCORE_INCLUDE=${project.rootDir}/../../libraries/include"
              }
          }
    

  4. 为 Java 和本机库添加依赖项。

     dependencies {
          ...
          // Add java and native dependencies on the ARCore library
          implementation 'com.google.ar:core:1.5.0'
          natives 'com.google.ar:core:1.5.0'
          ...
     }
    
  5. CMakeLists.txt 中引用本机库

    # Import the ARCore library.
    add_library(arcore SHARED IMPORTED)
    set_target_properties(arcore PROPERTIES IMPORTED_LOCATION
                  ${ARCORE_LIBPATH}/${ANDROID_ABI}/libarcore_sdk_c.so
                  INTERFACE_INCLUDE_DIRECTORIES ${ARCORE_INCLUDE}
    )
    

执行运行时检查

检查 ARCore 是否已安装

所有 AR 应用都必须先调用 ArCoreApk_requestInstall(),然后再创建 ARCore 会话。 ArCoreApk_requestInstall() 检查是否安装了兼容版本的 ARCore(该版本可能已过时或已由用户手动移除)并在不存在兼容版本的 ARCore 时提示用户安装。

// Tracks if we have already triggered an installation request.
bool install_requested_;

void nativeOnCreate() {
  // other setup

  install_requested_ = false;
}

void nativeOnResume(JNIEnv env, jobject activity) {
  if (ar_session_ == null) {
    bool user_requested_install = !install_requested_;

    ArInstallStatus install_status;
    ArStatus error = ArCoreApk_requestInstall(
        env, activity, user_requested_install, &install_status);
    if (error != AR_SUCCESS) {
      // Inform user of error.
      return;
    }

    switch (install_status) {
      case AR_INSTALL_STATUS_INSTALLED:
        break;
      case AR_INSTALL_STATUS_INSTALL_REQUESTED:
        install_requested_ = true;
        return;
    }

    // Request camera permissions.

    error = ArSession_create(env, context, &ar_session_);
    if (error != AR_SUCCESS) {
      // Inform user of error.
      return;
    }

    // Configure session
  }

  // Normal onResume behavior
}

如果 ArCoreApk_requestInstall() 返回 AR_INSTALL_STATUS_INSTALL_REQUESTED,则当前 Activity 暂停,并提示用户安装或更新 ARCore。 当用户返回 Activity 时,Activity 的 onResume() 会再次执行。

检查是否支持 ARCore(仅限 AR 可选)

AR 可选应用可以利用 ArCoreApk_checkAvailability() 来确定当前设备是否支持 ARCore。 在不支持 ARCore 的设备上,应用应停用 AR 相关功能并隐藏关联的界面元素。

void maybeEnableArButton(JNIEnv env, jobject context) {
  // Likely called from Activity.onCreate() of an activity with AR buttons.
  ArAvailability availability
  ArCoreApk_checkAvailability(env, context, &availability);
  if (availability == AR_AVAILABILITY_UNKNOWN_CHECKING) {
    // Set a timer to call maybeEnableArButton() again after about 200ms.
  }
  if (availability == AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED ||
      availability == AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD ||
      availability == AR_AVAILABILITY_SUPPORTED_INSTALLED) {
    // Show/enable AR button.
  } else {
    // Hide/disable AR button.
  }
}

然后,当用户想使用 AR 功能时,您的应用应确保 ARCore 已安装。 可通过启动遵循上述 AR 必备模式的 Activity 来轻松实现这一目的。

后续步骤

阅读示例应用以及 C API 参考中的代码和注释。