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

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

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

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

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

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

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

Включите библиотеку Android Jetpack на уровне проекта gradle.properties ), файл обычно находится в корневом каталоге вашего проекта:
```
  android.useAndroidX=true
```
Откройте файл build.gradle уровня модуля и добавьте следующую implementation в блок зависимостей. Это объявляет зависимости API рекомендаций по памяти в вашем приложении.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
Укажите версию NDK внутри блока android :
```
 ndkVersion "23.1.7779620"
```
Обязательно выберите версию NDK, совместимую с API Memory Advice. Список поддерживаемых версий NDK доступен на странице выпуска Android Games Jetpack .
Объявите дополнительные флаги сборки для CMake. Для этого добавьте следующий код в блок defaultConfig , который находится внутри блока android :
```
 externalNativeBuild {
     cmake {
         cppFlags '-std=c++14'
         // c++_shared flavor is the only supported STL type.
         arguments "-DANDROID_STL=c++_shared"
     }
 }
```
Включите функцию Prefab . Для плагина Android Gradle (AGP) 4.1 или более поздней версии добавьте в блок android следующий код:
```
 buildFeatures {
    prefab true
 }
```
Если вы используете AGP 4.0 или более раннюю версию, инструкции по настройке см. на странице Prefab .
Сохраните файл. Если вы видите следующее сообщение, нажмите кнопку «Синхронизировать сейчас», чтобы обновить проект:
```
  Gradle files have changed since last project sync. A project sync may be
  necessary for the IDE to work properly.
```

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

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

В верхней части файла добавьте следующую строку после всех строк cmake_minimum_required и project :
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
В команде 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() .

Этот шаг не является обязательным.

Найдите в своем проекте код Java, который загружает собственные библиотеки. Если его не существует, добавьте его. Код должен выглядеть аналогично System.loadLibrary("your-native-lib") и находится в static блоке.
Добавьте 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);

Что дальше

См. обзор дополнительных ресурсов и проблем с отчетами .