जीएलईएस लेयर

Android 10 (एपीआई लेवल 29) और इसके बाद के वर्शन वाले डिवाइसों पर, OpenGL ES (GLES) लेयरिंग की सुविधा उपलब्ध है. डीबग किए जा सकने वाले ऐप्लिकेशन में, 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 को कॉल करता है. इसके बाद, libEGL की फ़ंक्शन सूचियों को देखता है और सभी ज्ञात फ़ंक्शन के लिए AndroidGLESLayer_GetProcAddress को कॉल करता है.AndroidGLESLayer_Initialize यह लेयर पर निर्भर करता है कि अगले पते को कैसे ट्रैक किया जाए. अगर लेयर किसी फ़ंक्शन को इंटरसेप्ट करती है, तो यह फ़ंक्शन के पते को ट्रैक करती है. अगर लेयर किसी फ़ंक्शन को इंटरसेप्ट नहीं करती है, तो 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

अपने टारगेट ऐप्लिकेशन का एबीआई तय करें. इसके बाद, वह 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, फ़ंक्शन को ढूंढने के लिए get_next_layer_proc_address उपलब्ध कराता है. लेयर को अब भी लोडर से मिले 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);
  }
}