طبقات GLES

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

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

المتطلبات

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

تهيئة الطبقة

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

إذا كانت ميزة "الطبقات" مفعّلة، يبحث 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 اختلافًا كبيرًا عن المنصّات الأخرى. لتحميل طبقات خارجية، يجب أن يتحقّق أحد الشرطَين التاليَين:

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

# 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 Loader:

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);
  }
}