Начало работы с API-интерфейсом Memory Advice

В этом руководстве описывается, как интегрировать версию Jetpack API Memory Advice в ваше приложение с помощью Android Studio.

В играх следует использовать версию API Memory Advice, рекомендованную для вашей среды сборки. Для Android Studio мы рекомендуем версию Jetpack. Информация о версиях для других сред сборки, таких как Android Game Development Extension (AGDE), представлена в разделе «Дистрибутивы» .

Добавить библиотеку

В этом разделе описывается, как добавить библиотеку в ваш проект Android Studio (плагин Android Gradle).

Добавьте зависимости

Чтобы добавить библиотеку в проект Android Studio, выполните следующие действия:

  1. Включите библиотеку Android Jetpack на уровне проекта gradle.properties ). Обычно файл находится в корневом каталоге вашего проекта:

      android.useAndroidX=true

  2. Откройте файл build.gradle на уровне модуля и добавьте следующую implementation в блок зависимостей. Это декларирует зависимости API-интерфейса memory advice в вашем приложении.

     dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }

  3. Укажите версию NDK внутри блока android :

     ndkVersion "23.1.7779620"

    Убедитесь, что выбранная вами версия NDK совместима с API Memory Advice. Список поддерживаемых версий NDK доступен на странице выпуска Android Games Jetpack .

  4. Объявите дополнительные флаги сборки для CMake. Для этого добавьте следующий код в блок defaultConfig внутри блока android :

     externalNativeBuild {
     cmake {
         cppFlags '-std=c++14'
         // c++_shared flavor is the only supported STL type.
         arguments "-DANDROID_STL=c++_shared"
     }
 }

  5. Включите функцию Prefab . Для Android Gradle Plugin (AGP) 4.1 или выше добавьте следующий код в блок android :

     buildFeatures {
    prefab true
 }

    Если вы используете AGP 4.0 или более позднюю версию, см. страницу Prefab для получения инструкций по настройке.

  6. Сохраните файл. Если вы видите следующее сообщение, нажмите кнопку «Синхронизировать сейчас» , чтобы обновить проект:

      Gradle files have changed since last project sync. A project sync may be
  necessary for the IDE to work properly.

Настройте CMake для сборки C/C++

Чтобы добавить заголовочные файлы и библиотеку времени выполнения для Memory Advice API в свой проект, откройте основной файл CMakeLists.txt . На панели «Проект» файл находится в папке app > src > main > cpp . После открытия файла выполните следующие действия:

  1. В верхней части файла добавьте следующую строку после всех строк cmake_minimum_required и project :

     find_package(games-memory-advice REQUIRED CONFIG)

  2. В команде target_link_libraries добавьте games-memory-advice::memory_advice . Это сделает API Memory Advice зависимостью от нативной библиотеки вашего проекта и включит его в финальный пакет приложения. Обновление должно выглядеть примерно так:

     target_link_libraries(
     your-native-lib

     #link memory advice to the project
     games-memory-advice::memory_advice

     #rest of the dependencies
     #...
 )

Настройте файлы Java

Встроенная библиотека, входящая в состав API Memory Advice, — libmemory_advice.so . Она является компилируемой зависимостью для собственной общей библиотеки C/C++ вашего приложения и автоматически загружается при загрузке приложением собственной общей библиотеки с помощью функции System.loadlibrary() .

Этот шаг необязателен.

  1. Найдите в своём проекте код Java, загружающий нативные библиотеки. Если его нет, добавьте его. Код должен выглядеть примерно так: System.loadLibrary("your-native-lib") и находиться в static блоке.

  2. Добавьте System.loadLibrary("memory_advice") в System.loadLibrary("your-native-lib") . Обновление должно выглядеть примерно так:

     static {
     System.loadLibrary("your-native-lib");
     // Note: loading libmemory_advice.so is optional.
     System.loadLibrary("memory_advice");
 }

Использовать библиотеку

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

Добавьте заголовочные файлы

Включите в свой проект следующий заголовочный файл библиотеки: 

    #include <memory_advice/memory_advice.h>

Инициализировать библиотеку

Библиотеку необходимо инициализировать один раз при запуске приложения. Для этого добавьте в проект следующий код: 

    MemoryAdvice_init(env, activity);

Параметры env и activity — это переменные JNIEnv* и jobject , которые должны быть доступны вашей нативной библиотеке. Каждый вызов JNI к вашей нативной библиотеке должен содержать эти переменные. Если вы используете библиотеку GameActivity , обязательно подключите вызывающий поток к JavaVM перед вызовом функции MemoryAdvice_init .

Опрос состояния памяти

Вы можете получить состояние памяти вашего приложения, опрашивая библиотеку с выбранным интервалом. Используйте функцию MemoryAdvice_getMemoryState каждый раз, когда вам нужно опрашивать библиотеку: 

    MemoryAdvice_MemoryState state = MemoryAdvice_getMemoryState();
    switch (state) {
      case MEMORYADVICE_STATE_OK:
        // The application can safely allocate significant memory.
        break;
      case MEMORYADVICE_STATE_APPROACHING_LIMIT:
        //The application should minimize memory allocation.
        break;
      case MEMORYADVICE_STATE_CRITICAL:
        // The application should free memory as soon as possible,
        // until the memory state changes.
        break;
    }

Настройте наблюдателя

Вы также можете настроить наблюдателя и зарегистрировать API Memory Advice, и ваша функция-наблюдатель будет вызываться, когда состояние памяти приближается к пределу или к критическому (но не для состояния «ok»). Например, следующий код создаёт наблюдателя и запрашивает уведомление API Memory Advice каждые 2 секунды: 

    static int USER_DATA;
    constexpr int callback_waittime_ms = 2000;

    void callback(MemoryAdvice_MemoryState state, void* context) {
        switch (state) {
          case MEMORYADVICE_STATE_APPROACHING_LIMIT:
            //The application should minimize memory allocation.
            break;
          case MEMORYADVICE_STATE_CRITICAL:
            // The application should free memory as soon as possible,
            // until the memory state changes.
            break;
        }
    }

    MemoryAdvice_registerWatcher(callback_waittime_ms, callback, &USER_DATA);

Что дальше?

Ознакомьтесь с обзором для получения информации о дополнительных ресурсах и сообщениях о проблемах .