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

Este tópico descreve como criar perfis de sistema e de frame no app Android usando o Android GPU Inspector (AGI).

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

Requisitos do computador

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

• Um destes sistemas operacionais:

  • Windows: Windows 7 ou mais recente.

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

  • Linux: é necessário o JDK ou JRE 8 de 64 bits do Java (ou mais recente); 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 para seu sistema operacional.

Requisitos do app Android

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

• O app Android precisa ser depurável. O atributo debuggable no manifesto do Android precisa ser definido como true. Esse atributo permite 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">
  

Se o app usa o Vulkan nativamente, o AGI também exige o seguinte:

• O app precisa ter camadas de validação do Vulkan ativadas. Se elas não estiverem ativadas, execute os comandos a seguir para forçar o app a ser executado 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 de criar o perfil, desative essas camadas de validação com os comandos a seguir:

  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 informar avisos ou erros quando é executado com as camadas de validação do Vulkan ativadas. Corrija qualquer erro de validação do Vulkan antes de criar o perfil.

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

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

Requisitos do dispositivo Android

O AGI tem os seguintes requisitos de dispositivo Android:

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

• Um cabo USB.

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

Validação do dispositivo

O AGI exige 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 perfis de apps Android.

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

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 for atualizada.

Se um dispositivo estiver listado como um dispositivo compatível, você poderá esperar que o AGI passe na validação. Se o dispositivo não estiver listado, o driver da GPU provavelmente será incompatível com o AGI.

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

Verifique se você atende a todos os requisitos do Android e requisitos do 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 no nosso repositório do GitHub descrevendo o comportamento.

Se o dispositivo não for compatível

Estamos trabalhando com nossos parceiros OEM para adicionar suporte a mais dispositivos. Você pode registrar um problema no nosso repositório do GitHub para solicitar suporte a 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 rastreamento resultante para analisar os resultados.

Configurar as definições do Android

Antes de começar a criação de perfil, configure essas definições do app e do dispositivo Android, que especificam o app e o dispositivo a serem criados.

1. Conecte o dispositivo Android ao computador usando um cabo USB.

2. Inicie o AGI no computador.

   Na primeira vez que você inicia o AGI, ele mostra a tela Welcome, que solicita o caminho para o executável 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 Path to 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 Capture a new trace. Isso mostra a caixa de diálogo Capture A New Trace. Como alternativa, clique no botão Capture System Profile trace.

   

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

7. Na seção Application, selecione o app que você quer criar. Se houver apenas uma atividade no pacote, selecione o pacote em vez da atividade.

   O AGI inclui um app Vulkan de exemplo. 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 mostra uma lista de apps que podem ser rastreados no dispositivo selecionado.

   2. Na caixa de texto Filter, digite gapid para mostrar apenas os aplicativos que contêm gapid no nome do pacote.

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

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

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

9. Clique em OK.

Agora você já pode usar o AGI para criar perfis de sistema e de frame.

Criar um perfil de sistema

Para criar um perfil de 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 Start and Duration, defina Start at como Manual, e Duration como 2.

4. Na seção Trace Options, clique em Configure. Isso mostra uma lista de opções de criação de perfil.

   

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

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

   Isso mostra uma lista de contadores a serem selecionados.

   

7. Clique em default para selecionar o conjunto de contadores padrão e clique em OK para retornar às 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 Output, selecione um Output Directory para armazenar os arquivos de rastreamento gerados durante a criação de perfil. O campo File Name é preenchido automaticamente, mas também pode ser editado.

10. Clique em OK. Isso inicia o app selecionado no dispositivo Android e mostra uma janela pop-up 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 termine.

12. Clique em Open Trace. A visualização inicial mostrada é semelhante ao systrace.

    

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

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

Criar um perfil de frame

Para criar um perfil de um frame individual do 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, clique no botão Capture Frame Profile trace.

2. Na lista Type , selecione Vulkan ou OpenGL on ANGLE , dependendo da API Graphics que o app usa. Escolha a opção correta. Caso contrário, o AGI não vai capturar comandos gráficos.

3. Na seção Start and Duration, defina Start at como Manual. Se você clicou no botão Capture Frame Profile trace, essa etapa já foi concluída.

4. Na seção Output, selecione um Output Directory para armazenar os arquivos de rastreamento. O campo File Name é preenchido automaticamente, mas também pode ser editado.

5. Opcional:alguns apps geram um processo diferente que faz todo o processamento de gráficos. 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 de perfil seja concluída.

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

Para informações sobre outras configurações, consulte Opções de criação de perfil de frame.