Questa pagina è stata tradotta dall'API Cloud Translation.

Livelli GLES

Sui dispositivi con Android 10 (livello API 29) e versioni successive, è disponibile la stratificazione OpenGL ES (GLES). Un'app di cui è possibile eseguire il debug può caricare i livelli GLES dal relativo APK, dalla directory di base o da un APK di livello selezionato.

L'utilizzo del livello GLES è simile a quello del livello di convalida Vulkan.

Requisiti

I livelli GLES sono supportati solo nelle versioni GLES 2.0 e successive.

Inizializzazione del livello

Dopo aver compilato i punti di ingresso standard, EGL Loader crea un oggetto GLES LayerLoader. Se i livelli di debug sono attivi, LayerLoader esegue la scansione delle directory specificate per i livelli, come fa il caricatore Vulkan.

Se il layering è attivato, LayerLoader cerca ed enumera un elenco di livelli specificato. L'elenco dei livelli è specificato da nomi di file separati da due punti.

LayerLoader attraversa i livelli nell'ordine specificato, quindi il primo livello si trova direttamente sotto l'applicazione. Per ogni livello, LayerLoader monitora i punti di ingresso AndroidGLESLayer_Initialize e AndroidGLESLayer_GetProcAddress. I livelli devono fornire queste interfacce per essere caricabili.

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

AndroidGLESLayer_Initialize() fornisce un identificatore per il livello da utilizzare (layer_id) e un punto di ingresso che può essere chiamato per cercare le funzioni sotto il livello. Il punto di ingresso può essere utilizzato come mostrato nel seguente esempio di codice:

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

AndroidGLESLayer_GetProcAddress prende l'indirizzo della chiamata successiva nella catena che il livello deve chiamare al termine. Se è presente un solo livello, next punta direttamente al driver per la maggior parte delle funzioni.

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

Per ogni livello trovato da GLES LayerLoader, chiama AndroidGLESLayer_Initialize, scorre gli elenchi di funzioni di libEGL e chiama AndroidGLESLayer_GetProcAddress per tutte le funzioni note. Spetta al livello determinare come monitorare l'indirizzo successivo. Se il livello intercetta una funzione, ne monitora l'indirizzo. Se il livello non intercetta una funzione, AndroidGLESLayer_GetProcAddress restituisce lo stesso indirizzo della funzione che è stato passato. LayerLoader aggiorna quindi l'elenco degli hook di funzione in modo che punti al punto di ingresso del livello.

I livelli non sono necessari per fare qualcosa con le informazioni AndroidGLESLayer_Initialize e get_next_layer_proc_address, ma fornire i dati semplifica il supporto di Android per i livelli esistenti, come Android GPU Inspector e RenderDoc. Con questi dati, un livello può cercare le funzioni in modo indipendente anziché attendere le chiamate a AndroidGLESLayer_GetProcAddress. Se i livelli scelgono di inizializzarsi prima che il caricatore abbia eseguito una query su tutti i punti di ingresso, devono utilizzare get_next_layer_proc_address. eglGetProcAddress deve essere trasmesso alla piattaforma lungo la catena.

Posizionare i livelli

GLES LayerLoader cerca i livelli nelle seguenti posizioni, in ordine di priorità:

1. Posizione del sistema per la radice

È richiesto l'accesso 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. Directory di base dell'applicazione

L'applicazione di destinazione deve essere sottoposta a debug oppure devi disporre dell'accesso 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 esterno

Determina l'ABI dell'applicazione di destinazione, quindi installa un APK contenente i livelli che vuoi caricare:

adb install --abi armeabi-v7a layers.apk

4. Nell'APK dell'applicazione di destinazione

Il seguente esempio mostra come inserire i livelli nell'APK dell'applicazione:

$ 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

Attivare i livelli

Puoi attivare i livelli GLES per app o a livello globale. Le impostazioni per app vengono mantenute tra i riavvii, mentre le proprietà globali vengono cancellate al riavvio.

Il modello di sicurezza e le norme di Android differiscono in modo significativo dalle altre piattaforme. Per caricare i livelli esterni, deve verificarsi una delle seguenti condizioni:

Il file manifest dell'app di destinazione include il seguente elemento meta-data (valido solo per le app destinate ad Android 11 (livello API 30) o versioni successive):

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

Devi utilizzare questa opzione per profilare la tua applicazione.
L'app di destinazione è sottoponibile a debug. Questa opzione fornisce maggiori informazioni di debug, ma potrebbe influire negativamente sulle prestazioni della tua app.
L'app di destinazione viene eseguita su una build userdebug del sistema operativo che concede l'accesso root.

Per attivare i livelli per 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>

Per disattivare i livelli per 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

Per attivare i livelli a livello globale:

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

Creare un livello

I livelli devono esporre le due funzioni seguenti descritte in Inizializzazione del caricatore EGL:

AndroidGLESLayer_Initialize
AndroidGLESLayer_GetProcAddress

Livelli passivi

Per un livello che intercetta solo una manciata di funzioni, un livello inizializzato passivamente è ottimale. Il livello inizializzato passivamente attende che GLES LayerLoader inizializzi la funzione di cui ha bisogno.

Il seguente esempio di codice mostra come creare un livello passivo.

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

Livelli attivi

Per i livelli più formalizzati che devono essere inizializzati completamente in anticipo o per i livelli che devono cercare estensioni non note al caricatore EGL, è necessaria l'inizializzazione del livello attivo. Il livello utilizza get_next_layer_proc_address fornito da AndroidGLESLayer_Initialize per cercare una funzione. Il livello deve comunque rispondere alle richieste AndroidGLESLayer_GetProcAddress del caricatore, in modo che la piattaforma sappia dove indirizzare le chiamate. Il seguente esempio di codice mostra come creare un livello attivo.

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