内存建议API处于测试阶段。

内存建议API入门

本指南介绍如何在您的应用中使用Android Studio集成Jetpack 版本的内存建议API。

游戏应使用其构建环境推荐的内存建议API版本。对于Android Studio，我们建议使用Jetpack版本。有关其他构建环境（如Android游戏开发扩展(AGDE)）的版本信息，请参阅分发。

添加库

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

添加依赖项

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

在项目级gradle.properties（该文件通常位于项目的根目录中）中启用Android Jetpack库。
```
  android.useAndroidX=true
```
打开模块级build.gradle文件，并在依赖项块中添加以下implementation。这将在您的应用中声明内存建议API依赖项。
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
在android块内指定NDK版本
```
 ndkVersion "23.1.7779620"
```
确保选择与内存建议API兼容的NDK版本。支持的NDK版本的列表可在Android游戏Jetpack版本页面上找到。

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

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

启用预制件功能。对于Android Gradle插件(AGP) 4.1或更高版本，请将以下代码添加到android块中
```
 buildFeatures {
    prefab true
 }
```
如果您使用的是AGP 4.0或更早版本，请参阅预制件页面以获取配置说明。

保存文件。如果您看到以下消息，请单击“立即同步”按钮以更新您的项目

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

为C/C++构建配置CMake

要将内存建议API的头文件和运行时库添加到您的项目中，请打开项目的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成为您项目原生库的依赖项，并将其包含在最终的应用程序包中。更新应类似于以下内容
```
 target_link_libraries(
     your-native-lib

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

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

配置Java文件

内存建议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 库，请确保在调用 MemoryAdvice_init 函数之前将调用线程附加到 JavaVM。

轮询内存状态

您可以通过以您选择的间隔轮询库来检索应用程序的内存状态。无论何时需要轮询库，请使用 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，当状态即将达到限制或临界内存状态时（但不是对于正常状态），您的观察器函数将被调用。例如，以下代码创建了一个观察器，并请求每 2 秒通知一次内存建议 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);

下一步

请参阅概述，了解其他资源和报告问题。