طبقات GLES

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

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

المتطلبات

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

إعداد الطبقة

بعد تعبئة نقاط الدخول العادية، ينشئ أداة تحميل EGL مثيلًا لـ 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)

لكل طبقة يعثر عليها LayerLoader في GLES، يتم استدعاء 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 إلى المنصة.

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

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

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 بشكل كبير عن الأنظمة الأساسية الأخرى. لتحميل الطبقات الخارجية، يجب استيفاء أحد الشروط التالية:

  • يتضمّن ملف البيان للتطبيق المستهدَف عنصر البيانات الوصفية التالي (ينطبق فقط على التطبيقات التي تستهدف Android 11 (المستوى 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 Loader، يجب إعداد الطبقة النشطة. تستخدِم الطبقة 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);
  }
}