Guida rapida di Android GPU Inspector

Questo argomento descrive come eseguire la profilazione del sistema e la profilazione dei frame nella tua app per Android utilizzando Android GPU Inspector (AGI).

Questa guida rapida è rivolta agli sviluppatori che hanno familiarità con lo sviluppo di grafica su Android.

Requisiti del computer

Il computer che esegue l'AGI deve soddisfare i seguenti requisiti:

È richiesto uno dei seguenti sistemi operativi:
- Windows: Windows 7 o versioni successive.
- macOS: El Capitan (10.11) o versione successiva.
- Linux: è richiesto Java JDK a 64 bit o JRE 8 (o versioni successive); si consiglia Ubuntu Trusty Tahr (14.04 o versioni successive).
Lo strumento a riga di comando adb.

Scarica e installa AGI

Scarica e installa AGI per il tuo sistema operativo.

Requisiti delle app per Android

Questa sezione descrive i requisiti per l'app Android che viene profilata:

La tua app Android deve poter essere sottoposta a debug; l'attributo debuggable nel file manifest Android dell'app deve essere impostato su true. Questo attributo abilita la strumentazione corretta dal driver di grafica. Per le applicazioni Vulkan, questo attributo consente ad AGI di aggiungere il proprio livello Vulkan all'avvio dell'applicazione.
```
<application [...] android:debuggable="true">
```

Se la tua app utilizza Vulkan in modo nativo, AGI richiede anche quanto segue:

Nella tua app devono essere abilitati i livelli di convalida Vulkan. Se non sono abilitati, puoi eseguire i seguenti comandi per forzare l'esecuzione dell'app con i livelli di convalida inclusi nell'APK AGI (com.google.android.gapid.<abi>):

app_package=<YOUR APP PACKAGE NAME HERE>
abi=arm64v8a # Possible values: arm64v8a, armeabi-v7a, x86

adb shell settings put global enable_gpu_debug_layers 1
adb shell settings put global gpu_debug_app ${app_package}
adb shell settings put global gpu_debug_layer_app com.google.android.gapid.${abi}
adb shell settings put global gpu_debug_layers VK_LAYER_KHRONOS_validation

Al termine della profilazione, puoi disabilitare questi livelli di convalida con i seguenti comandi:

adb shell settings delete global enable_gpu_debug_layers
adb shell settings delete global gpu_debug_app
adb shell settings delete global gpu_debug_layers
adb shell settings delete global gpu_debug_layer_app

La tua app non deve segnalare avvisi o errori quando viene eseguita con i livelli di convalida Vulkan attivati. Correggi eventuali errori di convalida di Vulkan prima della profilazione.

Se utilizzi driver GPU beta, includi i seguenti metadati nel tag <application> del file manifest Android:

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

Requisiti dei dispositivi Android

L'AGI prevede i seguenti requisiti per i dispositivi Android:

Un dispositivo Android supportato con Android 11 o versioni successive.
Un cavo USB.
il debug ADB deve essere attivato e il dispositivo deve essere accessibile tramite adb. Se è presente l'opzione Installa tramite USB, attivala.

Convalida dei dispositivi

AGI richiede un driver GPU compatibile. Per garantire che fornisca dati di profilazione validi, AGI esegue un controllo di convalida la prima volta che connetti un nuovo dispositivo, che richiede circa dieci secondi. Dopo aver superato il controllo, puoi usare il dispositivo per profilare le app Android.

Non disturbare il dispositivo mentre è in corso la convalida. Questa operazione potrebbe causare la mancata convalida del dispositivo. Se la convalida del dispositivo non va a buon fine, ma è configurato correttamente, puoi riselezionarlo.

La convalida è un passaggio da eseguire una sola volta per un dispositivo e i risultati vengono memorizzati nella cache per l'uso futuro di AGI. Tuttavia, AGI eseguirà nuovamente la convalida se la configurazione del dispositivo cambia, ad esempio se il driver GPU o la versione di Android vengono aggiornati.

Se un dispositivo è indicato come supportato, puoi aspettarti che l'AGI superi la convalida. Se il dispositivo non è presente nell'elenco, è molto probabile che il relativo driver GPU non sia compatibile con AGI.

Se il dispositivo è supportato ma non supera la convalida

Assicurati di soddisfare tutti i requisiti Android e i requisiti del computer descritti nelle sezioni precedenti e che il dispositivo sia collegato correttamente al computer con un cavo USB.

Se tutti i requisiti sono soddisfatti, segnala il problema nel nostro repository GitHub per descrivere il comportamento.

Se il tuo dispositivo non è supportato

Stiamo collaborando con i nostri OEM partner per aggiungere il supporto per altri dispositivi. Puoi segnalare un problema nel nostro repository GitHub per richiedere assistenza per un dispositivo.

Acquisisci dati di profilazione

Le seguenti sezioni descrivono come acquisire i dati di profilazione e aprire il file di traccia risultante in modo da poter analizzare i risultati.

Configura le impostazioni di Android

Prima di iniziare la profilazione, devi configurare queste impostazioni delle app e del dispositivo Android, che specificano l'app e il dispositivo da profilare.

Collega il dispositivo Android al computer con un cavo USB.
Avvia AGI sul computer.

Al primo avvio di AGI, viene visualizzata la schermata di benvenuto, che richiede il percorso dell'eseguibile AGI. AGI salva queste impostazioni nel file .agic nella cartella HOME. Se l'hai già fatto, puoi saltare questo passaggio.

Figura 1: schermata di benvenuto.
Inserisci il percorso dell'eseguibile ADB nel campo Percorso ad adb. Le caselle di controllo dopo questo campo sono facoltative.
Fai clic su Inizia per visualizzare la schermata di avvio.

Figura 2: schermata di avvio principale di Android GPU Inspector.
Nella schermata di avvio, fai clic su Acquisisci una nuova traccia. Viene visualizzata la finestra di dialogo Acquisisci una nuova traccia. In alternativa, puoi fare clic sul pulsante Acquisisci traccia del profilo di sistema.

Figura 3: finestra di dialogo Acquisisci una nuova traccia.
Nella sezione Dispositivo e tipo, seleziona il dispositivo Android che vuoi profilare. Se non è presente nell'elenco Dispositivo, fai clic sulla freccia per ricaricare l'elenco.
Nella sezione Applicazione, seleziona l'app che vuoi profilare. Se il pacchetto contiene una sola attività, puoi selezionare il pacchetto anziché l'attività.

AGI include un'app Vulkan di esempio. Per utilizzare l'app di esempio anziché la tua, esegui questi passaggi:
1. Fai clic sul pulsante ... accanto al campo Applicazione.
  
  Viene visualizzata la finestra di dialogo Seleziona un'applicazione da tracciare, che mostra un elenco di app tracciabili sul dispositivo selezionato.
2. Nella casella di testo Filtro, digita gapid per visualizzare solo le applicazioni che contengono gapid nel nome del pacchetto.
3. Espandi il pacchetto e seleziona com.google.android.gapid.VkSampleActivity, quindi fai clic su OK.
  
  Viene visualizzata di nuovo la finestra di dialogo Acquisisci una nuova traccia, in cui il campo Applicazione completa l'applicazione selezionata.
Nella sezione Application (Applicazione), lascia gli altri campi vuoti.
Fai clic su OK.

Ora puoi utilizzare AGI per eseguire la profilazione del sistema e dei frame.

Profila un sistema

Per profilare un sistema, segui questi passaggi:

Nella schermata di avvio di AGI, fai clic su Acquisisci una nuova traccia per visualizzare la finestra di dialogo Acquisisci profilo di sistema.
Nell'elenco Tipo, seleziona Profilo di sistema.
Nella sezione Inizio e durata, imposta Inizia a su Manuale e Durata su 2.
Nella sezione Opzioni di traccia, fai clic su Configura. Viene visualizzato un elenco di opzioni di profilazione.

Figura 4: le opzioni di profilazione nella finestra di dialogo Acquisisci profilo di sistema.
Seleziona i dati di profilazione che vuoi acquisire.
Nella sezione GPU, fai clic su Seleziona.

Viene visualizzato un elenco di contatori da selezionare.

Figura 5: selezione dei contatori.
Fai clic su valore predefinito per selezionare l'insieme di contatori predefiniti e fai clic su OK per restituire le opzioni di profilazione.
Fai clic su OK per tornare alla finestra di dialogo principale Acquisisci profilo di sistema.
Nella sezione Output, seleziona una directory di output per archiviare i file di traccia generati durante la profilazione. Il campo Nome file dovrebbe essere compilato automaticamente, ma puoi anche modificarlo.
Fai clic su OK. Viene avviata l'app selezionata sul dispositivo Android e viene visualizzata una finestra popup con un pulsante Start.
Fai clic sul pulsante Avvia per iniziare ad acquisire i dati di profilazione e attendi un paio di secondi per il completamento del processo.
Fai clic su Apri traccia. La visualizzazione iniziale mostrata è simile a systrace.

Figura 6: UI di System Profiler.

Oltre ai dati disponibili in systrace, AGI mostra anche le informazioni sulle prestazioni della GPU. Per saperne di più sulla visualizzazione dei dati di profilazione del sistema, consulta Visualizzare un profilo di sistema AGI.

Per informazioni sulle impostazioni aggiuntive, consulta le opzioni di profilazione del sistema.

Profilare un frame

Per profilare un singolo frame della tua app, procedi nel seguente modo:

Nella schermata di avvio di AGI, fai clic su Acquisisci una nuova traccia per visualizzare la finestra di dialogo Acquisisci una nuova traccia. In alternativa, puoi fare clic sul pulsante Acquisisci traccia del profilo del frame.
Nell'elenco Tipo, seleziona Vulkan o OpenGL su ANGLE a seconda dell'API Graphics utilizzata dalla tua app. Assicurati di scegliere quello giusto, altrimenti AGI non acquisirà alcun comando grafico.
Nella sezione Inizio e durata, imposta Inizia da su Manuale. Se hai fatto clic sul pulsante Acquisisci traccia profilo frame, questo passaggio è già stato completato.
Nella sezione Output, seleziona una directory di output per archiviare i file di traccia. Il campo Nome file dovrebbe essere compilato automaticamente, ma puoi anche modificarlo.
(Facoltativo) Alcune app generano un processo diverso di elaborazione della grafica. Per acquisire questo processo, specificane il nome.
Fai clic su OK. L'app viene avviata sul dispositivo Android e viene visualizzata una finestra popup con un pulsante Avvia.
Fai clic sul pulsante Avvia e attendi alcuni secondi per il completamento della profilazione.
Fai clic su Apri traccia per visualizzare i dati di profilazione. Per informazioni su ciascun riquadro nell'interfaccia utente di Frame Profiler, consulta la panoramica della profilazione dei frame.

Per informazioni sulle impostazioni aggiuntive, consulta le opzioni di profilazione dei frame.