طبقات GLES

تتوفّر طبقات OpenGL ES (GLES) على الأجهزة التي تعمل بالإصدار 10 من نظام التشغيل Android (المستوى 29 من واجهة برمجة التطبيقات) والإصدارات الأحدث. يمكن للتطبيق القابل للتصحيح تحميل طبقات GLES من حزمة APK أو من الدليل الأساسي أو من حزمة APK لطبقة محدّدة.

يشبه استخدام طبقة GLES استخدام مرحلة التحقّق من Vulkan.

المتطلبات

لا تتوافق طبقات GLES إلا مع إصدارات GLES 2.0 والإصدارات الأحدث.

تهيئة الطبقة

بعد تعبئة نقاط الدخول العادية، ينشئ EGL Loader مثيلاً لـ GLES LayerLoader. في حال تفعيل طبقات تصحيح الأخطاء، يفحص LayerLoader الأدلة المحدّدة بحثًا عن الطبقات، كما يفعل مُحمِّل Vulkan.

في حال تفعيل ميزة "الطبقات"، يبحث LayerLoader عن قائمة طبقات محدّدة ويعدّدها. يتم تحديد قائمة الطبقات من خلال أسماء ملفات مفصولة بنقطتين.

يجتاز LayerLoader الطبقات بالترتيب الذي تحدده، لذا فإن الطبقة الأولى تقع مباشرة أسفل التطبيق. بالنسبة إلى كل طبقة، يتتبّع LayerLoader نقاط الدخول AndroidGLESLayer_Initialize وAndroidGLESLayer_GetProcAddress. يجب أن توفّر الطبقات هذه الواجهات لتكون قابلة للتحميل.

typedef void* (*PFNEGLGETNEXTLAYERPROCADDRESSPROC)(void*, const char*);
void* AndroidGLESLayer_Initialize(void* layer_id, PFNEGLGETNEXTLAYERPROCADDRESSPROC get_next_layer_proc_address))

توفّر السمة AndroidGLESLayer_Initialize() معرّفًا للطبقة التي سيتم استخدامها (layer_id) ونقطة دخول يمكن استدعاؤها للبحث عن الدوال أسفل الطبقة. يمكن استخدام نقطة الدخول كما هو موضّح في عيّنة التعليمات البرمجية التالية:

const char* func = "eglFoo";
void* gpa = get_next_layer_proc_address(layer_id, func);

يأخذ AndroidGLESLayer_GetProcAddress عنوان المكالمة التالية في السلسلة التي يجب أن تتصل بها الطبقة عند الانتهاء. إذا كانت هناك طبقة واحدة فقط، يشير next مباشرةً إلى برنامج التشغيل لمعظم الوظائف.

typedef __eglMustCastToProperFunctionPointerType EGLFuncPointer;
void* AndroidGLESLayer_GetProcAddress(const char *funcName, EGLFuncPointer next)

لكل طبقة يعثر عليها GLES LayerLoader، يتم استدعاء AndroidGLESLayer_Initialize، ويتم الانتقال إلى قوائم دوال libEGL، ويتم استدعاء AndroidGLESLayer_GetProcAddress لجميع الدوال المعروفة. ويعود الأمر إلى الطبقة لتحديد كيفية تتبُّع العنوان التالي. إذا اعترضت الطبقة دالة، فإنها تتبع عنوان الدالة. إذا لم تعترض الطبقة دالة، تعرض الدالة AndroidGLESLayer_GetProcAddress عنوان الدالة نفسه الذي تم تمريره. بعد ذلك، يحدّث LayerLoader قائمة ربط الدوال للإشارة إلى نقطة دخول الطبقة.

لا يُطلب من الطبقات تنفيذ أي إجراء باستخدام المعلومات التي يوفّرها AndroidGLESLayer_Initialize وget_next_layer_proc_address، ولكن توفير البيانات يسهّل على الطبقات الحالية، مثل Android GPU Inspector وRenderDoc، إتاحة استخدام Android. باستخدام هذه البيانات، يمكن لطبقة البحث عن الدوال بشكل مستقل بدلاً من انتظار المكالمات إلى AndroidGLESLayer_GetProcAddress. إذا اختارت الطبقات تهيئة نفسها قبل أن يستعلم المُحمِّل عن جميع نقاط الدخول، يجب أن تستخدم get_next_layer_proc_address. يجب تمرير eglGetProcAddress إلى المنصة.

طبقات الأماكن

يبحث GLES LayerLoader عن الطبقات في المواقع الجغرافية التالية، حسب ترتيب الأولوية:

1. الموقع الجغرافي للنظام للمستخدم الجذر

يتطلّب ذلك الوصول إلى الجذر

adb root
adb disable-verity
adb reboot
adb root
adb shell setenforce 0
adb shell mkdir -p /data/local/debug/gles
adb push <layer>.so /data/local/debug/gles/

2. الدليل الأساسي للتطبيق

يجب أن يكون التطبيق المستهدَف قابلاً للتصحيح، أو يجب أن يكون لديك إذن الوصول إلى الجذر:

adb push libGLTrace.so /data/local/tmp
adb shell run-as com.android.gl2jni cp /data/local/tmp/libGLTrace.so .
adb shell run-as com.android.gl2jni ls | grep libGLTrace
libGLTrace.so

3. ملف APK خارجي

حدِّد واجهة ABI للتطبيق المستهدَف، ثم ثبِّت حزمة APK تحتوي على الطبقات التي تريد تحميلها:

adb install --abi armeabi-v7a layers.apk

4. في حزمة APK الخاصة بالتطبيق المستهدَف

يوضّح المثال التالي كيفية وضع الطبقات في حزمة APK للتطبيق:

$ jar tf GLES_layers.apk
lib/arm64-v8a/libGLES_glesLayer1.so
lib/arm64-v8a/libGLES_glesLayer2.so
lib/arm64-v8a/libGLES_glesLayer3.so
lib/armeabi-v7a/libGLES_glesLayer1.so
lib/armeabi-v7a/libGLES_glesLayer2.so
lib/armeabi-v7a/libGLES_glesLayer3.so
resources.arsc
AndroidManifest.xml
META-INF/CERT.SF
META-INF/CERT.RSA
META-INF/MANIFEST.MF

تفعيل الطبقات

يمكنك تفعيل طبقات GLES لكل تطبيق أو على مستوى الجهاز. تظل الإعدادات الخاصة بكل تطبيق محفوظة بعد إعادة التشغيل، بينما يتم محو الخصائص العامة عند إعادة التشغيل.

يختلف نموذج الأمان والسياسات في Android بشكل كبير عن الأنظمة الأساسية الأخرى. لتحميل الطبقات الخارجية، يجب أن يكون أحد الشرطين التاليين صحيحًا:

  • يتضمّن ملف البيان الخاص بالتطبيق المستهدَف عنصر البيانات الوصفية التالي (لا ينطبق إلا على التطبيقات التي تستهدف الإصدار 11 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 30) أو الإصدارات الأحدث):

    <meta-data android:name="com.android.graphics.injectLayers.enable" android:value="true" />

    يجب استخدام هذا الخيار لإنشاء ملف تعريف لتطبيقك.

  • التطبيق المستهدَف قابل للتصحيح. يوفّر لك هذا الخيار المزيد من معلومات تصحيح الأخطاء، ولكنّه قد يؤثّر سلبًا في أداء تطبيقك.

  • يتم تشغيل التطبيق المستهدَف على إصدار userdebug من نظام التشغيل الذي يمنح إذن الوصول إلى الجذر.

لتفعيل الطبقات لكل تطبيق:

# Enable layers
adb shell settings put global enable_gpu_debug_layers 1

# Specify target application
adb shell settings put global gpu_debug_app <package_name>

# Specify layer list (from top to bottom)
# Layers are identified by their filenames, such as "libGLLayer.so"
adb shell settings put global gpu_debug_layers_gles <layer1:layer2:layerN>

# Specify packages to search for layers
adb shell settings put global gpu_debug_layer_app <package1:package2:packageN>

لإيقاف الطبقات لكل تطبيق:

# Delete the global setting that enables layers
adb shell settings delete global enable_gpu_debug_layers

# Delete the global setting that selects target application
adb shell settings delete global gpu_debug_app

# Delete the global setting that specifies layer list
adb shell settings delete global gpu_debug_layers_gles

# Delete the global setting that specifies layer packages
adb shell settings delete global gpu_debug_layer_app

لتفعيل الطبقات على مستوى العالم:

# This attempts to load layers for all applications, including native
# executables
adb shell setprop debug.gles.layers <layer1:layer2:layerN>

إنشاء طبقة

يجب أن تعرض الطبقات الدالتَين التاليتَين الموضّحتَين في إعداد أداة تحميل EGL:

AndroidGLESLayer_Initialize
AndroidGLESLayer_GetProcAddress

الطبقات السلبية

بالنسبة إلى الطبقة التي تعترض عددًا قليلاً من الدوال، فإنّ الطبقة التي يتم إعدادها بشكل سلبي هي الأفضل. تنتظر الطبقة التي تم إعدادها بشكل سلبي أن يقوم GLES LayerLoader بتهيئة الوظيفة التي يحتاجها.

توضّح عيّنة التعليمات البرمجية التالية كيفية إنشاء طبقة غير نشطة.

namespace {

std::unordered_map<std::string, EGLFuncPointer> funcMap;

EGLAPI EGLBoolean EGLAPIENTRY glesLayer_eglChooseConfig (
  EGLDisplay dpy, const EGLint *attrib_list, EGLConfig *configs, EGLint config_size,
  EGLint *num_config) {

  EGLFuncPointer entry = funcMap["eglChooseConfig"];

  typedef EGLBoolean (*PFNEGLCHOOSECONFIGPROC)(
    EGLDisplay, const EGLint*, EGLConfig*, EGLint, EGLint*);

  PFNEGLCHOOSECONFIGPROC next = reinterpret_cast<PFNEGLCHOOSECONFIGPROC>(entry);

  return next(dpy, attrib_list, configs, config_size, num_config);
}

EGLAPI EGLFuncPointer EGLAPIENTRY eglGPA(const char* funcName) {

  #define GETPROCADDR(func) if(!strcmp(funcName, #func)) { \
    return (EGLFuncPointer)glesLayer_##func; }

  GETPROCADDR(eglChooseConfig);

  // Don't return anything for unrecognized functions
  return nullptr;
}

EGLAPI void EGLAPIENTRY glesLayer_InitializeLayer(
  void* layer_id, PFNEGLGETNEXTLAYERPROCADDRESSPROC get_next_layer_proc_address) {
     // This function is purposefully empty, since this layer does not proactively
     // look up any entrypoints
  }

EGLAPI EGLFuncPointer EGLAPIENTRY glesLayer_GetLayerProcAddress(
  const char* funcName, EGLFuncPointer next) {
  EGLFuncPointer entry = eglGPA(funcName);
  if (entry != nullptr) {
    funcMap[std::string(funcName)] = next;
    return entry;
  }
  return next;
}

}  // namespace

extern "C" {
  __attribute((visibility("default"))) EGLAPI void AndroidGLESLayer_Initialize(
    void* layer_id, PFNEGLGETNEXTLAYERPROCADDRESSPROC get_next_layer_proc_address) {
    return (void)glesLayer_InitializeLayer(layer_id, get_next_layer_proc_address);
  }
  __attribute((visibility("default"))) EGLAPI void* AndroidGLESLayer_GetProcAddress(
    const char *funcName, EGLFuncPointer next) {
    return (void*)glesLayer_GetLayerProcAddress(funcName, next);
  }
}

الطبقات النشطة

بالنسبة إلى الطبقات الأكثر رسمية التي تحتاج إلى الإعداد بالكامل مسبقًا، أو الطبقات التي تحتاج إلى البحث عن إضافات غير معروفة لبرنامج تحميل EGL، يجب إعداد الطبقة النشطة. تستخدم الطبقة get_next_layer_proc_address التي توفّرها AndroidGLESLayer_Initialize للبحث عن دالة. يجب أن تستجيب الطبقة لطلبات AndroidGLESLayer_GetProcAddress من أداة التحميل لكي يعرف النظام الأساسي مكان توجيه المكالمات. يوضّح نموذج الرمز البرمجي التالي كيفية إنشاء طبقة نشطة.

namespace {

std::unordered_map<std::string, EGLFuncPointer> funcMap;

EGLAPI EGLBoolean EGLAPIENTRY glesLayer_eglChooseConfig (
  EGLDisplay dpy, const EGLint *attrib_list, EGLConfig *configs, EGLint config_size,
  EGLint *num_config) {

  EGLFuncPointer entry = funcMap["eglChooseConfig"];

  typedef EGLBoolean (*PFNEGLCHOOSECONFIGPROC)(
    EGLDisplay, const EGLint*, EGLConfig*, EGLint, EGLint*);

  PFNEGLCHOOSECONFIGPROC next = reinterpret_cast<PFNEGLCHOOSECONFIGPROC>(entry);

  return next(dpy, attrib_list, configs, config_size, num_config);
}

EGLAPI EGLFuncPointer EGLAPIENTRY eglGPA(const char* funcName) {

  #define GETPROCADDR(func) if(!strcmp(funcName, #func)) { \
    return (EGLFuncPointer)glesLayer_##func; }

  GETPROCADDR(eglChooseConfig);

  // Don't return anything for unrecognized functions
  return nullptr;
}

EGLAPI void EGLAPIENTRY glesLayer_InitializeLayer(
  void* layer_id, PFNEGLGETNEXTLAYERPROCADDRESSPROC get_next_layer_proc_address) {

  // Note: This is where the layer would populate its function map with all the
  // functions it cares about
  const char* func = “eglChooseConfig”;
  funcMap[func] = get_next_layer_proc_address(layer_id, func);
}

EGLAPI EGLFuncPointer EGLAPIENTRY glesLayer_GetLayerProcAddress(
  const char* funcName, EGLFuncPointer next) {
  EGLFuncPointer entry = eglGPA(funcName);
  if (entry != nullptr) {
    return entry;
  }

  return next;
}

}  // namespace

extern "C" {
  __attribute((visibility("default"))) EGLAPI void AndroidGLESLayer_Initialize(
    void* layer_id, PFNEGLGETNEXTLAYERPROCADDRESSPROC get_next_layer_proc_address) {
    return (void)glesLayer_InitializeLayer(layer_id, get_next_layer_proc_address);
  }
  __attribute((visibility("default"))) EGLAPI void* AndroidGLESLayer_GetProcAddress(
    const char *funcName, EGLFuncPointer next) {
    return (void*)glesLayer_GetLayerProcAddress(funcName, next);
  }
}