Pierwsze kroki z interfejsem Memory Advice API

Z tego przewodnika dowiesz się, jak zintegrować wersję Jetpacka interfejsu Memory Advice API z aplikacją za pomocą Android Studio.

Gry powinny używać wersji Memory Advice API, która jest zalecana dla ich środowiska kompilacji. W przypadku Android Studio polecamy wersję Jetpacka. Informacje o wersjach dla innych środowisk kompilacji, takich jak Android Game Development Extension (AGDE), znajdziesz w sekcji Dystrybucja.

Dodaj bibliotekę

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

Dodaj zależności

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

Włącz bibliotekę Androida Jetpack na poziomie projektu gradle.properties). Plik zwykle znajduje się w katalogu głównym projektu:
```
  android.useAndroidX=true
```
Otwórz plik build.gradle na poziomie modułu i dodaj do sekcji zależności ten fragment implementation. Deklaruje to zależności interfejsu API porad dotyczących pamięci w aplikacji.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
Określ wersję NDK w bloku android:
```
 ndkVersion "23.1.7779620"
```
Pamiętaj, aby wybrać wersję pakietu NDK zgodną z interfejsem Memory Advice API. Lista obsługiwanych wersji NDK jest dostępna na stronie Wydania gier na Androida Jetpack.

Zadeklaruj dodatkowe flagi kompilacji dla CMake. Aby to zrobić, dodaj ten kod do bloku defaultConfig, który znajduje się wewnątrz bloku android:

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

Włącz funkcję Prefab. W przypadku wtyczki Androida do obsługi Gradle w wersji 4.1 lub nowszej dodaj do bloku android ten kod:
```
 buildFeatures {
    prefab true
 }
```
Jeśli korzystasz z AGP w wersji 4.0 lub starszej, instrukcje konfiguracji znajdziesz na stronie Prefab.

Zapisz plik. Jeśli pojawi się 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.

Skonfiguruj CMake do kompilacji C/C++

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

Na początku pliku dodaj ten wiersz po wierszach cmake_minimum_required i project:
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
W poleceniu target_link_libraries dodaj games-memory-advice::memory_advice. To sprawia, że interfejs Memory Advice API jest zależność od biblioteki natywnej Twojego projektu i umieszcza ją w ostatecznym pakiecie aplikacji. Aktualizacja powinna wyglądać mniej więcej tak:
```
 target_link_libraries(
     your-native-lib

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

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

Skonfiguruj pliki Java

Biblioteka natywna zawarta w interfejsie Memory Advice API to libmemory_advice.so. Jest to zależność kompilacyjna dla biblioteki udostępnionej C/C++ Twojej aplikacji. Jest automatycznie wczytywana, gdy aplikacja wczytuje własną bibliotekę udostępnianą za pomocą funkcji System.loadlibrary().

Ten krok jest opcjonalny.

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

Dodaj System.loadLibrary("memory_advice") w sekcji System.loadLibrary("your-native-lib"). Aktualizacja powinna wyglądać mniej więcej tak:

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

Korzystanie z biblioteki

W tej sekcji opisano, jak korzystać z biblioteki.

Dodaj pliki nagłówka

Dołącz do projektu ten plik nagłówka biblioteki:

    #include <memory_advice/memory_advice.h>

Inicjowanie biblioteki

Musisz zainicjować bibliotekę raz podczas uruchamiania 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 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 maszyny wirtualnej JavaVM.

Sonda dotycząca stanu pamięci

Stan pamięci aplikacji możesz pobrać, przeprowadzając odpytywanie biblioteki z wybranym interwałem. Jeśli musisz przeprowadzić sondowanie biblioteki, użyj funkcji 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;
    }

Skonfiguruj obserwatora

Możesz też skonfigurować obserwację i zarejestrować interfejs Memory Advice API. Funkcja obserwacyjna będzie wywoływana, gdy stan zbliża się do limitu lub krytyczny stan pamięci (ale nie dla stanu OK). Na przykład ten kod tworzy obserwatora i żąda powiadomienia do interfejsu Memory Advice API co 2 sekundy:

    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

W omówieniu dodatkowych materiałów i problemów z raportowaniem dowiesz się.