איך מתחילים להשתמש ב-Memory Adwise API

במדריך הזה נסביר איך לשלב את מהדורת Jetpack של Memory Advantage API באפליקציה באמצעות Android Studio.

המשחקים צריכים להשתמש בגרסת Memory Advantage API שמומלצות לסביבת ה-build שלהם. ב-Android Studio, מומלץ שחרור ב-Jetpack. למידע על גרסאות לסביבות build אחרות: כמו Android Game Development Extension (תוסף פיתוח המשחקים ל-Android) (AGDE), מומלץ לעיין בקטע הפצות.

הוספת הספרייה

בקטע הזה נסביר איך להוסיף את הספרייה ל-Android Studio (Android Studio) פרויקט של Gradle Plugin).

מוסיפים את יחסי התלות

כדי להוסיף את הספרייה לפרויקט Android Studio, מבצעים את השלבים הבאים:

מפעילים את ספריית Jetpack ב-Android ברמת הפרויקט gradle.properties), בדרך כלל הקובץ ממוקם בתיקיית השורש של הפרויקט:
```
  android.useAndroidX=true
```
פותחים את הקובץ build.gradle ברמת המודול ומוסיפים את הפרטים הבאים implementation לבלוק של יחסי התלות. זהו הצהרה על ה-API של ייעוץ בזיכרון של יחסי התלות באפליקציה שלכם.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
מציינים את גרסת ה-NDK שבתוך הבלוק android:
```
 ndkVersion "23.1.7779620"
```
חשוב לבחור גרסה של ה-NDK שתואמת ל-Memory Ad וכך API. רשימה של גרסאות NDK נתמכות זמינה בדף 'מהדורת Jetpack של משחקים ל-Android'.

הצהרה על דגלי build נוספים ל-CMake. כדי לעשות את זה, מוסיפים את הקוד הבא בלוק defaultConfig שנמצא בתוך הבלוק android:

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

מפעילים את התכונה Prefab. ב-Android Gradle Plugin(AGP) 4.1 ואילך, צריך להוסיף את הקוד הבא חסימת android:
```
 buildFeatures {
    prefab true
 }
```
אם אתם משתמשים ב-AGP 4.0 או גרסאות ישנות יותר, כדאי לעיין דף מקדים לקבלת הוראות הגדרה.
שומרים את הקובץ. אם ההודעה הבאה מופיעה, לוחצים על סנכרון עכשיו. לחצן לעדכון הפרויקט:
```
  Gradle files have changed since last project sync. A project sync may be
  necessary for the IDE to work properly.
```

הגדרת CMake ל-C/C++ build

כדי להוסיף את קובצי הכותרות ואת ספריית זמן הריצה ל-Memory Advantage API בפרויקט, פותחים את קובץ CMakeLists.txt הראשי של הפרויקט. ב בחלונית Project, הקובץ נמצא ב-app > מקור > ראשי > cpp. לאחר הפתיחה של מבצעים את השלבים הבאים:

ליד החלק העליון של הקובץ, מוסיפים את השורה הבאה אחרי שורות cmake_minimum_required ו-project:
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
בפקודה target_link_libraries, מוסיפים games-memory-advice::memory_advice. הפעולה הזו הופכת את Memory Advantage API תלות בספרייה המקורית של הפרויקט וכוללת אותה בחבילה הסופית של האפליקציה. העדכון אמור להיראות כך:
```
 target_link_libraries(
     your-native-lib

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

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

מגדירים את קובצי ה-Java

ספריית ה-Native שכלולה ב-Memory Adwise API היא libmemory_advice.so זו תלות בהידור של האפליקציה ספרייה משותפת מסוג C/C++ ונטען באופן אוטומטי כשהאפליקציה שלך נטענת משותפת עם הפונקציה System.loadlibrary().

השלב הזה הוא אופציונלי.

מאתרים את קוד Java בפרויקט שטוען את ספריות ה-Native. אם לא קיים, הוסף אותו. הקוד אמור להיראות דומה ל-System.loadLibrary("your-native-lib"), והוא נמצאים בבלוק של static.

הוספה של System.loadLibrary("memory_advice") מתחת System.loadLibrary("your-native-lib"). העדכון אמור להיראות כמו הבאים:

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

שימוש בספרייה

בקטע הזה נסביר איך להשתמש בספרייה.

הוספת קובצי הכותרות

כוללים בפרויקט את קובץ כותרת הספרייה הבא:

    #include <memory_advice/memory_advice.h>

הפעלת הספרייה

תצטרכו לאתחל את הספרייה פעם אחת כשהאפליקציה מופעלת. כדי לעשות את זה, מוסיפים את הקוד לפרויקט:

    MemoryAdvice_init(env, activity);

הפרמטרים env ו-activity הם המשתנים JNIEnv* ו-jobject שאמור להיות זמין בספריית המקור שלכם. כל קריאה של JNI ל-Native מכילה את המשתנים האלה. אם משתמשים ספריית GameActivity, להקפיד צירוף ה-thread של הקריאה ל-JavaVM לפני קריאה לפונקציה MemoryAdvice_init.

סקר על מצב הזיכרון

ניתן לאחזר את מצב הזיכרון של האפליקציה על ידי עריכת סקרים בספרייה ב במרווח הזמן הרצוי לך. משתמשים ב MemoryAdvision_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 Advantage API, והפונקציה של השעון תיקרא כשהמצב מתקרב למגבלה או מצב הזיכרון (אבל לא למצב 'תקין'). לדוגמה, הקוד הבא יוצר שומר (watcher) ומבקש התראה של Memory Advantage API כל 2 שניות:

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

השלב הבא

אפשר לעיין בסקירה הכללית בנושא מקורות מידע נוספים ובעיות בדיווח.