Table of Contents

Включение функций EasyAR в Android-приложении

В этой главе описывается, как настроить Android-проект EasyAR в Android Studio без использования 3D engine, такого как Unity.

Подготовка

Перед началом нужно подготовить:

  • Последнюю версию Android Studio

  • JDK 8/11/17

  • Android Gradle Plugin 4.0 или выше

  • Android NDK r28 или выше

  • Получить лицензию авторизации EasyAR

  • Выбрать версию выпуска и скачать EasyAR Sense

Примечание

Не все Android-устройства поддерживают все функции EasyAR Sense. Некоторые функции зависят от дополнительного hardware или конфигурации. Подробности см. в списке устройств, поддерживающих соответствующую функцию.

Импорт EasyAR Sense for Android

В этом разделе описывается, как импортировать EasyAR Sense SDK в Android-проект без Unity. EasyAR Sense предоставляет Java и C++ API и поддерживает Kotlin, поэтому вы можете разрабатывать на наиболее привычном языке.

Поскольку способы настройки в разных IDE могут отличаться, здесь описан только типичный способ настройки на основе Android Studio + Gradle.

Выбор способа использования API

EasyAR Sense for Android предоставляет два способа использования API:

  • Использовать только Java API
  • Использовать Java и C++ API

Выберите один из них для настройки в соответствии с требованиями проекта.

Использовать только Java API

При использовании только Java API EasyAR настройка NDK не требуется.

Поместите EasyAR.aar в app/libs/ или в каталог, указанный Gradle.

Использовать Java и C++ API

Если одновременно требуется использовать C++ API EasyAR, необходимо настроить как Java-зависимости, так и native-библиотеки.

  • Файлы Java-слоя

    Поместите EasyAR.jar в app/libs/ или в путь, указанный Gradle.

  • Native-библиотеки (.so)

    Поместите native-библиотеки, предоставленные EasyAR, по ABI в следующий путь или в путь, указанный Gradle.

    app/src/main/jniLibs/
├── armeabi-v7a/
│   └── libEasyAR.so
└── arm64-v8a/
    └── libEasyAR.so

  • Заголовочные файлы C++

    Скопируйте папку easyar из каталога include в EasyAR SDK в следующий путь или в путь, указанный Android.mk/CMakeLists.txt.

    app/src/main/jni/easyar/

    Путь к заголовочным файлам должен быть явно указан в Android.mk или CMakeLists.txt.

Описание настройки Gradle

При использовании C++ API необходимо включить Native Build в Gradle. Если используется только Java API, настройка не требуется. Можно настроить через ndk-build (Android.mk).

Добавьте в app/build.gradle:

android {
    externalNativeBuild {
        ndkBuild {
            path "src/main/jni/Android.mk"
        }
    }
}

Если используется CMake, см. официальную документацию Google по настройке.

Настройка NDK

Объявление EasyAR как предварительно собранной библиотеки

include $(CLEAR_VARS)

# Make sure this path points to the current ABI directory in jniLibs
LOCAL_PATH := $(LOCAL_PATH_TOP)/../jniLibs/$(TARGET_ARCH_ABI)

LOCAL_MODULE := EasyAR
LOCAL_SRC_FILES := libEasyAR.so

include $(PREBUILT_SHARED_LIBRARY)

Связывание EasyAR и системных библиотек

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (required)
LOCAL_LDLIBS += -lGLESv3

Для работы EasyAR требуется как минимум OpenGL ES 2.0. Рекомендуется OpenGL ES 3.0 (GLESv3).

Указание архитектур ABI

Явно укажите ABI в app/build.gradle, чтобы избежать упаковки недопустимых архитектур:

android {
    defaultConfig {
        ndk {
            abiFilters "armeabi-v7a", "arm64-v8a"
        }
    }
}

Если нужна только одна архитектура, оставьте только соответствующий пункт.

Настройка разрешений AndroidManifest

EasyAR Sense требует следующие разрешения. Их отсутствие приведет к ошибке инициализации или черному экрану:

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />

Полный пример:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="cn.easyar.samples.helloar">

    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.INTERNET" />

</manifest>

Инициализация EasyAR

Вызовите Engine.initialize при запуске приложения для инициализации.

Пример (Java):

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Engine.initialize(this, key);
}
Примечание

Инициализация должна быть завершена до использования функций EasyAR.

Дополнительная конфигурация

На платформе Android, в зависимости от версии системы и используемых функций, также может потребоваться учитывать следующие конфигурации и ограничения.

Настройка использования ARCore

Если проект использует ARCore, обратитесь к его официальной документации, чтобы выполнить соответствующую настройку AndroidManifest.xml и build.gradle.

Кроме того, перед инициализацией EasyAR необходимо явно загрузить native library ARCore:

System.loadLibrary("arcore_sdk_c");
Примечание

При использовании версий до ARCore v1.19.0 ARCore не будет обнаруживаться на Android 11. Это связано с тем, что начиная с Android 11 введены ограничения app visibility, и имя пакета ARCore нужно объявить в AndroidManifest.xml.

<queries>
    <package android:name="com.google.ar.core" />
</queries>

Настройка obfuscation (ProGuard)

Если для Java-кода включена obfuscation, необходимо исключить namespace cn.easyar.

EasyAR Sense во время выполнения через JNI использует reflection имени класса для получения Java types. Если классы в cn.easyar будут obfuscated или переименованы, может возникнуть undefined behavior.

Базовые правила

-keep class cn.easyar.** { *; }

Рекомендуемые точные правила

-dontwarn javax.annotation.Nonnull
-dontwarn javax.annotation.Nullable
-keepattributes *Annotation*

-keep class cn.easyar.RefBase { native <methods>; }
-keepclassmembers class cn.easyar.* {
    <fields>;
    protected <init>(long, cn.easyar.RefBase);
}
-keep,allowobfuscation interface cn.easyar.FunctorOf* { *; }

-keep class cn.easyar.Buffer { native <methods>; }
-keep class cn.easyar.Engine { native <methods>; }
-keep class cn.easyar.JniUtility { native <methods>; }

-keep class cn.easyar.engine.** { *; }
-keep class cn.easyar.CameraParameters
-keep interface cn.easyar.FunctorOfVoidFromInputFrame

Указанные выше правила ProGuard уже включены в aar library EasyAR, поэтому обычно повторная настройка не требуется.

Scoped Storage

Механизм Scoped Storage, введенный начиная с Android 10, влияет на некоторые API, зависящие от file paths. Это связано с тем, что non-media paths под /sdcard, например пользовательские каталоги, на Android 10 недоступны напрямую. Для EasyAR это проявляется в том, что некоторые API, требующие file paths, например screen recording, на Android 10 не поддерживают прямое чтение и запись media paths, но нормально работают на Android 11.

Решения:

  • Простой вариант (Android 10) Отключить Scoped Storage в AndroidManifest.xml:

    <application
    android:requestLegacyExternalStorage="true"
    ... >
</application>

  • Рекомендуемый вариант

    • Использовать только app internal storage
    • Или обмениваться данными с media paths через MediaStore

Android Gradle Plugin и NDK

Начиная с NDK r22, по умолчанию используется linker LLD, и требуется совместное использование с llvm-strip; это несовместимо со встроенным tool strip в Android Gradle Plugin ниже версии 4.0. Решения:

  • Обновиться до Android Gradle Plugin 4.0 или выше
  • Или использовать doNotStrip в packagingOptions, чтобы отключить stripping (не рекомендуется)

Ограничение длины пути Windows

В Windows, если абсолютная длина пути любого файла в проекте, включая временные файлы, создаваемые во время build, превышает 260 символов, build в Android Studio может завершиться ошибкой.

Решения:

  • Поместить проект в более короткий путь, например C:\user\project
  • Избегать слишком глубоких уровней каталогов

Дополнительное чтение