يوفّر هذا القسم المعلومات اللازمة لبدء استخدام واجهات برمجة تطبيقات OpenSL ES.
إضافة OpenSL ES إلى تطبيقك
يمكنك استدعاء OpenSL ES من كل من رمزي C وC++. لإضافة ميزة OpenSL ES الأساسية إلى تطبيقك، عليك تضمين ملف العنوان OpenSLES.h:
#include <SLES/OpenSLES.h>
لإدراج إضافات Android بتنسيق OpenSL ES،
عليك أيضًا تضمين ملف العنوان OpenSLES_Android.h:
#include <SLES/OpenSLES_Android.h>
عند تضمين ملف العنوان OpenSLES_Android.h، يتم تضمين العناوين التالية تلقائيًا:
#include <SLES/OpenSLES_AndroidConfiguration.h> #include <SLES/OpenSLES_AndroidMetadata.h>
ملاحظة: هذه العناوين غير مطلوبة، ولكن يتم عرضها كوسائل مساعدة في التعرّف على واجهة برمجة التطبيقات.
الإنشاء وتصحيح الأخطاء
يمكنك دمج OpenSL ES في إصدارك من خلال تحديده في ملف
Android.mk الذي يُعدّ أحد ملفات
makefiles الخاصة بنظام إنشاء NDK. إضافة السطر التالي إلى Android.mk:
LOCAL_LDLIBS += -lOpenSLES
لتصحيح الأخطاء بشكلٍ فعّال، ننصحك بفحص قيمة SLresult التي تعرضها معظم واجهات برمجة تطبيقات OpenSL ES. يمكنك استخدام
التأكيدات
أو منطق أكثر تقدّمًا لمعالجة الأخطاء لتصحيح الأخطاء، فأيًّا منهما لا يقدّم
ميزة متأصلة للعمل مع OpenSL ES، على الرغم من أنّ أحدهما قد يكون أكثر ملاءمةً
لحالة استخدام معيّنة.
ونستخدم التأكيدات في الأمثلة، لأنّها تساعد في رصد الحالات غير الواقعية التي قد تشير إلى خطأ في الترميز. لقد استخدمنا معالجة الأخطاء الصريحة للحالات الأخرى التي من المرجح حدوثها في الإنتاج.
تؤدي العديد من أخطاء واجهة برمجة التطبيقات إلى إدخال سجلّ، بالإضافة إلى رمز نتيجة بقيمة غير صفرية. ويمكن أن توفّر إدخالات السجلّ هذه تفاصيل إضافية تكون مفيدة بشكل خاص لواجهات برمجة التطبيقات المعقدة نسبيًا، مثل
Engine::CreateAudioPlayer.
يمكنك عرض السجلّ إما من سطر الأوامر أو من "استوديو Android". لفحص السجل من سطر الأوامر، اكتب ما يلي:
$ adb logcat
لفحص السجلّ من "استوديو Android"، اختَر عرض > أداة Windows > Logcat. لمزيد من المعلومات، يُرجى الاطّلاع على كتابة السجلات وعرضها باستخدام Logcat.
مثال على الرمز
نقترح عليك استخدام نموذج الرموز المتوافقة والاختبارية الذي يمكن استخدامه كنموذج لرمزك البرمجي، ويمكنك العثور عليه في المجلدَين audio-echo وNative-audio في مستودع android-ndk GitHub.
تنبيه: تحتوي مواصفات OpenSL ES 1.0.1 على نموذج رمز في الملاحق (يمكنك الاطّلاع على Khronos OpenSL ES Registry للاطّلاع على مزيد من التفاصيل). ومع ذلك، تستخدم الأمثلة الواردة في الملحق ب: الرمز النموذجي والملحق ج: الرمز النموذجي لحالة الاستخدام ميزات لا يتيحها Android. تحتوي بعض الأمثلة أيضًا على أخطاء مطبعية أو تستخدم واجهات برمجة تطبيقات من المحتمل أن تتغير. يُرجى توخّي الحذر عند الإشارة إلى هذه القواعد، على الرغم من أنّ الرمز البرمجي قد يكون مفيدًا في فهم معيار OpenSL ES الكامل، إلا أنّه يجب عدم استخدامه كما هو مع Android.
محتوى صوتي
في ما يلي بعض الطرق العديدة لتجميع محتوى صوتي لتطبيقك:
- المصادر: من خلال وضع ملفاتك الصوتية في مجلد
res/raw/، يمكن الوصول إليها بسهولة من خلال واجهات برمجة التطبيقات المرتبطة بالسمةResources. ولا يمكن الوصول المباشر إلى الموارد من خلال مصدر أصلي، لذا عليك كتابة رمز لغة برمجة Java لنسخها قبل استخدامها. - مواد العرض: من خلال وضع ملفاتك الصوتية في مجلد
assets/، يمكن الوصول إليها مباشرةً عبر واجهات برمجة تطبيقات إدارة مواد العرض الأصلية في Android. اطّلِع على ملفَي العناوينandroid/asset_manager.hوandroid/asset_manager_jni.hللحصول على مزيد من المعلومات عن واجهات برمجة التطبيقات هذه. إنّ رمز المثال المتوفّر في مستودع android-ndk GitHub يستخدم واجهات برمجة التطبيقات الأصلية لإدارة الأصول هذه جنبًا إلى جنب مع محدِّد بيانات واصف ملفات Android. - الشبكة: يمكنك استخدام محدِّد بيانات معرّف الموارد المنتظم (URI) لتشغيل المحتوى الصوتي من الشبكة مباشرةً. ومع ذلك، احرص على قراءة الأمان والأذونات.
- نظام الملفات المحلي: يتوافق محدِّد مواقع بيانات معرّف الموارد المنتظم (URI) مع نظام
file:للملفات المحلية، شرط أن يتمكن التطبيق من الوصول إلى الملفات. تجدر الإشارة إلى أنّ إطار عمل الأمان في Android يحظر الوصول إلى الملفات من خلال آليات رقم تعريف المستخدم ورقم تعريف المجموعة في نظام التشغيل Linux. - مسجّل: يمكن للتطبيق تسجيل بيانات صوتية من إدخال الميكروفون وتخزين هذا المحتوى وإعادة تشغيله لاحقًا. يستخدم الرمز النموذجي هذه الطريقة لمقطع تشغيل.
- محتوى مضمَّن ومرتبط: يمكنك ربط المحتوى الصوتي مباشرةً
بالمكتبة المشتركة، ثم تشغيله باستخدام مشغِّل صوت يتضمّن محدِّدًا لبيانات قائمة انتظار المخزن المؤقت. وتُعدّ هذه الطريقة الأنسب للمقاطع القصيرة بتنسيق PCM. يستخدم الرمز النموذجي هذا الأسلوب للمقاطع
Hello وAndroid. تم تحويل بيانات PCM إلى سلاسل سداسية عشرية باستخدام أداة
bin2c(غير مقدَّمة). - التركيب في الوقت الفعلي: يمكن لتطبيقك إنشاء بيانات PCM بسرعة ثم تشغيلها باستخدام مشغّل صوت يتضمّن محدِّد مواقع بيانات قائمة انتظار المخزن المؤقت. وهي تقنية متقدّمة نسبيًا، ولا تشمل هذه المقالة تفاصيل تركيب الصوت.
ملاحظة: إنّ العثور على محتوى صوتي مفيد لتطبيقك أو إنشائه خارج نطاق هذه المقالة. يمكنك استخدام عبارات بحث الويب مثل محتوى صوتي تفاعلي وصوت ألعاب وتصميم صوت وبرمجة صوتية للعثور على مزيد من المعلومات.
تنبيه: تقع على عاتقك مسؤولية ضمان السماح لك قانونًا بتشغيل المحتوى أو تسجيله. قد تكون هناك اعتبارات خصوصية لتسجيل المحتوى.
عيّنات التعليمات البرمجية
وتتوفّر نماذج التطبيقات التالية على صفحة GitHub:
- تنشئ audio-echo حلقة ذهاب وعودة من مصدر الإدخال إلى الإخراج.
- Native-audio مسجل/مشغّل صوت بسيط.
يختلف تنفيذ NDK NDK من OpenSL ES عن المواصفات المرجعية لـ OpenSL ES 1.0.1 من حيث عدد من الجوانب. تُعدّ هذه الاختلافات سببًا مهمًا لاحتمال عدم عمل نموذج الرمز الذي تنسخه مباشرةً من المواصفات المرجعية لـ OpenSL ES في تطبيق Android.
لمزيد من المعلومات حول أوجه الاختلاف بين المواصفات المرجعية وتطبيق Android، يُرجى الاطّلاع على OpenSL ES لنظام التشغيل Android.