開始使用 Memory Advice API

本指南說明如何使用 Android Studio，將 Memory Advice API 的 Jetpack 版本整合至您的應用程式。

遊戲使用的 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 遊戲 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」>「primary」>「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 函式。

記憶體狀態輪詢

以您選擇的時間間隔輪詢程式庫，即可擷取應用程式的記憶體狀態。每當您需要輪詢程式庫時，請使用 MemoryAdtip_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 Adtip 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);

後續步驟

請參閱總覽，瞭解其他資源以及如何回報問題。