Memory Advice API 处于 Beta 版阶段。

Memory Advice API 入门

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

游戏应使用其构建环境建议的 Memory Advice API 版本。对于 Android Studio，我们推荐 Jetpack 版本。有关其他构建环境（例如 Android 游戏开发扩展 (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++ 构建配置 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 库，请务必在调用 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;
    }

设置观察器

您还可以设置观察器并注册 Memory Advice API，当状态接近限制或达到关键内存状态时（但不包括“正常”状态），您的观察器函数将被调用。例如，以下代码创建一个观察器并请求每 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);

下一步

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

Memory Advice API 入门 使用收藏夹保持井然有序 根据您的偏好保存和分类内容。

添加库