In diesem Leitfaden wird beschrieben, wie du den Jetpack-Release der Memory Advice API mithilfe von Android Studio in deine App einbindest.
Für Spiele sollte die Memory Advice API-Version verwendet werden, die für ihre Build-Umgebung empfohlen wird. Für Android Studio empfehlen wir den Jetpack-Release. Informationen zu Releases für andere Build-Umgebungen, z. B. die Android Game Development Extension (AGDE), findest du unter Distributionen.
Bibliothek hinzufügen
In diesem Abschnitt wird beschrieben, wie Sie die Bibliothek Ihrem Android Studio-Projekt (Android Gradle-Plug-in) hinzufügen.
Abhängigkeiten hinzufügen
Führen Sie die folgenden Schritte aus, um die Bibliothek zu Ihrem Android Studio-Projekt hinzuzufügen:
Aktivieren Sie die Android Jetpack-Bibliothek auf Projektebene
gradle.properties
), befindet sich die Datei normalerweise im Stammverzeichnis Ihres Projekts:android.useAndroidX=true
Öffnen Sie die Datei
build.gradle
auf Modulebene und fügen Sie den folgendenimplementation
dem Abhängigkeitenblock hinzu. Dadurch werden die API-Abhängigkeiten für die Arbeitsspeicherempfehlung in Ihrer App deklariert.dependencies { implementation 'androidx.games:games-memory-advice:1.0.0-beta01' }
Geben Sie die NDK-Version im
android
-Block an:ndkVersion "23.1.7779620"
Wählen Sie eine Version des NDK aus, die mit der Memory Advice API kompatibel ist. Eine Liste der unterstützten NDK-Versionen ist auf der Seite zu den Android Games Jetpack-Releases verfügbar.
Deklarieren Sie zusätzliche Build-Flags für CMake. Fügen Sie dazu den folgenden Code in den
defaultConfig
-Block innerhalb desandroid
-Blocks ein:externalNativeBuild { cmake { cppFlags '-std=c++14' // c++_shared flavor is the only supported STL type. arguments "-DANDROID_STL=c++_shared" } }
Aktivieren Sie die Funktion Prefab. Fügen Sie für Android Gradle-Plug-in(AGP) 4.1 oder höher den folgenden Code in den
android
-Block ein:buildFeatures { prefab true }
Wenn Sie AGP 4.0 oder eine ältere Version verwenden, finden Sie eine Konfigurationsanleitung auf der Prefab-Seite.
Speichere die Datei. Wenn die folgende Meldung angezeigt wird, klicken Sie auf die Schaltfläche Sync Now (Jetzt synchronisieren), um Ihr Projekt zu aktualisieren:
Gradle files have changed since last project sync. A project sync may be necessary for the IDE to work properly.
CMake für C/C++ Build konfigurieren
Öffnen Sie die CMakeLists.txt
-Hauptdatei Ihres Projekts, um die Header-Dateien und die Laufzeitbibliothek für die Memory Advice API in Ihr Projekt einzufügen. Im Bereich Projekt befindet sich die Datei unter app > src > main > cpp. Führe nach dem Öffnen der Datei die folgenden Schritte aus:
Fügen Sie oben in der Datei nach den Zeilen
cmake_minimum_required
undproject
die folgende Zeile ein:find_package(games-memory-advice REQUIRED CONFIG)
Fügen Sie im Befehl
target_link_libraries
den Befehlgames-memory-advice::memory_advice
hinzu. Dadurch ist die Memory Advice API von der nativen Bibliothek Ihres Projekts abhängig und nimmt sie in Ihr endgültiges Anwendungspaket auf. Das Update sollte in etwa so aussehen:target_link_libraries( your-native-lib #link memory advice to the project games-memory-advice::memory_advice #rest of the dependencies #... )
Java-Dateien konfigurieren
Die native Bibliothek, die in der Memory Advice API enthalten ist, ist libmemory_advice.so
. Er ist eine Kompilierungsabhängigkeit für die eigene gemeinsam genutzte Bibliothek C/C++ Ihrer Anwendung. Sie wird automatisch geladen, wenn Ihre Anwendung ihre eigene gemeinsam genutzte Bibliothek mit der Funktion System.loadlibrary()
lädt.
Dieser Schritt ist optional.
Suchen Sie in Ihrem Projekt den Java-Code, über den die nativen Bibliotheken geladen werden. Ist dies nicht der Fall, fügen Sie sie hinzu. Der Code sollte ähnlich aussehen wie
System.loadLibrary("your-native-lib")
und befindet sich in einemstatic
-Block.Fügen Sie
System.loadLibrary("memory_advice")
unterSystem.loadLibrary("your-native-lib")
hinzu. Die Aktualisierung sollte in etwa so aussehen:static { System.loadLibrary("your-native-lib"); // Note: loading libmemory_advice.so is optional. System.loadLibrary("memory_advice"); }
Bibliothek verwenden
In diesem Abschnitt wird die Verwendung der Bibliothek beschrieben.
Headerdateien hinzufügen
Fügen Sie die folgende Bibliotheksheaderdatei in Ihr Projekt ein:
#include <memory_advice/memory_advice.h>
Bibliothek initialisieren
Du musst die Bibliothek beim Start der App einmal initialisieren. Fügen Sie dazu folgenden Code in Ihr Projekt ein:
MemoryAdvice_init(env, activity);
Die Parameter env
und activity
sind die Variablen JNIEnv*
und jobject
, die für Ihre native Bibliothek verfügbar sein sollten. Jeder JNI-Aufruf an Ihre native Bibliothek sollte diese Variablen enthalten. Wenn Sie die GameActivity-Bibliothek verwenden, müssen Sie den aufrufenden Thread an die JavaVM anhängen, bevor Sie die Funktion MemoryAdvice_init
aufrufen.
Arbeitsspeicherstatus abfragen
Sie können den Arbeitsspeicherstatus Ihrer Anwendung abrufen, indem Sie die Bibliothek im gewünschten Intervall abfragen. Verwenden Sie die Funktion MemoryAdvice_getMemoryState immer dann, wenn Sie die Bibliothek abfragen müssen:
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;
}
Watcher einrichten
Sie können auch einen Watcher einrichten und die Memory Advice API registrieren. Die Watcher-Funktion wird dann aufgerufen, wenn sich der Status entweder dem Limit oder dem kritischen Arbeitsspeicherstatus nähert (aber nicht für den Zustand „OK“). Mit dem folgenden Code wird beispielsweise ein Watcher erstellt und alle zwei Sekunden eine Memory Advice API-Benachrichtigung angefordert:
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);
Nächste Schritte
In der Übersicht finden Sie weitere Ressourcen und Probleme mit Berichten.