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 プロジェクトに該当のライブラリを追加する手順は次のとおりです。

  1. プロジェクト レベルの gradle.properties ファイルで、次のように Android Jetpack ライブラリを有効にします。このファイルは通常、プロジェクトのルート ディレクトリに存在します。

      android.useAndroidX=true

  2. モジュール レベルの build.gradle ファイルを開き、次の implementation を dependencies ブロックに追加します。これにより、アプリで Memory Advice API の依存関係が宣言されます。

     dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }

  3. NDK バージョンを android ブロックに指定します。

     ndkVersion "23.1.7779620"

    必ず Memory Advice API に対応している NDK バージョンを指定してください。対応している NDK バージョンの一覧については、Android Games の Jetpack リリースのページをご覧ください。

  4. CMake の追加のビルドフラグを宣言します。そのために、android ブロック内の defaultConfig ブロックに次のコードを追加します。

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

  5. Prefab 機能を有効にします。Android Gradle プラグイン（AGP）4.1 以降を使用している場合は、次のコードを android ブロックに追加します。

     buildFeatures {
    prefab true
 }

    AGP 4.0 以前を使用している場合の設定手順については、Prefab のページをご覧ください。

  6. ファイルを保存します。次のメッセージが表示された場合は、[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] にあります。開いたら、次の手順を行います。

  1. ファイルの先頭付近にあるすべての cmake_minimum_required 行および project 行の下に、次の行を追加します。

     find_package(games-memory-advice REQUIRED CONFIG)

  2. 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() 関数で自身の共有ライブラリを読み込むときに自動的に読み込まれます。

このステップは省略可能です。

  1. プロジェクト内でネイティブ ライブラリを読み込む Java コードを見つけます。存在しない場合は追加します。このコードは System.loadLibrary("your-native-lib") のように記述されており、static ブロックにあります。

  2. 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>

ライブラリを初期化する

アプリの起動時に 1 回、ライブラリを初期化する必要があります。そのために、次のコードをプロジェクトに追加します。

    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 を登録することもできます。これにより、メモリ状態が上限に近づいた、またはひっ迫した際に、ウォッチャー関数が呼び出される（OK 状態では呼び出されない）ようにできます。たとえば、次のコードはウォッチャーを作成して 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 の概要で、参考情報および問題とフィードバックについてご確認ください。