Auf Geräten mit Android 10 (API-Level 29) und höher ist die OpenGL ES-(GLES-)Layering-Funktion verfügbar. Eine debug-fähige App kann GLES-Ebenen aus ihrem APK, aus ihrem Basisverzeichnis oder aus einem APK der ausgewählten Ebene laden.
Die Verwendung der GLES-Ebene ähnelt der Verwendung der Vulkan-Validierungsschicht.
Voraussetzungen
GLES-Ebenen werden nur in GLES-Versionen ab 2.0 unterstützt.
Layer-Initialisierung
Nach dem Ausfüllen von Standardeinstiegspunkten instanziiert der EGL-Loader eine GLES-LayerLoader. Wenn Debug-Ebenen aktiviert sind, scannt LayerLoader die angegebenen Verzeichnisse nach Ebenen, wie das Vulkan Loader tut.
Wenn Ebenen aktiviert ist, sucht LayerLoader nach einer bestimmten Ebenenliste und listet sie auf. Die Ebenenliste wird durch Doppelpunkte getrennte Dateinamen angegeben.
Der LayerLoader durchläuft die Ebenen in der von Ihnen angegebenen Reihenfolge, sodass sich die erste Ebene direkt unter der Anwendung befindet. Für jede Ebene verfolgt LayerLoader die Einstiegspunkte AndroidGLESLayer_Initialize und AndroidGLESLayer_GetProcAddress. Die Schichten 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() stellt eine ID für die zu verwendende Ebene (layer_id) und einen Einstiegspunkt bereit, der aufgerufen werden kann, um Funktionen unter der Ebene nachzuschlagen. Der Einstiegspunkt kann wie im folgenden Codebeispiel gezeigt verwendet werden:
const char* func = "eglFoo"; void* gpa = get_next_layer_proc_address(layer_id, func);
AndroidGLESLayer_GetProcAddress verwendet die Adresse des nächsten Aufrufs in der Kette, den die Ebene nach Abschluss aufrufen soll. Wenn es nur einen Layer gibt, verweist next bei den meisten Funktionen direkt auf den Treiber.
typedef __eglMustCastToProperFunctionPointerType EGLFuncPointer; void* AndroidGLESLayer_GetProcAddress(const char *funcName, EGLFuncPointer next)
Für jede Ebene, die die GLES-LayerLoader findet, ruft sie AndroidGLESLayer_Initialize auf, durchläuft die Funktionslisten von libEGL und ruft AndroidGLESLayer_GetProcAddress für alle bekannten Funktionen auf. Die Ebene entscheidet, wie die nächste Adresse verfolgt werden soll. Wenn die Ebene 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. Anschließend aktualisiert LayerLoader die Funktions-Hook-Liste so, dass sie auf den Einstiegspunkt der Ebene verweist.
Die Ebenen müssen nichts mit den von AndroidGLESLayer_Initialize und get_next_layer_proc_address bereitgestellten Informationen tun. Durch die Bereitstellung der Daten wird es jedoch für vorhandene Ebenen wie Android GPU Inspector und RenderDoc einfacher, Android zu unterstützen. Mit diesen Daten kann eine Ebene Funktionen unabhängig suchen, anstatt auf Aufrufe von AndroidGLESLayer_GetProcAddress zu warten. Wenn sich die Ebenen selbst initialisieren, bevor das Ladeprogramm alle Einstiegspunkte abgefragt hat, müssen sie get_next_layer_proc_address verwenden. eglGetProcAddress muss in der Kette an die Plattform übergeben werden.
Ortsebenen
Die GLES-LayerLoader sucht nach Ebenen an den folgenden Orten (in der Reihenfolge ihrer Priorität):
1. Systemspeicherort für das Stammverzeichnis
Dies erfordert Root-Zugriff
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 debug-fähig sein oder 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
Bestimmen Sie die ABI Ihrer Zielanwendung und installieren Sie dann ein APK mit den zu ladenden Ebenen:
adb install --abi armeabi-v7a layers.apk
4. Im APK der Ziel-App
Das folgende Beispiel zeigt, wie Ebenen im App-APK platziert werden:
$ 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. Die App-spezifischen Einstellungen bleiben auch nach einem Neustart erhalten, während globale Attribute beim Neustart gelöscht werden.
Das Sicherheitsmodell und die Richtlinien von Android unterscheiden sich erheblich von anderen Plattformen. Zum Laden externer Ebenen muss eine der folgenden Bedingungen erfüllt sein:
Die Manifestdatei der Ziel-App enthält das folgende Meta-Datenelement (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 für Ihre Anwendung zu erstellen.
Die Ziel-App ist debug-fähig. Diese Option liefert Ihnen mehr Informationen zur Fehlerbehebung, kann sich aber negativ auf die Leistung Ihrer Anwendung auswirken.
Die Ziel-App wird auf 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 verfügbar machen, die unter Initialisierung des EGL-Ladeprogramms beschrieben sind:
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, bis GLES LayerLoader die erforderliche 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 stärker formalisierte Ebenen, die im Vorfeld vollständig initialisiert werden müssen, oder für die nach Erweiterungen gesucht werden müssen, die dem EGL-Ladeprogramm nicht bekannt sind, ist die Initialisierung der aktiven Ebene erforderlich. Die Ebene verwendet den get_next_layer_proc_address, den AndroidGLESLayer_Initialize bereitstellt, um eine Funktion zu suchen. Die Ebene muss weiterhin auf AndroidGLESLayer_GetProcAddress-Anfragen vom Ladeprogramm antworten, damit die Plattform weiß, wohin Aufrufe weitergeleitet werden sollen. Das folgende Codebeispiel zeigt, wie Sie eine aktive Ebene erstellen.
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);
}
}