Guia de início rápido do Android GPU Inspector

Este tópico descreve como executar a criação de perfil do sistema e a criação de perfis de frames no seu app Android usando o Android GPU Inspector (AGI).

Este guia de início rápido é destinado a desenvolvedores familiarizados com o desenvolvimento gráfico no Android.

Requisitos de computador

O computador que executa o AGI precisa atender a estes requisitos:

• É necessário ter um dos seguintes sistemas operacionais:

  • Windows: Windows 7 ou versão mais recente.

  • macOS: El Capitan (10.11) ou mais recente.

  • Linux: é necessário usar o Java JDK ou JRE 8 (ou mais recente) de 64 bits. O Ubuntu Trusty Tahr (14.04 ou mais recente) é recomendado.

• A ferramenta de linha de comando adb.

Fazer o download e instalar o AGI

Faça o download e instale o AGI no seu sistema operacional.

Requisitos de apps Android

Esta seção descreve os requisitos do app Android para o qual o perfil está sendo criado:

• O app Android precisa ser depurável. O atributo depurável no manifesto do Android precisa ser definido como true. Esse atributo permite as instrumentações adequadas do driver de gráficos. Para aplicativos Vulkan, esse atributo permite que o AGI adicione a própria camada Vulkan quando o aplicativo é iniciado.

  <application [...] android:debuggable="true">
  

Caso seu app use o Vulkan de forma nativa, o AGI também exigirá o seguinte:

• Seu app precisa ter as camadas de validação da Vulkan ativadas. Se elas não estiverem ativadas, você pode executar os seguintes comandos para forçar a execução do app com as camadas de validação incluídas no APK do 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
  

  Quando terminar a criação de perfil, você poderá desativar essas camadas de validação com os seguintes comandos:

  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
  

• O app não pode relatar avisos ou erros quando for executado com as camadas de validação da Vulkan ativadas. Corrija qualquer erro de validação da Vulkan antes da criação de perfil.

• Se você estiver usando drivers de GPU Beta, inclua os seguintes metadados na tag <application> do manifesto do Android:

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

Requisitos para dispositivos Android

O AGI tem os seguintes requisitos para dispositivos Android:

• Um dispositivo Android compatível com o Android 11 ou versão mais recente.

• Um cabo USB.

• A depuração do adb precisa estar ativada e o dispositivo precisa estar acessível por meio do adb. Se a opção Instalar via USB estiver presente, ative-a.

Validação do dispositivo

O AGI requer um driver de GPU compatível. Para garantir que ele forneça dados de criação de perfil válidos, o AGI executa uma verificação de validação na primeira vez que você conecta um novo dispositivo, o que leva cerca de dez segundos. Depois de passar na verificação, você pode usar o dispositivo para criar o perfil de apps Android.

Não perturbe o dispositivo durante a validação. Isso pode fazer com que o dispositivo falhe na validação. Se a validação do dispositivo falhar, mas estiver configurado corretamente, você poderá repetir a validação selecionando o dispositivo novamente.

A validação é uma etapa única para um dispositivo, e os resultados são armazenados em cache para uso futuro do AGI. No entanto, o AGI vai executar a validação novamente se a configuração do dispositivo mudar, por exemplo, se o driver da GPU ou a versão do Android forem atualizados.

Se um dispositivo estiver listado como compatível, o AGI vai passar na validação. Se o dispositivo não estiver listado, é provável que o driver da GPU seja incompatível com o AGI.

Se o dispositivo for compatível, mas a validação falhar

Verifique se você atendeu a todos os requisitos do Android e de computador descritos nas seções anteriores e se o dispositivo está conectado corretamente ao computador com um cabo USB.

Se todos os requisitos forem atendidos, registre um problema em nosso repositório do GitHub que descreva o comportamento.

Se o dispositivo não for compatível

Estamos trabalhando com nossos parceiros de OEM para adicionar suporte a mais dispositivos. Registre um problema no nosso repositório do GitHub para solicitar suporte com um dispositivo.

Capturar dados de criação de perfil

As seções a seguir descrevem como capturar dados de criação de perfil e abrir o arquivo de rastro resultante para analisar os resultados.

Definir as configurações do Android

Antes de iniciar a criação de perfil, é necessário definir essas configurações de app Android e dispositivo, que especificam o app e o dispositivo para o perfil.

1. Com um cabo USB, conecte o dispositivo Android ao computador.

2. Inicie o AGI no seu computador.

   Na primeira vez que você iniciar o AGI, ele vai mostrar a tela Welcome, que solicitará o caminho para o executável do adb. O AGI salva essas configurações no arquivo .agic na pasta HOME. Se você já fez isso, pule esta etapa.

   

3. Insira o caminho para o executável adb no campo Caminho para adb. As caixas de seleção após esse campo são opcionais.

4. Clique em Get Started para mostrar a tela de inicialização.

   

5. Na tela de inicialização, clique em Capturar novo rastro. A caixa de diálogo Capture A New Trace vai aparecer. Como alternativa, você pode clicar no botão Capturar rastros de perfil do sistema.

   

6. Na seção Device and Type, selecione o dispositivo Android para o qual você quer criar um perfil. Se ele não aparecer na lista Device, clique na seta de atualização para atualizar a lista.

7. Na seção Aplicativo, selecione o app para o qual você quer criar um perfil. Se houver apenas uma atividade no pacote, você poderá selecioná-lo em vez da atividade.

   O AGI inclui um app de exemplo Vulkan. Para usar o app de exemplo em vez do seu, siga estas etapas:

   1. Clique no botão ... ao lado do campo Application.

      Isso mostra a caixa de diálogo Select an Application to Trace, que exibe uma lista de apps que são rastreáveis no dispositivo selecionado.

   2. Na caixa de texto Filtro, digite gapid para mostrar apenas aplicativos que contenham gapid no nome do pacote.

   3. Expanda o pacote, selecione com.google.android.gapid.VkSampleActivity e clique em OK.

      Isso retorna à caixa de diálogo Capture A New Trace, com o campo Application preenchido pelo app selecionado.

8. Na seção Aplicativo, deixe os outros campos vazios.

9. Clique em OK.

Você já pode usar o AGI para criar perfis do sistema e do frame.

Criar perfil de um sistema

Para criar um perfil de um sistema, siga estas etapas:

1. Na tela de inicialização do AGI, clique em Capture a new trace para mostrar a caixa de diálogo Capture System Profile.

2. Na lista Type, selecione System profile.

3. Na seção Início e duração, defina Início em como Manual e Duração como 2.

4. Na seção Opções de rastreamento, clique em Configurar. Uma lista de opções de criação de perfil será exibida.

   

5. Selecione os dados de criação de perfil que você quer capturar.

6. Na seção GPU, clique em Selecionar.

   Uma lista de contadores será exibida para seleção.

   

7. Clique em default para selecionar o conjunto de contadores padrão e clique em OK para retornar as opções de criação de perfil.

8. Clique em OK para retornar à caixa de diálogo principal Capture System Profile.

9. Na seção Saída, selecione um Diretório de saída para armazenar os arquivos de rastreamento gerados durante a criação de perfil. O campo File Name é preenchido automaticamente, mas ele também pode ser editado.

10. Clique em OK. O app selecionado será iniciado no dispositivo Android e uma janela pop-up será exibida com um botão Start.

11. Clique no botão Start para começar a capturar dados de criação de perfil e aguarde alguns segundos para que o processo seja concluído.

12. Clique em Abrir trace. A visualização inicial exibida é semelhante ao systrace.

    

    Além dos dados disponíveis no Systrace, o AGI também mostra informações de desempenho da GPU. Para saber mais sobre como visualizar dados de criação de perfil do sistema, consulte Ver um perfil do sistema AGI.

Para mais informações sobre outras configurações, consulte as opções de criação de perfil do sistema.

Criar perfil de um frame

Para criar um perfil de um frame individual no seu app, siga estas etapas:

1. Na tela de inicialização do AGI, clique em Capture a new trace para mostrar a caixa de diálogo Capture A New Trace. Como alternativa, você pode clicar no botão Capture Frame Profile trace.

2. Na lista Type, selecione Vulkan ou OpenGL on ANGLE, dependendo da API Graphics usada pelo app. Verifique se você está escolhendo a opção certa. Caso contrário, o AGI não capturará nenhum comando gráfico.

3. Na seção Início e duração, defina Início em como Manual. Se você clicou no botão Capture Frame Profile trace, esta etapa já está concluída.

4. Na seção Saída, selecione um Diretório de saída para armazenar os arquivos de rastreamento. O campo File Name é preenchido automaticamente, mas você também pode editá-lo.

5. Opcional:alguns apps geram um processo diferente que faz todo o processamento gráfico. Para capturar esse processo, especifique o nome dele.

6. Clique em OK. Isso inicia o app no dispositivo Android e mostra uma janela pop-up com um botão Start.

7. Clique no botão Start e aguarde alguns segundos para que a criação do perfil seja concluída.

8. Clique em Open Trace para visualizar os dados de criação de perfil. Para saber mais sobre cada painel na interface do Frame Profiler, consulte a Visão geral da criação de perfil do frame.

Para saber mais sobre outras configurações, consulte as opções de criação de perfil de frame.