طبقات GLES

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

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

المتطلبات

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

إعداد الطبقة

بعد ملء نقاط الدخول العادية، ينشئ برنامج 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 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);
  }
}