本頁面由 Cloud Translation API 翻譯而成。

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_Initialize 和 AndroidGLESLayer_GetProcAddress 進入點。這些圖層「必須」提供這些介面，才可順利載入。

typedef void* (*PFNEGLGETNEXTLAYERPROCADDRESSPROC)(void*, const char*);
void* AndroidGLESLayer_Initialize(void* layer_id, PFNEGLGETNEXTLAYERPROCADDRESSPROC get_next_layer_proc_address))

AndroidGLESLayer_Initialize() 會提供要使用的圖層 ID (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 檢查器和 RenderDoc) 更容易支援 Android。圖層可以利用這些資料自行查詢函式，不必等待呼叫 AndroidGLESLayer_GetProcAddress。如果圖層選擇在載入器查詢所有進入點之前自行進行初始化，則必須使用 get_next_layer_proc_address。eglGetProcAddress 必須沿鏈結向下傳遞至平台。

放置圖層

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 存取權的作業系統使用者偵錯版本上執行。

如何啟用個別應用程式的圖層：

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