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

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

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

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

1. اطلب من نظام الإنشاء الربط بالمكتبة.

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

     لمزيد من المعلومات حول LOCAL_LDLIBS، راجِع مستندات Android.mk.

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

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

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

Core C/C++

مكتبة C

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

يُرجى العِلم أنّه على نظام التشغيل Android، على عكس Linux، لا تتوفّر مكتبات libpthread أو librt منفصلة. يتم تضمين هذه الوظيفة مباشرةً في 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

الدليل: Native Tracing

ضغط 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 مع الإصدارَين 1.0 و2.0 من OpenGL ES.

لا تتوافق الإصدارات الأحدث من OpenGL ES إلا مع أجهزة Android التي تتضمّن وحدة معالجة الرسومات (GPU) اللازمة، ولكن تتوفّر المكتبات على جميع الأجهزة التي تتوافق مع مستوى واجهة برمجة التطبيقات الذي تم طرحها فيه. يمكن ربط التطبيق بالمكتبات بأمان، ولكن يجب أن يستعلم التطبيق عن سلسلة إصدار OpenGL ES وسلسلة الإضافات لتحديد ما إذا كان الجهاز الحالي يتوافق مع الميزات التي يحتاجها. للحصول على معلومات حول كيفية تنفيذ طلب البحث هذا، راجِع وصف glGetString() في مواصفات OpenGL.

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

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

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

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

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

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

EGL

توفّر 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

Vulkan

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

للاطّلاع على نماذج الرموز البرمجية، راجِع مشروعي LunarG VulkanSamples وandroid-vulkan-tutorials على GitHub.

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

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

المكتبة: libvulkan

الدليل: دليل واجهة برمجة تطبيقات الرسومات Vulkan

الصور النقطية

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

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

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

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

4. اتّصِل بالرقم AndroidBitmap_unlockPixels() لفتح المخزن المؤقت.

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

المكتبة: libjnigraphics

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

Sync API

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

المكتبة: libsync

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

الكاميرا

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

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

المكتبة: libcamera2ndk

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

الوسائط

libmediandk

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

المكتبة: libmediandk

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

OpenMAX AL

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

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

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

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

المكتبة: libOpenMAXAL

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

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات مرجع واجهة برمجة التطبيقات في حزمة تطوير البرامج الأصلية (NDK) لنظام التشغيل Android.

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

• مادة العرض
• مصمّم الرقصات
• الإعداد
• الإدخال
• Looper
• Native Activity
• مخازن مؤقتة للأجهزة الأصلية
• النافذة الأصلية
• الذاكرة
• التواصل
• أداة الاستشعار
• مساحة التخزين
• SurfaceTexture

المكتبة: libandroid

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

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

واجهات برمجة تطبيقات Binder

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

المكتبة: libbinder_ndk

المرجع: Binder

واجهات برمجة التطبيقات الخاصة بـ Hardware Buffer

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

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

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

الصوت

AAudio

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

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

المكتبة: libaaudio

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

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

OpenSL ES

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

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

المكتبة: libOpenSLES

الدليل: دليل OpenSL ES لنظام التشغيل Android

Neural Networks API

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

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

المكتبة: libneuralnetworks

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

المرجع: مرجع Neural Networks API