Auf Geräten mit Android 10 (API-Level 29) und höher ist OpenGL ES (GLES) verfügbar. Eine Debug-fähige App kann GLES-Ebenen aus ihrem APK, ihrem Basisverzeichnis oder von einem ausgewählten Ebenen-APK laden.
Die Verwendung der GLES-Ebene ähnelt der Verwendung der Vulkan-Validierungsschicht.
Voraussetzungen
GLES-Ebenen werden nur ab GLES-Version 2.0 unterstützt.
Ebeneninitialisierung
Nach dem Ausfüllen von Standardeinstiegspunkten initiiert der EGL-Ladeprogramm ein GLES-LayerLoader. Wenn Debug-Ebenen aktiviert sind, scannt LayerLoader angegebene Verzeichnisse nach Ebenen, wie es der Vulkan-Ladeprogramm tut.
Wenn Layering aktiviert ist, sucht LayerLoader nach einer bestimmten Ebenenliste und listet sie auf. Die Ebenenliste wird durch Dateinamen angegeben, die durch einen Doppelpunkt getrennt sind.
LayerLoader durchläuft die Ebenen in der von Ihnen angegebenen Reihenfolge, sodass sich die erste Ebene direkt unter der Anwendung befindet. Die LayerLoader verfolgt für jede Ebene die Einstiegspunkte AndroidGLESLayer_Initialize und AndroidGLESLayer_GetProcAddress. 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() stellt eine Kennung 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 übernimmt die Adresse des nächsten Aufrufs in der Kette, den die Ebene nach Abschluss aufrufen soll. 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 der GLES-LayerLoader findet, ruft er AndroidGLESLayer_Initialize auf, geht die Funktionslisten von libEGL durch und ruft AndroidGLESLayer_GetProcAddress für alle bekannten Funktionen auf. Der Layer entscheidet selbst, wie die nächste Adresse verfolgt wird. Wenn die Ebene eine Funktion abfängt, wird deren Adresse verfolgt. Wenn die Ebene keine Funktion abfängt, gibt AndroidGLESLayer_GetProcAddress dieselbe Funktionsadresse zurück, die sie übergeben hat. LayerLoader aktualisiert dann die Liste der Funktions-Hooks, sodass sie auf den Einstiegspunkt der Ebene verweist.
Die Ebenen müssen nichts mit den Informationen AndroidGLESLayer_Initialize und get_next_layer_proc_address tun, aber die Bereitstellung der Daten erleichtert es, dass vorhandene Ebenen wie Android GPU Inspector und RenderDoc Android unterstützen. Mit diesen Daten kann eine Ebene unabhängig nach Funktionen suchen, anstatt auf Aufrufe von AndroidGLESLayer_GetProcAddress zu warten. Wenn sich die Layer für die Initialisierung selbst entscheiden, 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.
Ebenen platzieren
Das GLES-LayerLoader sucht nach Ebenen an den folgenden Orten in der Reihenfolge ihrer Priorität:
1. Systemspeicherort für Root
Hierfür 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 debug-fähig sein oder Sie benötigen Root-Zugriff:
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, das die zu ladenden Ebenen enthält:
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. App-spezifische Einstellungen bleiben bei Neustarts erhalten, während globale Eigenschaften 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 bietet Ihnen mehr Informationen zur Fehlerbehebung, kann sich aber negativ auf die Leistung Ihrer App auswirken.
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 folgenden zwei Funktionen bereitstellen, die unter Initialisierung des EGL-Ladeprogramms beschrieben werden:
AndroidGLESLayer_Initialize AndroidGLESLayer_GetProcAddress
Passive Ebenen
Für einen Layer, der nur eine Handvoll 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
Bei formalisierten Layern, die vollständig im Voraus initialisiert werden müssen, oder bei Layern, die nach Erweiterungen suchen müssen, die dem EGL Loader nicht bekannt sind, ist eine aktive Layer-Initialisierung erforderlich. Die Ebene verwendet das von AndroidGLESLayer_Initialize bereitgestellte get_next_layer_proc_address, um eine Funktion zu suchen. Die Ebene muss weiterhin auf AndroidGLESLayer_GetProcAddress-Anfragen vom Loader antworten, damit die Plattform weiß, wohin Aufrufe 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);
}
}