ממשקי 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.

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

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

ספריית C++‎

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

רישום

<android/log.h> מכיל ממשקי API לתיעוד ביומן logcat.

האפשרות הזו זמינה החל מרמת API 3.

ספרייה: liblog

מידע נוסף: רישום ביומן

נתוני מעקב

ממשק ה-API המקורי למעקב (native tracing 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 לקישור דינמי מגיע מהמכשיר, ותהיה לו הגרסה שפורסמה במכשיר הזה. באופן ספציפי, המשמעות היא שהכותרות שבהן השתמשתם בזמן ה-build לא תואמות לגרסה של zlib במכשיר, ולכן האזהרות הרגילות לגבי הנחות לגבי פרטי ההטמעה רלוונטיות במיוחד כאן. אנחנו לא מודעים לבעיות בממשק ה-API הציבורי, אבל פריסת המבנה (struct) במיוחד השתנתה עם הזמן, וסביר להניח שהיא תמשיך להשתנות. חשוב לזכור שממשק 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 וב-2.0.

רק מכשירי Android עם מעבד הגרפי הנדרש תומכים באופן מלא בגרסאות מתקדמות יותר של 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

Vulkan

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

לדוגמי קוד, אפשר לעיין בפרויקטים VulkanSamples ו-android-vulkan-tutorials של LunarG ב-GitHub.

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

האפשרות הזו זמינה החל מרמה 24 של API.

ספרייה: libvulkan

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

מפות סיביות (bitmap)

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

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

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

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

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

האפשרות הזו זמינה החל מרמת API 8.

ספרייה: libjnigraphics

מידע נוסף: הפניית API של Bitmap

Sync API

האפשרות הזו זמינה החל מרמת API 26.

ספרייה: libsync

מידע נוסף: הפניית API לסנכרון

מצלמה

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

האפשרות הזו זמינה החל מרמה 24 של API.

ספרייה: libcamera2ndk

מידע נוסף: מידע על Camera API

מדיה

libmediandk

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

ספרייה: libmediandk

מידע נוסף: הפניית Media API

OpenMAX AL

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

הכותרות הסטנדרטיות של 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

ממשקי API של Binder

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

ספרייה: libbinder_ndk

מקור: Binder

ממשקי API של מאגרי נתונים לחומרה

יש שני ממשקי API מקומיים שמאפשרים ליצור צינורות עיבוד נתונים משלכם לניהול מאגרים (buffers) בין תהליכים.

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

באמצעות JNI API (<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 ל-Android

Neural Networks API

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

האפשרות הזו זמינה החל מרמת API‏ 27.

ספרייה: libneuralnetworks

מדריך: מדריך בנושא רשתות נוירונים

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