Mecanismos nativos e reservados

Começar a usar o Vulkan no Android

O Vulkan é a principal API gráfica de baixo nível no Android. O Vulkan oferece o desempenho ideal para jogos que implementam o próprio mecanismo e renderizador.

Para implementar o Vulkan no seu mecanismo de jogo, você precisa:

• Identificar quais dispositivos Android usar com o Vulkan
• Entender as desvantagens de oferecer suporte a dispositivos Android mais antigos
• Adicionar o Vulkan ao destino de build do Android
• Escolher um compilador de shader para criar o SPIR-V para Vulkan
• Determinar a versão disponível da API do Vulkan durante a execução
• Saber como otimizar suas operações de renderização do Vulkan com perfis, ritmo de frames e pré-rotação
• Selecionar ferramentas gráficas para depuração e análise de desempenho

Observação: para mais informações sobre como usar o Vulkan no Android com os mecanismos de jogo do Unity ou Unreal, consulte:
• Vulkan no Unity
• Vulkan no Unreal

Escolher as especificações mínimas do dispositivo para o Vulkan

O Vulkan está disponível no Android 7.0 (nível 24 da API) e versões mais recentes. Nem todos os dispositivos com o Android 7.0 ou versões mais recentes oferecem suporte ao Vulkan. Você precisa determinar a quais dispositivos Android compatíveis com Vulkan seu jogo oferece suporte.

Recomendações

Use as especificações abaixo como requisitos mínimos para oferecer suporte ao Vulkan:

• O dispositivo está executando o Android 10.0 (nível 29 da API) ou mais recente
• O dispositivo oferece suporte à versão 1.1 ou mais recente da API do Vulkan
• O dispositivo tem funções e recursos de hardware compatíveis com o perfil de referência do Android de 2022

Observação: o suporte ao Vulkan 1.1 é um requisito para novos dispositivos Android de 64 bits a partir do Android 10.0. O perfil de referência do Android de 2022 também define a versão mínima da API do Vulkan como a 1.1. A maioria dos dispositivos compatíveis com o Vulkan 1.1, mas não todos, é compatível com o perfil de referência do Android de 2022. Para estatísticas de compatibilidade, acesse o Painel de distribuição.

Suporte a dispositivos mais antigos

Se o jogo for projetado para ser executado em uma grande variedade de dispositivos com vários níveis de recursos gráficos, talvez seja necessário oferecer suporte a dispositivos mais antigos que os recomendados em Escolher especificações mínimas de dispositivos para o Vulkan. Antes de oferecer suporte a dispositivos mais antigos, avalie se o Vulkan oferece benefícios para seu jogo. Jogos que têm muitas chamadas de desenho e que usam o OpenGL ES podem ter uma sobrecarga significativa do driver devido ao alto custo de fazer chamadas de desenho no OpenGL ES. Esses jogos podem se tornar limitados pela CPU ao gastar grandes partes do tempo de renderização de frames no driver gráfico. Os jogos também podem ter reduções significativas no uso de CPU e energia ao mudar do OpenGL ES para o Vulkan. Isso é especialmente aplicável se o jogo tiver cenas complexas que não podem usar a instância de maneira eficaz para reduzir chamadas de desenho. Ao segmentar dispositivos mais antigos, inclua suporte à renderização do OpenGL ES como substituto, já que alguns dispositivos na lista de dispositivos de destino podem ter implementações do Vulkan que não podem executar o jogo de maneira confiável.

Talvez você não queira oferecer suporte a dispositivos mais antigos compatíveis com o Vulkan porque eles não têm desempenho e recursos ideais ou têm problemas de estabilidade.

Desempenho e recursos

Dispositivos Android mais antigos compatíveis com o Vulkan podem não ter o desempenho de renderização ou suporte de hardware ideais para os recursos necessários para executar o jogo. Isso é muito provável se o jogo tiver gráficos de alta fidelidade e o Vulkan for a única API de destino no Android. Muitos dispositivos mais antigos estão limitados à versão 1.0.3 da API do Vulkan e, muitas vezes, não incluem as extensões do Vulkan amplamente usadas disponíveis em hardwares mais modernos.

Estabilidade

Dispositivos Android mais antigos podem estar usando drivers do Vulkan desatualizados. Essas versões do driver podem incluir bugs que afetam a estabilidade do jogo. Resolver bugs de driver pode envolver uma quantidade significativa de tempo de teste e engenharia.

Adicionar o Vulkan ao seu projeto

Para adicionar o Vulkan ao seu projeto, você precisa:

• Incluir cabeçalhos da API do Vulkan
• Compilar o código de shader para o SPIR-V
• Chamar a API do Vulkan durante a execução

Incluir cabeçalhos da API do Vulkan

Seu jogo precisa incluir os arquivos principais da API do Vulkan para compilar o código que usa o Vulkan. É possível encontrar uma cópia dos cabeçalhos do Vulkan no Android NDK ou empacotada nas versões do SDK do Vulkan (link em inglês). As versões do NDK incluem apenas cabeçalhos do Vulkan disponíveis no momento do lançamento do NDK. Se você usa cabeçalhos do Vulkan do NDK, use a versão 25 ou mais recente do NDK, que inclui arquivos de cabeçalho com suporte à versão 1.3 do Vulkan. O SDK do Vulkan tem a versão mais atual dos cabeçalhos.

Compilar o código de shader para o SPIR-V

A API do Vulkan espera que os programas de shader sejam fornecidos no formato intermediário binário SPIR-V. Essa convenção é diferente do OpenGL ES, em que você pode enviar o código-fonte escrito na OpenGL Shading Language (GLSL) como strings de texto. Use um compilador de shader para compilar o código escrito em uma linguagem de sombreador, como GLSL ou High-level Shader Language (HLSL), e compilá-lo em módulos SPIR-V para uso com o Vulkan.

O compilador shaderc pode ser usado para compilar programas de shader escritos em GLSL para SPIR-V. Se o jogo usa HLSL, o DirectXShaderCompiler oferece suporte à saída SPIR-V (links em inglês). Normalmente, você compila programas de shader off-line como parte do processo de build de recursos do jogo e inclui os módulos SPIR-V como parte dos recursos de execução.

Chamar a API do Vulkan durante a execução

Para chamar a API do Vulkan, o jogo precisa extrair ponteiros de função para chamadas da API do Vulkan. A maneira mais direta de fazer isso é fazer a vinculação da biblioteca compartilhada libvulkan.so, incluída no Android NDK. Vincular à biblioteca tem duas desvantagens: sobrecarga extra de envio de funções e limitações de quais ponteiros de função da API do Vulkan são resolvidos automaticamente.

Quando você chama uma função da API do Vulkan, o controle passa por uma tabela de despacho gerenciada por uma construção chamada carregador do Vulkan. O Android usa a própria implementação de carregador do Vulkan (link em inglês) e não o carregador LunarG. Esse sistema de carregador faz parte da arquitetura de camadas da API do Vulkan. A vinculação à biblioteca do sistema no tempo de build resulta em um nível de despacho extra para uma determinada chamada de API. Embora a sobrecarga seja pequena, ela pode ser perceptível para jogos que realizam altos volumes de chamadas do Vulkan.

Em geral, a biblioteca do sistema resolve apenas ponteiros para funções do Vulkan que são consideradas parte da API principal. O Vulkan tem um grande número de extensões, que definem outras funções do Vulkan, muitas das quais não são resolvidas automaticamente pela biblioteca do sistema. É necessário resolver manualmente os ponteiros para essas funções do Vulkan antes de usá-las.

Para atenuar esses problemas, resolva dinamicamente os ponteiros para todas as funções do Vulkan que você pretende usar durante a execução. Uma maneira de fazer isso é usando uma biblioteca de meta carregador de código aberto, como volk. O jogo de exemplo AGDKTunnel integra o volk para essa finalidade. Se você estiver usando uma biblioteca de meta carregadores, não vincule a biblioteca compartilhada libvulkan.so nos scripts de build.

Determinar a versão disponível da API do Vulkan

O Android oferece suporte a estas versões da API do Vulkan:

• 1.0.3
• 1.1
• 1.3

O número de versão mais alto da API do Vulkan disponível em um determinado dispositivo é determinado pela versão do Android e pelo suporte ao driver do Vulkan.

Versão do Android

O suporte da plataforma a uma versão da API do Vulkan depende de uma versão mínima do Android (nível da API):

• 1.3 — Android 13.0 (nível 33 da API) e versões mais recentes
• 1.1 — Android 10.0 (nível 29 da API) e versões mais recentes
• 1.0.3 — Android 7.0 (nível 24 da API) e versões mais recentes

Suporte para drivers do Vulkan

O suporte da plataforma Android a uma versão da API do Vulkan não garante que a versão da API ofereça suporte ao driver do Vulkan do dispositivo. Um dispositivo com o Android 13 pode oferecer suporte apenas à versão 1.1 da API do Vulkan.

Ao inicializar o Vulkan, não solicite uma versão da API mais recente que:

• A versão máxima da API do Vulkan para a versão do Android em execução no dispositivo
• A versão da API do Vulkan informada por vkEnumerateInstanceVersion (link em inglês)
• A versão da API do Vulkan informada pela propriedade apiVersion da estrutura VkPhysicalDeviceProperties (link em inglês)

Confira abaixo um exemplo de como determinar a versão mais alta com suporte da API do Vulkan:

// Minimum Android API levels for Vulkan 1.3/1.1 version support
static constexpr int kMinimum_vk13_api_level = 33;
static constexpr int kMinimum_vk11_api_level = 29;

uint32_t GetHighestSupportedVulkanVersion(VkPhysicalDevice physical_device) {
  uint32_t instance_api_version = 0;
  vkEnumerateInstanceVersion(&instance_api_version);

  VkPhysicalDeviceProperties device_properties;
  vkGetPhysicalDeviceProperties(physical_device, &device_properties);

  // Instance and device versions don't have to match, use the lowest version
  // number for API support if they don't.
  const uint32_t driver_api_version =
      (instance_api_version < device_properties.apiVersion) ?
      instance_api_version : device_properties.apiVersion;

  const int device_api_level = android_get_device_api_level();
  if (device_api_level >= kMinimum_vk13_api_level &&
      driver_api_version >= VK_API_VERSION_1_3) {
    return VK_API_VERSION_1_3;
  } else if (device_api_level >= kMinimum_vk11_api_level &&
             driver_api_version >= VK_API_VERSION_1_1) {
    return VK_API_VERSION_1_1;
  }
  return VK_API_VERSION_1_0;
}

Determinar a compatibilidade do perfil do Vulkan

Os perfis do Vulkan são arquivos JSON que definem um conjunto de recursos, extensões, funcionalidades e limites mínimos de parâmetros necessários que um dispositivo Vulkan precisa oferecer suporte para ser compatível com o perfil. Para determinar se um dispositivo é compatível com um perfil específico do Vulkan, como o perfil de referência do Android de 2022, use a biblioteca da API Vulkan Profiles (link em inglês) de código aberto. Você também pode analisar o arquivo JSON de perfil e consultar os recursos do dispositivo usando as APIs do Vulkan relevantes para determinar a compatibilidade do perfil.

Perfis do Vulkan

O Android usa perfis do Vulkan, que define quais recursos e extensões estão disponíveis para cada um dos dispositivos com Android.

O perfil de referência do Android (ABP, na sigla em inglês) é a primeira tentativa de criar um perfil do Vulkan. ABP2021 e ABP2022 são perfis de versões anteriores destinadas a abranger mais de 85% dos dispositivos ativos naquele momento. Não haverá um novo ABP a partir de agora.

Os perfis do Vulkan para Android (VPA, na sigla em inglês) são um novo perfil voltado para o futuro que visa refletir as necessidades dos desenvolvedores de software e oferecer recursos consistentes assim que os desenvolvedores de hardware possam oferecê-los. O VPA15_minimums é o primeiro perfil do Android 15, e haverá um novo VPA todo ano para cobrir cada versão principal do Android.

Implementar o ritmo de frames

O ritmo adequado de frames é essencial para proporcionar uma experiência de jogabilidade de alta qualidade. O Android Game Development Kit inclui a biblioteca Frame Pacing para ajudar seu jogo a atingir o ritmo ideal de frames. Para mais detalhes de implementação, consulte Integrar a Android Frame Pacing ao renderizador Vulkan.

Implementar a pré-rotação

Os dispositivos Android podem mostrar telas em várias orientações. A orientação do dispositivo pode ser diferente da orientação da superfície de renderização. Ao contrário do OpenGL ES no Android, o Vulkan não processa discrepâncias entre os dois. Para entender como funciona o processo de orientação e o método ideal para lidar com diferenças de orientação ao usar o Vulkan, consulte Processar a rotação do dispositivo com a pré-rotação do Vulkan.

Resolver problemas e criar perfis de renderização do Vulkan

Várias ferramentas estão disponíveis para ajudar a diagnosticar problemas de renderização e de desempenho com o código de renderização do Vulkan.

Para saber mais sobre as ferramentas de depuração e criação de perfil do Vulkan, confira a seção Ferramentas e recursos avançados.

Camadas de validação do Vulkan

As camadas de validação do Vulkan são bibliotecas de execução que podem ser ativadas para inspecionar as chamadas de API do Vulkan e fornecer avisos ou erros sobre o uso incorreto ou não ideal. Essas camadas não estão ativas por padrão, porque o processo de validação adiciona sobrecarga durante a execução e afeta o desempenho do jogo. Para informações sobre como usar camadas de validação com seu jogo, consulte Como depurar com a camada de validação (link em inglês).

Observação: alguns fornecedores de GPU oferecem bibliotecas de camadas de validação específicas para as GPUs, além das camadas de validação padrão do Vulkan. Use as camadas de validação específicas da GPU para receber feedback direcionado sobre GPUs específicas. É possível fazer o download dessas camadas no site do desenvolvedor do fornecedor da GPU.

Ferramentas de captura de frames

Use ferramentas de captura de frames para gravar e reproduzir as chamadas de API do Vulkan feitas durante um frame de jogo. Essas ferramentas permitem:

• Conferir informações e visualizações de recursos gráficos ativos
• Conferir a sequência das chamadas de API feitas pelo jogo e os parâmetros de API
• Analisar o estado do pipeline de gráficos no momento de uma chamada de desenho
• Conferir os resultados da renderização até uma chamada de desenho específica no frame

Use a ferramenta de código aberto RenderDoc (link em inglês) para capturar frames de jogos em execução no Android. O RenderDoc tem suporte à captura de frames do Vulkan e do OpenGL ES.

O Android GPU Inspector (AGI) também pode ser usado para capturar frames do Vulkan.

Ferramentas de análise de desempenho

Use ferramentas de análise de desempenho para investigar problemas de renderização no jogo que causam frame rates abaixo do ideal. Os fornecedores individuais de GPUs oferecem ferramentas projetadas para criar perfis para seu jogo e fornecer dados de desempenho específicos para as respectivas arquiteturas de GPU. As características de desempenho e os gargalos do jogo podem variar significativamente ao renderizar em GPUs de diferentes fornecedores ou até mesmo em diferentes gerações de GPUs do mesmo fornecedor.

Você também pode usar o Android GPU Inspector para coletar e analisar dados de desempenho. Ao contrário das ferramentas do fornecedor, o Android GPU Inspector é compatível com várias GPUs de diferentes fornecedores. No entanto, o Android GPU Inspector não tem suporte a dispositivos Android mais antigos e pode não ser compatível com todos os novos dispositivos.

Melhorar os testes do Vulkan com o CTS-D

Os fabricantes de dispositivos Android usam o conjunto de teste de compatibilidade (CTS) para ajudar a garantir que os dispositivos deles sejam compatíveis. Os CTS com tecnologia de desenvolvedor (CTS-D, na sigla em inglês) são testes enviados por desenvolvedores de apps Android para garantir que os futuros dispositivos Android atendam aos casos de uso e possam executar os apps com facilidade e sem bugs.

Se você conseguir acionar um novo bug no aplicativo Vulkan que afeta qualquer dispositivo Android específico, envie uma nova proposta de teste, descrevendo o problema e maneiras de verificá-lo. Isso garante que o problema seja corrigido em uma atualização futura do dispositivo e também garante que o mesmo bug não aconteça em nenhum outro dispositivo.

Confira o processo de envio do CTS para instruções detalhadas sobre como enviar a proposta de teste.