Pierwsze kroki z interfejsem Memory Advice API

Ten przewodnik opisuje, jak zintegrować wersję Jetpack interfejsu Memory Advice API z aplikacją za pomocą Android Studio.

Gry powinny korzystać z wersji interfejsu Memory Advice API zalecanej w danym środowisku kompilacji. W przypadku Android Studio zalecamy wersję Jetpack. Informacje o wersjach w innych środowiskach kompilacji, takich jak Android Game Development Extension (AGDE), znajdziesz w sekcji Dystrybucje.

Dodawanie biblioteki

W tej sekcji dowiesz się, jak dodać bibliotekę do projektu Android Studio (wtyczka Androida do obsługi Gradle).

Dodawanie zależności

Aby dodać bibliotekę do projektu w Android Studio, wykonaj te czynności:

  1. Włącz bibliotekę Android Jetpack na poziomie projektu gradle.properties). Plik zwykle znajduje się w katalogu głównym projektu:

      android.useAndroidX=true

  2. Otwórz plik build.gradle na poziomie modułu i dodaj do sekcji zależności ten kod:implementation W ten sposób zadeklarujesz w aplikacji zależności interfejsu Memory Advice API.

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

  3. Określ wersję NDK w bloku android:

     ndkVersion "23.1.7779620"

    Wybierz wersję NDK zgodną z interfejsem Memory Advice API. Listę obsługiwanych wersji NDK znajdziesz na stronie z informacjami o wersji Android Games Jetpack.

  4. Zadeklaruj dodatkowe flagi kompilacji dla CMake. Aby to zrobić, dodaj ten kod do bloku defaultConfig znajdującego się w bloku android:

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

  5. Włącz funkcję Prefab. W przypadku wtyczki Androida do obsługi Gradle(AGP) w wersji 4.1 lub nowszej dodaj ten kod do bloku android:

     buildFeatures {
    prefab true
 }

    Jeśli używasz AGP w wersji 4.0 lub starszej, instrukcje konfiguracji znajdziesz na stronie Prefab.

  6. Zapisz plik. Jeśli zobaczysz ten komunikat, kliknij przycisk Synchronizuj teraz, aby zaktualizować projekt:

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

Konfigurowanie CMake do kompilacji C/C++

Aby dodać do projektu pliki nagłówkowe i bibliotekę środowiska wykonawczego interfejsu Memory Advice API, otwórz główny plik CMakeLists.txt projektu. W panelu Project (Projekt) plik znajduje się w folderze app > src > main > cpp. Po otwarciu pliku wykonaj te czynności:

  1. U góry pliku, po wierszach cmake_minimum_required i project, dodaj ten wiersz:

     find_package(games-memory-advice REQUIRED CONFIG)

  2. W poleceniu target_link_libraries dodaj games-memory-advice::memory_advice. Dzięki temu interfejs Memory Advice API staje się zależnością biblioteki natywnej projektu i jest uwzględniany w końcowym pakiecie aplikacji. Aktualizacja powinna wyglądać podobnie do tej:

     target_link_libraries(
     your-native-lib

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

     #rest of the dependencies
     #...
 )

Konfigurowanie plików Java

Biblioteka natywna dołączona do interfejsu Memory Advice API to libmemory_advice.so. Jest to zależność kompilacji własnej biblioteki współdzielonej C/C++ aplikacji, która jest automatycznie wczytywana, gdy aplikacja wczytuje własną bibliotekę współdzieloną za pomocą funkcji System.loadlibrary().

Ten krok jest opcjonalny.

  1. Znajdź w projekcie kod Java, który wczytuje biblioteki natywne. Jeśli nie istnieje, dodaj ją. Kod powinien wyglądać podobnie do System.loadLibrary("your-native-lib") i znajdować się w bloku static.

  2. Dodaj System.loadLibrary("memory_advice") w sekcji System.loadLibrary("your-native-lib"). Aktualizacja powinna wyglądać podobnie do tej:

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

Korzystanie z biblioteki

Z tej sekcji dowiesz się, jak korzystać z biblioteki.

Dodaj pliki nagłówkowe

W projekcie uwzględnij ten plik nagłówkowy biblioteki:

    #include <memory_advice/memory_advice.h>

Inicjowanie biblioteki

Bibliotekę trzeba zainicjować raz po uruchomieniu aplikacji. Aby to zrobić, dodaj do projektu ten kod:

    MemoryAdvice_init(env, activity);

Parametry env i activity to zmienne JNIEnv* i jobject, które powinny być dostępne w bibliotece natywnej. Każde wywołanie JNI do biblioteki natywnej powinno zawierać te zmienne. Jeśli używasz biblioteki GameActivity, przed wywołaniem funkcji MemoryAdvice_init dołącz wątek wywołujący do JavaVM.

Sprawdzanie stanu pamięci

Stan pamięci aplikacji możesz odzyskać, odpytując bibliotekę w wybranym przez siebie odstępie czasu. Używaj funkcji MemoryAdvice_getMemoryState za każdym razem, gdy chcesz sprawdzić stan biblioteki:

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

Konfigurowanie obserwatora

Możesz też skonfigurować obserwatora i zarejestrować interfejs Memory Advice API. Funkcja obserwatora zostanie wywołana, gdy stan będzie zbliżać się do limitu lub osiągnie krytyczny stan pamięci (ale nie w przypadku stanu ok). Na przykład ten kod tworzy obserwatora i co 2 sekundy wysyła żądanie powiadomienia z interfejsu 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);

Co dalej

Więcej informacji znajdziesz w omówieniu, dodatkowych materiałach i informacjach o zgłaszaniu problemów.