Memory Advice API 使用入门

本指南介绍了如何使用 Android Studio 将 Memory Advice API 的 Jetpack 版本集成到您的应用中。

Android Games 应使用为其构建环境推荐的 Memory Advice API 版本。对于 Android Studio，我们建议使用 Jetpack 版本。如需了解适用于其他构建环境（例如 Android Game Development Extension (AGDE)）的版本，请参阅分发情况。

添加库

本部分介绍了如何将库添加到您的 Android Studio（Android Gradle 插件）项目中。

添加依赖项

若要将库添加到 Android Studio 项目，请完成以下步骤：

在项目级 gradle.properties 中启用 Android Jetpack 库，该文件通常位于项目的根目录中：
```
  android.useAndroidX=true
```
打开模块级 build.gradle 文件，并将以下 implementation 添加到依赖项代码块中。这会在应用中声明 Memory Advice API 依赖项。
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
在 android 代码块内指定 NDK 版本：
```
 ndkVersion "23.1.7779620"
```
请务必选择与 Memory Advice API 兼容的 NDK 版本。Android Games Jetpack 版本页面上列出了受支持的 NDK 版本。

为 CMake 声明其他构建标志。为此，请将以下代码添加到 android 代码块内的 defaultConfig 代码块中：

 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 页面了解配置说明。

保存文件。如果您看到以下消息，请点击 Sync Now 按钮以更新您的项目：

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

为 C/C++ build 配置 CMake

如需将 Memory Advice API 的头文件和运行时库添加到项目中，请打开项目的主 CMakeLists.txt 文件。在 Project 窗格中，该文件位于 app > src > main > cpp 中。打开文件后，请执行以下步骤：

在文件顶部附近的任何 cmake_minimum_required 和 project 行之后，添加以下行：
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
在 target_link_libraries 命令中添加 games-memory-advice::memory_advice。这会使 Memory Advice API 成为您项目的原生库的依赖项，并将其包含在最终应用软件包中。更新代码应与以下代码类似：
```
 target_link_libraries(
     your-native-lib

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

     #rest of the dependencies
     #...
 )
```

配置 Java 文件

Memory Advice API 中包含的原生库是 libmemory_advice.so。它是应用自己的 C/C++ 共享库的编译依赖项，将在应用使用 System.loadlibrary() 函数加载自己的共享库时自动加载。

这是可选步骤。

在项目中找到加载原生库的 Java 代码。如果该代码不存在，请予以添加。该代码应类似于 System.loadLibrary("your-native-lib")，并位于 static 代码块中。

在 System.loadLibrary("your-native-lib") 下添加 System.loadLibrary("memory_advice")。更新代码应与以下代码类似：

 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;
    }

设置观察器

您也可以设置观察器并注册 Memory Advice API，并在状态接近上限或紧急内存状态（但不适用于 ok 状态）时调用 watcher 函数。例如，以下代码会创建一个观察器并每 2 秒请求 Memory Advice API 通知：

    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);

后续操作

如需查看其他资源和报告问题，请参阅概览。