GLES 层

在运行 Android 10(API 级别 29)及更高版本的设备上,可以使用 OpenGL ES (GLES) 分层。可调试的应用可以从其 APK、其基目录或选定的层 APK 加载 GLES 层。

GLES 层的使用类似于 Vulkan 验证层 的使用。

要求

GLES 层仅在 GLES 2.0+ 版本上受支持。

层初始化

填充标准入口点后,EGL 加载器会实例化 GLES LayerLoader。如果启用了调试层,则 LayerLoader 会扫描指定目录中的层,就像 Vulkan 加载器 一样。

如果启用了分层,则 LayerLoader 会搜索并枚举指定的层列表。层列表由冒号分隔的文件名指定。

LayerLoader 按您指定的顺序遍历层,因此第一层直接位于应用程序下方。对于每一层,LayerLoader 会跟踪 AndroidGLESLayer_InitializeAndroidGLESLayer_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_Initializeget_next_layer_proc_address 提供的信息执行任何操作,但提供数据可以更轻松地让现有层(如 Android GPU InspectorRenderDoc)支持 Android。使用这些数据,层可以独立查找函数,而不必等待对 AndroidGLESLayer_GetProcAddress 的调用。如果层选择在加载器查询所有入口点之前自行初始化,则必须使用 get_next_layer_proc_addresseglGetProcAddress 必须向下传递到平台。

放置层

GLES LayerLoader 会按以下位置顺序(优先级顺序)搜索层:

1. 根目录的系统位置

这需要root权限

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. 应用程序的基本目录

目标应用程序必须可调试,或者您必须具有root权限

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(API级别30)或更高版本的应用)

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

    您应该使用此选项来分析您的应用程序。

  • 目标应用是可调试的。此选项为您提供更多调试信息,但可能会对应用程序的性能产生负面影响。

  • 目标应用运行在具有root权限的操作系统的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加载器未知的扩展的层,需要主动层初始化。该层使用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);
  }
}