GLES-Ebenen

Auf Geräten mit Android 10 (API-Level 29) und höher ist die OpenGL ES-Schicht (GLES) verfügbar. Eine debugfähige App kann GLES-Ebenen aus ihrem APK, aus ihrem Basisverzeichnis oder aus einem ausgewählten Ebenen-APK laden.

Die Verwendung der GLES-Validierungsebene ähnelt der Verwendung der Vulkan-Validierungsebene.

Voraussetzungen

GLES-Ebenen werden nur in GLES-Versionen ab 2.0 unterstützt.

Initialisierung der Ebene

Nachdem die Standardeinstiegspunkte festgelegt wurden, instanziiert der EGL-Loader ein GLES-LayerLoader. Wenn Debug-Ebenen aktiviert sind, durchsucht LayerLoader die angegebenen Verzeichnisse nach Ebenen, wie es auch der Vulkan-Loader tut.

Wenn das Layering aktiviert ist, sucht LayerLoader nach einer angegebenen Layerliste und zählt sie auf. Die Ebenenliste wird durch durch Doppelpunkte getrennte Dateinamen angegeben.

Die LayerLoader durchläuft die Ebenen in der von Ihnen angegebenen Reihenfolge. Die erste Ebene befindet sich also direkt unter der Anwendung. Für jede Ebene werden mit LayerLoader die Einstiegspunkte AndroidGLESLayer_Initialize und AndroidGLESLayer_GetProcAddress erfasst. Die Ebenen müssen diese Schnittstellen bereitstellen, damit sie geladen werden können.

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

AndroidGLESLayer_Initialize() enthält eine Kennung für die zu verwendende Ebene (layer_id) und einen Einstiegspunkt, der aufgerufen werden kann, um Funktionen unterhalb der Ebene zu suchen. Der Einstiegspunkt kann wie im folgenden Codebeispiel verwendet werden:

const char* func = "eglFoo";
void* gpa = get_next_layer_proc_address(layer_id, func);

AndroidGLESLayer_GetProcAddress enthält die Adresse des nächsten Aufrufs in der Kette, der von der Ebene aufgerufen werden soll, wenn sie fertig ist. Wenn es nur eine Ebene gibt, verweist next für die meisten Funktionen direkt auf den Treiber.

typedef __eglMustCastToProperFunctionPointerType EGLFuncPointer;
void* AndroidGLESLayer_GetProcAddress(const char *funcName, EGLFuncPointer next)

Für jede Ebene, die von GLES LayerLoader gefunden wird, wird AndroidGLESLayer_Initialize aufgerufen, die Funktionslisten von libEGL durchlaufen und AndroidGLESLayer_GetProcAddress für alle bekannten Funktionen aufgerufen. Es liegt am Layer, wie die nächste Adresse verfolgt wird. Wenn der Layer eine Funktion abfängt, wird die Adresse der Funktion erfasst. Wenn die Ebene keine Funktion abfängt, gibt AndroidGLESLayer_GetProcAddress dieselbe Funktionsadresse zurück, die übergeben wurde. LayerLoader aktualisiert dann die Funktions-Hook-Liste, sodass sie auf den Einstiegspunkt der Ebene verweist.

Die Ebenen sind nicht erforderlich, um mit den Informationen von AndroidGLESLayer_Initialize und get_next_layer_proc_address etwas zu tun. Wenn Sie die Daten jedoch bereitstellen, können vorhandene Ebenen wie Android GPU Inspector und RenderDoc Android leichter unterstützen. Mit diesen Daten kann eine Ebene Funktionen unabhängig nachschlagen, anstatt auf Aufrufe von AndroidGLESLayer_GetProcAddress zu warten. Wenn die Ebenen sich initialisieren, bevor der Loader alle Einstiegspunkte abgefragt hat, müssen sie get_next_layer_proc_address verwenden. eglGetProcAddress muss über die Kette an die Plattform weitergegeben werden.

Ebenen platzieren

Die GLES-LayerLoader sucht an den folgenden Speicherorten nach Layern, in der Reihenfolge der Priorität:

1. Systemstandort für Root

Dazu ist Root-Zugriff erforderlich

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. Basisverzeichnis der Anwendung

Die Zielanwendung muss debugfähig sein oder Sie müssen Root-Zugriff haben:

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. Externes APK

Ermitteln Sie die ABI Ihrer Zielanwendung und installieren Sie dann eine APK, die die zu ladenden Ebenen enthält:

adb install --abi armeabi-v7a layers.apk

4. In der APK der Zielanwendung

Das folgende Beispiel zeigt, wie Sie Ebenen in der Anwendungs-APK platzieren:

$ 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

Ebenen aktivieren

Sie können GLES-Ebenen entweder pro App oder global aktivieren. App-spezifische Einstellungen bleiben auch nach einem Neustart erhalten, während globale Eigenschaften beim Neustart gelöscht werden.

Das Sicherheitsmodell und die Richtlinien von Android unterscheiden sich erheblich von denen anderer Plattformen. Damit externe Ebenen geladen werden können, muss eine der folgenden Bedingungen erfüllt sein:

  • Die Manifestdatei der Ziel-App enthält das folgende Meta-Data-Element (gilt nur für Apps, die auf Android 11 (API-Level 30) oder höher ausgerichtet sind):

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

    Sie sollten diese Option verwenden, um ein Profil Ihrer Anwendung zu erstellen.

  • Die Ziel-App ist debugfähig. Mit dieser Option erhalten Sie mehr Informationen zur Fehlerbehebung, die Leistung Ihrer App kann jedoch beeinträchtigt werden.

  • Die Ziel-App wird in einem Userdebug-Build des Betriebssystems ausgeführt, der Root-Zugriff gewährt.

So aktivieren Sie Ebenen pro App:

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

So deaktivieren Sie Ebenen pro App:

# 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

So aktivieren Sie Ebenen global:

# This attempts to load layers for all applications, including native
# executables
adb shell setprop debug.gles.layers <layer1:layer2:layerN>

Ebene erstellen

Ebenen müssen die beiden folgenden Funktionen bereitstellen, die unter EGL Loader initialization beschrieben werden:

AndroidGLESLayer_Initialize
AndroidGLESLayer_GetProcAddress

Passive Ebenen

Für eine Ebene, die nur wenige Funktionen abfängt, ist eine passiv initialisierte Ebene optimal. Die passiv initialisierte Ebene wartet darauf, dass GLES LayerLoader die benötigte Funktion initialisiert.

Das folgende Codebeispiel zeigt, wie eine passive Ebene erstellt wird.

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

Aktive Ebenen

Für formalisierte Ebenen, die vorab vollständig initialisiert werden müssen, oder Ebenen, die Erweiterungen nachschlagen müssen, die dem EGL-Loader nicht bekannt sind, ist eine aktive Ebeneninitialisierung erforderlich. Die Ebene verwendet die get_next_layer_proc_address, die von AndroidGLESLayer_Initialize bereitgestellt wird, um eine Funktion zu suchen. Die Ebene muss weiterhin auf AndroidGLESLayer_GetProcAddress-Anfragen des Loaders reagieren, damit die Plattform weiß, wohin Anrufe weitergeleitet werden sollen. Das folgende Codebeispiel zeigt, wie eine aktive Ebene erstellt wird.

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