Memulai Memory Advice API

Panduan ini menjelaskan cara mengintegrasikan rilis Jetpack Memory Advice API dalam aplikasi Anda menggunakan Android Studio.

Game harus menggunakan rilis Memory Advice API yang direkomendasikan untuk lingkungan build-nya. Untuk Android Studio, sebaiknya gunakan rilis Jetpack. Untuk mengetahui informasi tentang rilis untuk lingkungan build lainnya, seperti Android Game Development Extension (AGDE), lihat Distribusi.

Menambahkan library

Bagian ini menjelaskan cara menambahkan library ke project Android Studio (Plugin Android Gradle).

Menambahkan dependensi

Untuk menambahkan library ke project Android Studio Anda, selesaikan langkah-langkah berikut:

Aktifkan library Android Jetpack di level project gradle.properties), file biasanya berada di direktori utama project Anda:
```
  android.useAndroidX=true
```
Buka file build.gradle level modul dan tambahkan implementation berikut ke blok dependensi. Ini mendeklarasikan dependensi memory advice API dalam aplikasi Anda.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
Tentukan versi NDK di dalam blok android:
```
 ndkVersion "23.1.7779620"
```
Pastikan untuk memilih versi NDK yang kompatibel dengan Memory Advice API. Daftar versi NDK yang didukung tersedia di halaman Rilis Jetpack Android Games.

Deklarasikan flag build tambahan untuk CMake. Untuk melakukannya, tambahkan kode berikut ke blok defaultConfig yang ada di dalam blok android:

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

Aktifkan fitur Prefab. Untuk Plugin Android Gradle(AGP) 4.1 atau yang lebih tinggi, tambahkan kode berikut ke blok android:
```
 buildFeatures {
    prefab true
 }
```
Jika Anda menggunakan AGP 4.0 atau yang lebih lama, lihat halaman Prefab untuk petunjuk konfigurasi.

Simpan file tersebut. Jika Anda melihat pesan berikut, klik tombol Sync Now untuk mengupdate project:

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

Mengonfigurasi CMake untuk build C/C++

Untuk menambahkan file header dan library runtime untuk Memory Advice API ke project Anda, buka file CMakeLists.txt utama project Anda. Di panel Project, file berada di app > src > main > cpp. Setelah membuka file, lakukan langkah-langkah berikut:

Di dekat bagian atas file, tambahkan baris berikut setelah baris cmake_minimum_required dan project:
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
Dalam perintah target_link_libraries, tambahkan games-memory-advice::memory_advice. Hal ini membuat Memory Advice API menjadi dependensi ke library native project dan menyertakannya dalam paket aplikasi akhir Anda. Update akan terlihat seperti berikut:
```
 target_link_libraries(
     your-native-lib

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

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

Mengonfigurasi file Java

Library native yang disertakan dengan Memory Advice API adalah libmemory_advice.so. Library ini adalah dependensi kompilasi untuk library bersama C/C++ milik aplikasi Anda, dan secara otomatis dimuat saat aplikasi memuat library bersamanya sendiri dengan fungsi System.loadlibrary().

Langkah ini opsional.

Temukan kode Java dalam project Anda yang memuat library native. Jika tidak ada, tambahkan. Kode harus terlihat mirip dengan System.loadLibrary("your-native-lib"), dan berada di blok static.

Tambahkan System.loadLibrary("memory_advice") di bagian System.loadLibrary("your-native-lib"). Update akan terlihat seperti berikut:

 static {
     System.loadLibrary("your-native-lib");
     // Note: loading libmemory_advice.so is optional.
     System.loadLibrary("memory_advice");
 }

Menggunakan library

Bagian ini menjelaskan cara menggunakan library ini.

Menambahkan file header

Sertakan file header library berikut dalam project Anda:

    #include <memory_advice/memory_advice.h>

Melakukan inisialisasi library

Anda perlu menginisialisasi library sekali saat aplikasi dimulai. Untuk melakukannya, tambahkan kode ini ke project Anda:

    MemoryAdvice_init(env, activity);

Parameter env dan activity adalah variabel JNIEnv* dan jobject, dan keduanya harus tersedia untuk library native. Setiap panggilan JNI ke library native Anda harus berisi variabel-variabel ini. Jika Anda menggunakan Library GameActivity, pastikan untuk melampirkan thread panggilan ke JavaVM sebelum memanggil fungsi MemoryAdvice_init.

Melakukan polling untuk status memori

Anda dapat mengambil status memori aplikasi dengan melakukan polling library pada interval pilihan Anda. Gunakan fungsi MemoryAdvice_getMemoryState setiap kali Anda perlu melakukan polling pada library:

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

Menyiapkan watcher

Anda juga dapat menyiapkan watcher dan mendaftarkan Memory Advice API, dan fungsi watcher Anda akan dipanggil saat status mendekati batas atau dalam keadaan kritis status memori (tetapi bukan untuk status oke). Misalnya, kode berikut membuat watcher dan meminta notifikasi Memory Advice API setiap 2 detik:

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

Langkah berikutnya

Baca ringkasan untuk referensi tambahan dan melaporkan masalah.