ממשקי API מקומיים

בדף הזה מובאת סקירה כללית של הספריות שכלולות ב-NDK, עם קישורים לחלקים הרלוונטיים בהפניה ל-NDK API, ולמדריכים שקיימים.

שימוש בממשקי API מקוריים

כדי להשתמש בספרייה ש-NDK מספק, צריך לבצע שני שלבים:

  1. מגדירים למערכת ה-build לקשר לספרייה.

    • אם אתם משתמשים ב-ndk-build: מוסיפים את הספרייה אל LOCAL_LDLIBS בקובץ Android.mk. שימו לב שאתם מסירים את ה-lib המוביל ואומרים -l במקום. לדוגמה, כדי לקשר ל-libfoo ול-libbar, כותבים: makefile LOCAL_LDLIBS := -lfoo -lbar

      מידע נוסף על LOCAL_LDLIBS זמין במסמכי התיעוד של Android.mk.

    • אם אתם משתמשים ב-CMake: פועלים לפי ההוראות במאמר הוספת ממשקי NDK API בתיעוד של Studio.

  2. #include הכותרות המתאימות מהקוד.

שימו לב שאי אפשר לקרוא ל-API חדש יותר מ-minSdkVersion של האפליקציה כברירת מחדל, ובמקום זאת צריך להשתמש בו באמצעות dlopen() ו-dlsym(). לגישה פשוטה יותר, אפשר לעיין במאמר שימוש בממשקי API חדשים יותר.

Core C/C++

ספריית C

כותרות הספרייה הרגילות של C11, כמו <stdlib.h> ו-<stdio.h>, זמינות כרגיל.

שימו לב שב-Android, בניגוד ל-Linux, אין ספריות נפרדות של libpthread או librt. הפונקציונליות הזו נכללת ישירות ב-libc, ולא צריך לקשר אותה באופן מפורש.

יש ספרייה נפרדת libm לפונקציות מתמטיות (בהתאם לשיטה המקובלת ב-Unix), אבל כמו libc, היא מקושרת אוטומטית על ידי מערכות ה-build.

הפונקציונליות של Dynamic linker ב-<dlfcn.h>, כמו dlopen(3)‎ ו-dlsym(3)‎, זמינה, אבל צריך לקשר באופן מפורש ל-libdl.

ספרייה: libc / libm / libdl

ספריית C++‎

יש תמיכה ב-C++17. מידע נוסף על התמיכה בספריית C++ זמין במאמר בנושא תמיכה בספריית C++.

רישום

‫<android/log.h> מכיל ממשקי API לרישום ב-logcat.

זמין מרמת API‏ 3.

ספרייה: liblog

הפניה: רישום ביומן

נתוני מעקב

ממשק ה-API המקורי למעקב <android/trace.h> מספק את המקבילה המקורית למחלקה android.os.Trace בשפת התכנות Java. ‫API הזה מאפשר לכם לעקוב אחרי יחידות עבודה עם שמות בקוד שלכם על ידי כתיבת אירועי מעקב למאגר המערכת של המעקב. לאחר מכן תוכלו לאסוף ולנתח את אירועי המעקב באמצעות כלי Systrace.

זמין החל מרמת API‏ 23.

ספרייה: libandroid

מדריך: מעקב מקורי

דחיסת zlib

אפשר להשתמש בספריית הדחיסה Zlib על ידי הכללת <zlib.h> וקישור ל-libz.

ה-NDK תמיד כולל את קובצי הכותרות האחרונים של zlib בזמן השחרור, והספרייה libz.a שכלולה ב-NDK לקישור סטטי היא תמיד אותה גרסה, אבל הספרייה libz.so לקישור דינמי מגיעה מהמכשיר, והיא הגרסה שפורסמה במכשיר. במילים אחרות, הכותרות שיצרתם לא תואמות לגרסה של zlib במכשיר, ולכן האזהרות הרגילות מפני הסתמכות על פרטי ההטמעה תקפות במיוחד במקרה הזה. לא ידוע לנו על בעיות ב-API הציבורי, אבל פריסת המבנה השתנתה במיוחד לאורך זמן, וכנראה שהיא תמשיך להשתנות. חשוב לזכור שממשקי API חדשים בגרסאות מאוחרות יותר של zlib לא יהיו זמינים בגרסאות של מערכת ההפעלה שקדמו ל-API. אפשר להימנע מכל הבעיות האלה (אבל זה יגדיל את גודל ה-APK) אם תמיד משתמשים ב-libz.a הסטטי במקום ב-libz.so.

זמין מגרסת API 3 (אבל כדאי לעיין בהערה שלמעלה).

ספרייה: libz

גרפיקה

‫OpenGL ES 1.0 - 3.2

הכותרות הרגילות של OpenGL ES 1.x‏ (<GLES/gl.h> ו-<GLES/glext.h>), של 2.0‏ (<GLES2/gl2.h> ו-<GLES2/gl2ext.h>), של 3.0‏ (<GLES3/gl3.h> ו-<GLES3/gl3ext.h>), של 3.1‏ (<GLES3/gl31.h> ו-<GLES3/gl3ext.h>) ושל 3.2‏ (<GLES3/gl32.h> ו-<GLES3/gl3ext.h>) מכילות את ההצהרות שנדרשות ל-OpenGL ES.

כדי להשתמש ב-OpenGL ES 1.x, צריך לקשר את המודול המקורי ל-libGLESv1_CM.

כדי להשתמש ב-OpenGL ES 2.0, צריך לקשר את המודול המקורי ל-libGLESv2.

כדי להשתמש ב-OpenGL ES 3.x, מקשרים את המודול המקורי ל-libGLESv3.

כל המכשירים מבוססי Android תומכים ב-OpenGL ES 1.0 וב-OpenGL ES 2.0.

רק מכשירי Android עם GPU מתאים תומכים באופן מלא בגרסאות מאוחרות יותר של OpenGL ES, אבל הספריות קיימות בכל המכשירים שתומכים ברמת ה-API שבה הן הוצגו. אפשר לקשר בבטחה לספריות, אבל אפליקציה צריכה לשלוח שאילתה למחרוזת הגרסה ולמחרוזת התוסף של OpenGL ES כדי לקבוע אם המכשיר הנוכחי תומך בתכונות שהיא צריכה. מידע על אופן הביצוע של השאילתה הזו זמין בתיאור של glGetString() במפרט OpenGL.

בנוסף, צריך להוסיף תג <uses-feature> לקובץ המניפסט כדי לציין את הגרסה של OpenGL ES שנדרשת.

‫OpenGL ES 1.0 זמין החל מרמת API‏ 4.

‫OpenGL ES 2.0 זמין החל מרמת API‏ 5.

‫OpenGL ES 3.0 זמין החל מרמת API‏ 18.

‫OpenGL ES 3.1 זמין החל מרמת API‏ 21.

‫OpenGL ES 3.2 זמין החל מרמת API‏ 24.

EGL

‫EGL מספקת ממשק פלטפורמה מקורי באמצעות הכותרות <EGL/egl.h> ו-<EGL/eglext.h> להקצאה ולניהול של הקשרים והמשטחים של OpenGL ES.

הספרייה EGL מאפשרת לכם לבצע את הפעולות הבאות מקוד מקורי:

  • הצגת רשימה של הגדרות EGL נתמכות.
  • הקצאה ושחרור של משטחי OpenGL ES.
  • יצירה והרס של הקשרים של OpenGL ES.
  • החלפה או היפוך של משטחים.

רמת API‏ 24 הוסיפה תמיכה בתוספים EGL_KHR_mutable_render_buffer,‏ ANDROID_create_native_client_buffer ו-ANDROID_front_buffer_auto_refresh.

זמין מגרסת API‏ 9.

ספרייה: libEGL

מדריך: EGL Native Platform Interface

Vulkan

‫Vulkan הוא API חוצה פלטפורמות עם תקורה נמוכה, שמאפשר עיבוד גרפיקה תלת-ממדית בביצועים גבוהים. ‫Vulkan הוא תקן פתוח שמתחזקת קבוצת Khronos. קובץ הכותרת <vulkan/vulkan.h> הרגיל מכיל את ההצהרות שדרושות לביצוע קריאות להצגת Vulkan מהקוד.

דוגמאות לקוד זמינות בפרויקטים LunarG VulkanSamples ו- android-vulkan-tutorials ב-GitHub.

ספריית Vulkan קיימת בכל המכשירים שתומכים ברמת API‏ 24 ומעלה, אבל האפליקציות צריכות לבדוק בזמן הריצה אם יש תמיכה בחומרה של GPU. מכשירים שלא תומכים ב-Vulkan יחזירו אפס מכשירים מ-vkEnumeratePhysicalDevices.

זמין מרמת API‏ 24.

ספרייה: libvulkan

מדריך: מדריך ל-Vulkan Graphics API

מפות סיביות

ספריית libjnigraphics חושפת API שמאפשר גישה למאגרי הפיקסלים של אובייקטים של Java Bitmap. תהליך העבודה הוא כזה:

  1. מתקשרים אל AndroidBitmap_getInfo() כדי לאחזר מידע, כמו רוחב וגובה, לגבי נקודת אחיזה נתונה של מפת סיביות.

  2. מתקשרים אל AndroidBitmap_lockPixels() כדי לנעול את מאגר הפיקסלים ולאחזר מצביע אליו. כך מוודאים שהפיקסלים לא יזוזו עד שהאפליקציה תפעיל את AndroidBitmap_unlockPixels().

  3. משנים את מאגר הפיקסלים בהתאם לפורמט הפיקסלים, לרוחב ולמאפיינים אחרים.

  4. מתקשרים אל AndroidBitmap_unlockPixels() כדי לבטל את הנעילה של המאגר.

זמין מרמת API‏ 8.

ספרייה: libjnigraphics

חומר עזר: הפניית API של Bitmap

Sync API

זמין החל מרמת API‏ 26.

ספרייה: libsync

הפניה: מאמר עזרה על Sync API

מצלמה

ממשקי ה-API המקוריים של המצלמה מבצעים צילום ועיבוד של תמונות ברמת פירוט גבוהה. בשונה מ-Java camera2 API, ‏ native camera API לא תומך בהטמעות של camera HAL 1.0 שהוצאו משימוש (כלומר, רשימת המצלמות הזמינות ב-native camera API לא תכלול מכשירי מצלמה עם רמת החומרה LEGACY).

זמין מרמת API‏ 24.

ספרייה: libcamera2ndk

חומר עזר: הפניית API של המצלמה

מדיה

libmediandk

ממשקי Media APIs מספקים ממשקים מקוריים ברמה נמוכה, בדומה ל-MediaExtractor, MediaCodec ולממשקי Java APIs אחרים שקשורים אליהם.

ספרייה: libmediandk

הפניה: Media API reference

OpenMAX AL

הטיפול המקורי במולטימדיה ב-Android מבוסס על Khronos Group OpenMAX AL 1.0.1 API.

הכותרות הרגילות של OpenMAX AL‏ <OMXAL/OpenMAXAL.h> ו-<OMXAL/OpenMAXAL_Platform.h> מכילות את ההצהרות שנדרשות לביצוע פלט מולטימדיה מהצד המקורי של Android.

הפצת ה-NDK של OpenMAX AL מספקת גם תוספים ספציפיים ל-Android. מידע על התוספים האלה מופיע בתגובות בקובץ <OMXAL/OpenMAXAL_Android.h>.

זמין החל מרמת API‏ 14.

ספרייה: libOpenMAXAL

ממשקי API של אפליקציות מקוריות ל-Android

מידע נוסף זמין במאמרי העזרה בנושא Android NDK API.

ממשקי ה-API כוללים:

ספרייה: libandroid

ספרייה: libnativewindow כדי ליהנות מהפונקציונליות העדכנית של חלון מקורי

הפניה מלאה: Android NDK API reference

Binder APIs

ממשקי ה-API של Binder מאפשרים ליצור ערוצי תקשורת בין תהליכים. זוהי הטמעה ברמה נמוכה של תקשורת בין תהליכים (IPC) ב-Android. כשיש אפשרות כזו, כדאי להשתמש ברכיבים ברמה גבוהה יותר. עם זאת, הספרייה הזו זמינה לתרחישי שימוש מתקדמים.

ספרייה: libbinder_ndk

הפניה: Binder

Hardware Buffer APIs

יש שני ממשקי API מותאמים שמאפשרים ליצור צינורות משלכם לניהול חוצץ בין תהליכים.

‫API של מאגר חומרה מקורי <android/hardware_buffer.h> מאפשר להקצות מאגרים ישירות כדי ליצור צינורות משלכם לניהול מאגרים בין תהליכים. אפשר להקצות AHardwareBuffer ולהשתמש בו כדי לקבל משאב מסוג EGLClientBuffer באמצעות התוסף eglGetNativeClientBufferANDROID. אפשר להעביר את המאגר הזה אל eglCreateImageKHR כדי ליצור משאב מסוג EGLImage, שאפשר לקשר אותו לטקסטורה באמצעות glEGLImageTargetTexture2DOES במכשירים נתמכים. האפשרות הזו יכולה להיות שימושית ליצירת טקסטורות שאפשר לשתף בין תהליכים.

ממשק ה-API המקורי של JNI (<android/hardware_buffer_jni.h>) מאפשר לקבל אובייקט HardwareBuffer, שהוא Parcelable ולכן אפשר להעביר אותו בין שני תהליכים שונים. כך האפליקציה מקבלת יכולות דומות לאלה של SurfaceFlinger, כמו יצירת תור משלכם של מאגרי נתונים זמניים בין תהליכים בלי לגשת לממשקי API פנימיים של Android.

אודיו

AAudio

‫AAudio הוא ה-API המקורי לאודיו שנתמך כרגע. הוא החליף את OpenSL ES, ומספק תמיכה טובה יותר באפליקציות אודיו עם ביצועים גבוהים שדורשות אודיו עם השהיה נמוכה.

זמין החל מרמת API‏ 26.

ספרייה: libaaudio

מדריך: מדריך בנושא AAudio API

חומר עזר: AAudio API reference

OpenSL ES

‫OpenSL ES הוא עוד API מקורי של אודיו שנתמך גם הוא, אבל כדאי לעיין בהערה במדריך שלמטה.

זמין מגרסת API‏ 9. ב-API ברמה 14 נוספה תמיכה ב-PCM.

ספרייה: libOpenSLES

מדריך: OpenSL ES for Android guide

Neural Networks API

ה-Neural Networks API‏ (NNAPI) מספק לאפליקציות שיפור מהירות באמצעות חומרה לפעולות של למידת מכונה במכשיר. ה-API תומך ביצירה, בהידור ובביצוע של מודלים במכשיר. בדרך כלל אפליקציות לא משתמשות ב-NNAPI ישירות, אלא בספריות, במסגרות ובכלים של למידת מכונה שמאפשרים למפתחים לאמן את המודלים שלהם ולפרוס אותם במכשירי Android.

זמין החל מרמת API‏ 27.

ספרייה: libneuralnetworks

מדריך: מדריך לרשתות נוירונים

מקור מידע: הפניית Neural Networks API