واجهات برمجة التطبيقات الأصلية

تقدّم هذه الصفحة نظرة عامة على المكتبات المضمّنة في NDK، مع روابط إلى الأجزاء ذات الصلة من مرجع واجهة برمجة التطبيقات NDK، والأدلة في أماكن وجودها.

استخدام واجهات برمجة التطبيقات الأصلية

هناك خطوتان لاستخدام مكتبة يوفرها NDK:

  1. اطلب من نظام التصميم الربط بالمكتبة.

    • في حال استخدام ndk-build: يمكنك إضافة المكتبة إلى LOCAL_LDLIBS في Android.mk. يُرجى العلم أنّه تتم إزالة علامة lib البادئة وقول -l بدلاً من ذلك. على سبيل المثال، للربط بين libfoo وlibbar، يمكنك كتابة: makefile LOCAL_LDLIBS := -lfoo -lbar

      للحصول على مزيد من المعلومات حول LOCAL_LDLIBS، يمكنك الاطّلاع على مستندات مستندات Android.mk.

    • إذا كنت تستخدم أداة CMake: يمكنك اتّباع التعليمات الواردة في مستندات إضافة واجهات برمجة تطبيقات NDK في Studio.

  2. #include العناوين المناسبة من الرمز الخاص بك.

تجدر الإشارة إلى أنّ واجهات برمجة التطبيقات الأحدث من minSdkVersion في تطبيقك لن تكون قابلة للاستدعاء بشكل تلقائي، وعليك استخدامها من خلال dlopen() وdlsym() بدلاً من ذلك. للتعرّف على طريقة أسهل، يمكنك الاطّلاع على استخدام واجهات برمجة تطبيقات أحدث.

Core C/C++

مكتبة C

وتتوفر عناوين مكتبة C11 العادية، مثل <stdlib.h> و<stdio.h>، كالمعتاد.

يُرجى العِلم أنّه لا تتوفّر مكتبات libpthread أو librt منفصلة على نظام التشغيل Android، على عكس Linux. ويتم تضمين هذه الوظيفة مباشرةً في libc التي لا تحتاج إلى الربط المباشر بها.

تتوفّر libm منفصلة للدوال الرياضية (باتّباع نمط Unix المعتاد)، ولكن يتم ربط هذه السمة تلقائيًا من خلال أنظمة التصميم، مثل libc.

تتوفّر وظيفة الرابط الديناميكي في <dlfcn.h>، مثل dlopen(3) وdlsym(3)، ولكن يجب عليك الربط الصريح بـ libdl.

المكتبة: libc / libm / libdl

مكتبة C++

يتوفر دعم C++17. للحصول على مزيد من المعلومات حول دعم مكتبة C++ ، راجع دعم مكتبة C++.

التسجيل

يحتوي <android/log.h> على واجهات برمجة تطبيقات لتسجيل الدخول إلى Logcat.

تتوفّر هذه الميزة منذ المستوى 3 لواجهة برمجة التطبيقات.

المكتبة: liblog

المرجع: التسجيل

تتبُّع

توفّر واجهة برمجة تطبيقات التتبّع الأصلية <android/trace.h> المكافئة الأصلية للفئة android.os.Trace في لغة برمجة Java. تتيح لك واجهة برمجة التطبيقات هذه تتبُّع وحدات العمل المُعنونة في الرمز البرمجي من خلال كتابة أحداث التتبُّع في المخزن المؤقت للنظام. يمكنك بعد ذلك جمع أحداث التتبُّع وتحليلها باستخدام أداة النظام (Systrace).

تتوفّر هذه الميزة بدءًا من المستوى 23 لواجهة برمجة التطبيقات.

المكتبة: libandroid

دليل: التتبّع المحلي

ضغط zlib

يمكنك استخدام مكتبة ضغط Zlib من خلال تضمين <zlib.h> وربطها بـ libz.

يتضمّن NDK دائمًا أحدث ملفات عناوين zlib في وقت إصداره، كما أن libz.a المضمّن في NDK للربط الثابت هو دائمًا الإصدار نفسه، ولكن libz.so للربط الديناميكي يأتي من الجهاز، ويكون أي نسخة تم إصدارها على هذا الجهاز. ويعني هذا على وجه الخصوص أنّ العناوين التي أنشأتها لا تتطابق مع إصدار zlib على الجهاز، وبالتالي تكون التحذيرات المعتادة ضد وضع افتراضات حول تفاصيل التنفيذ صالحة هنا بشكل خاص. ليس على علم بأي مشاكل تتعلق بواجهة برمجة التطبيقات العامة، ولكن تنسيق البنية على وجه الخصوص تغيّر بمرور الوقت، وسنستمر على الأرجح في ذلك. يُرجى العِلم أنّ واجهة برمجة التطبيقات الجديدة في إصدارات zlib اللاحقة لن تكون متاحة بوضوح في إصدارات أنظمة التشغيل التي تسبق واجهة برمجة التطبيقات. من الممكن تجنُّب كل هذه المشاكل (على حساب زيادة حجم حزمة APK) دائمًا عن طريق استخدام العلامة libz.a الثابتة بدلاً من libz.so.

تتوفّر هذه الميزة بدءًا من المستوى 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 بشكل كامل، ولكن المكتبات متاحة على جميع الأجهزة المتوافقة مع مستوى واجهة برمجة التطبيقات في المكان الذي عُرضت فيه. يمكن الربط بالمكتبات بشكل آمن، ولكن يجب أن يستفسر التطبيق عن سلسلة إصدار OpenGL ES وسلسلة الإضافة لتحديد ما إذا كان الجهاز الحالي يوفّر الميزات التي يحتاج إليها. للحصول على معلومات حول كيفية إجراء طلب البحث هذا، يمكنك الاطّلاع على وصف glGetString() في مواصفات OpenGL.

بالإضافة إلى ذلك، يجب وضع علامة <uses-feature> في ملف البيان للإشارة إلى إصدار OpenGL ES المطلوب.

يتوفر OpenGL ES 1.0 منذ المستوى 4 لواجهة برمجة التطبيقات.

يتوفر OpenGL ES 2.0 منذ المستوى 5 من واجهة برمجة التطبيقات.

يتوفر OpenGL ES 3.0 منذ المستوى 18 من واجهة برمجة التطبيقات.

يتوفّر OpenGL ES 3.1 منذ المستوى 21 من واجهة برمجة التطبيقات.

يتوفّر OpenGL ES 3.2 منذ المستوى 24 لواجهة برمجة التطبيقات.

هبوط الطائرات

توفّر EGL واجهة نظام أساسي أصلي من خلال العنوانَين <EGL/egl.h> و<EGL/eglext.h> لتخصيص وإدارة سياقات وواجهات OpenGL ES.

يتيح لك EGL تنفيذ العمليات التالية باستخدام الرمز الأصلي:

  • أدرِج إعدادات EGL المتوافقة.
  • تخصيص مساحات عرض OpenGL ES وإصدارها
  • إنشاء سياقات OpenGL ES وإتلافها
  • بدِّل الأسطح أو قلبها.

أتاح المستوى 24 من واجهة برمجة التطبيقات استخدام الإضافات EGL_KHR_mutable_render_buffer وANDROID_create_native_client_buffer وANDROID_front_buffer_auto_refresh.

تتوفّر هذه الميزة منذ المستوى 9 لواجهة برمجة التطبيقات.

المكتبة: libEGL

دليل: واجهة EGL Native Platform

فولكان

Vulkan هي واجهة برمجة تطبيقات منخفضة التكلفة تعمل على عدّة منصات لعرض الرسومات الثلاثية الأبعاد عالية الأداء. Vulkan هو معيار مفتوح تحتفظ به مجموعة Khronos Group. يحتوي ملف عنوان <vulkan/vulkan.h> العادي على الإعلانات المطلوبة لإجراء استدعاءات عرض Vulkan من التعليمات البرمجية.

للاطّلاع على عيّنات التعليمات البرمجية، يُرجى الاطّلاع على مشروعَي VulkanSamples وandroid-vulkan-Tutorials على GitHub.

تتوفّر مكتبة Vulkan على جميع الأجهزة التي تدعم المستوى 24 من واجهة برمجة التطبيقات أو المستويات الأحدث، ولكن يجب أن تتحقّق التطبيقات في وقت التشغيل من توفّر الدعم اللازم لأجهزة وحدة معالجة الرسومات. لن تعرض الأجهزة غير المتوافقة مع Vulkan أي أجهزة من vkEnumeratePhysicalDevices.

تتوفّر هذه الميزة بدءًا من المستوى 24 لواجهة برمجة التطبيقات.

المكتبة: libvulkan

الدليل: دليل Vulkan graphics API

صور نقطية

تعرض مكتبة libjnigraphics واجهة برمجة التطبيقات التي تسمح بالوصول إلى المخازن المؤقتة لوحدات البكسل لكائنات Java Bitmap. في ما يلي خطوات سير العمل:

  1. يمكنك طلب الدالة AndroidBitmap_getInfo() لاسترداد معلومات، مثل العرض والارتفاع، حول مؤشر صورة نقطية معيّن.

  2. يمكنك طلب AndroidBitmap_lockPixels() لقفل المخزن المؤقت للبكسل واسترداد مؤشر إليه. ويضمن ذلك عدم تحرّك وحدات البكسل إلى أن يستدعي التطبيق الرمز AndroidBitmap_unlockPixels().

  3. عدِّل المخزن المؤقت للبكسل بما يتناسب مع تنسيق البكسل وعرضه وخصائصه الأخرى.

  4. يمكنك الاتصال بـ AndroidBitmap_unlockPixels() لفتح قفل المخزن المؤقت.

تتوفّر هذه الميزة منذ المستوى 8 من واجهة برمجة التطبيقات.

المكتبة: libjnigraphics

المرجع: مرجع واجهة برمجة تطبيقات Bitmap

واجهة برمجة تطبيقات المزامنة

تتوفّر هذه الميزة بدءًا من المستوى 26 لواجهة برمجة التطبيقات.

المكتبة: libsync

المرجع: مرجع Sync API

الكاميرا

تتيح واجهات برمجة التطبيقات للكاميرا الأصلية التقاط صور ومعالجتها بدقة أكبر. على عكس واجهة برمجة التطبيقات Java camera2 API، لا تتيح واجهة برمجة التطبيقات للكاميرا الأصلية عمليات تنفيذ HAL 1.0 للكاميرا المتوقّفة (أي أنّ قائمة الكاميرات المتاحة في واجهة برمجة تطبيقات الكاميرا الأصلية لن تتضمّن أجهزة الكاميرا التي تحتوي على مستوى جهاز LEGACY).

تتوفّر هذه الميزة بدءًا من المستوى 24 لواجهة برمجة التطبيقات.

المكتبة: libcamera2ndk

المرجع: مرجع واجهة برمجة التطبيقات للكاميرا

الوسائط

ليبميدينك

توفر واجهات برمجة تطبيقات الوسائط واجهات أصلية منخفضة المستوى تشبه MediaExtractor وMediaCodec وواجهات برمجة تطبيقات Java الأخرى ذات الصلة.

المكتبة: libmediandk

المرجع: مرجع Media API

OpenMAX AL

تعتمد معالجة الوسائط المتعددة الأصلية في Android على واجهة برمجة التطبيقات Hronos Group OpenMAX AL 1.0.1.

يتضمّن عنوانا OpenMAX AL العاديان <OMXAL/OpenMAXAL.h> و<OMXAL/OpenMAXAL_Platform.h> البيانات اللازمة لتنفيذ إخراج وسائط متعددة من الإصدار الأصلي من Android.

يوفر توزيع NDK من OpenMAX AL أيضًا إضافات خاصة بنظام Android. للحصول على معلومات حول هذه الإضافات، يمكنك الاطّلاع على التعليقات في "<OMXAL/OpenMAXAL_Android.h>".

تتوفّر هذه الميزة بدءًا من المستوى 14 لواجهة برمجة التطبيقات.

المكتبة: libOpenMAXAL

واجهات برمجة التطبيقات لتطبيقات Android الأصلية

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات مرجع واجهة برمجة التطبيقات Android NDK API.

تشمل واجهات برمجة التطبيقات ما يلي:

المكتبة: libandroid

المكتبة: libnativewindow للحصول على أحدث وظائف النافذة الأصلية

المرجع الكامل: مرجع واجهة برمجة التطبيقات Android NDK API

واجهات برمجة التطبيقات لـ Machine Buffer

يتوفر نوعان من واجهات برمجة التطبيقات الأصلية تتيحان لك إنشاء المسارات الخاصة بك لإدارة المخزن المؤقت عبر العمليات المختلفة.

تتيح لك واجهة برمجة التطبيقات الأصلية للمخزن المؤقت للأجهزة <android/hardware_buffer.h> تخصيص الموارد الاحتياطية مباشرةً لإنشاء مساراتك الخاصة لإدارة المخزن المؤقت على مستوى العمليات المختلفة. يمكنك تخصيص AHardwareBuffer واستخدامه للحصول على نوع مورد EGLClientBuffer من خلال إضافة eglGetNativeClientBufferANDROID. يمكنك تمرير هذا المخزن المؤقت إلى eglCreateImageKHR لإنشاء نوع مورد EGLImage والذي يمكن ربطه بعد ذلك بزخرفة من خلال glEGLImageTargetTexture2DOES على الأجهزة المتوافقة. يمكن أن يكون هذا مفيدًا في إنشاء زخارف يمكن مشاركتها بين العمليات المتقاطعة.

تتيح لك واجهة برمجة التطبيقات JNI API للمخزن المؤقت للأجهزة (<android/hardware_buffer_jni.h>) الحصول على كائن HardwareBuffer، وهو كائن قابل للاستبدال وبالتالي يمكن نقله بين عمليتَين مختلفتَين. ويمنح ذلك تطبيقك إمكانيات مماثلة لإمكانات SurfaceFlinger، مثل إنشاء قائمة انتظار خاصة بك من المخازن المؤقتة بين العمليات بدون الوصول إلى واجهات برمجة تطبيقات Android الداخلية.

الصوت

صوت

AAudio هي واجهة برمجة التطبيقات للصوت الأصلي المتوافقة حاليًا. وقد حل هذا الحلّ محلّ OpenSL ES، كما أنّه يوفّر توافقًا أفضل لتطبيقات الصوت العالية الأداء التي تتطلّب وقت استجابة سريع.

تتوفّر هذه الميزة بدءًا من المستوى 26 لواجهة برمجة التطبيقات.

المكتبة: libaaudio

الدليل: دليل AAudio API

المرجع: مرجع AAudio API

OpenSL ES

OpenSL ES هي واجهة برمجة تطبيقات صوتية أصلية أخرى متاحة، ولكن يمكنك الاطّلاع على الملاحظة الواردة في الدليل أدناه.

تتوفّر هذه الميزة منذ المستوى 9 لواجهة برمجة التطبيقات. أضاف المستوى 14 من واجهة برمجة التطبيقات استخدام PCM.

المكتبة: libOpenSLES

الدليل: دليل OpenSL ES لأجهزة Android

واجهة برمجة تطبيقات الشبكات العصبونية

تزوّد واجهة برمجة التطبيقات العصبية (NNAPI) التطبيقات بتسريع الأجهزة لإتاحة عمليات تعلُّم الآلة على الجهاز. تدعم واجهة برمجة التطبيقات إنشاء النماذج على الجهاز وتجميعها وتنفيذها. لا تستخدم التطبيقات عادةً NNAPI مباشرةً، بل من المفترض بدلاً من ذلك أن يتم استدعاء واجهة برمجة التطبيقات بواسطة مكتبات تعلُّم الآلة وأُطر العمل والأدوات التي تتيح للمطوّرين تدريب نماذجهم ونشرها على أجهزة Android.

تتوفّر هذه الميزة بدءًا من المستوى 27 لواجهة برمجة التطبيقات.

المكتبة: libneuralnetworks

دليل: دليل الشبكات العصبية

المرجع: مرجع واجهة برمجة التطبيقات للشبكات العصبية