Plug-in VkQuality do mecanismo para Unity

O plug-in VkQuality para o mecanismo Unity fornece recomendações no momento da inicialização da API gráfica Vulkan ou OpenGL ES, para usar no seu jogo em dispositivos específicos.

A VkQuality recomenda o Vulkan em um conjunto de dispositivos mais restrito do que a lista de permissões padrão do mecanismo do Unity. Use o VkQuality para aproveitar os benefícios de desempenho do Vulkan e limitar o uso do Vulkan a dispositivos mais recentes com drivers gráficos mais novos, o que limita a exposição do jogo a problemas de driver. O VkQuality só faz recomendações de qualidade, não garantias, já que ainda é possível encontrar problemas de driver em dispositivos recomendados. O VkQuality oferece suporte a listas personalizadas, que permitem adicionar ou remover recomendações de dispositivos para seu jogo.

Ativar o Vulkan no seu jogo do mecanismo do Unity

A VkQuality exige que seu jogo tenha os renderizadores OpenGL ES e Vulkan ativados nas configurações do projeto do Unity. Ative os renderizadores usando a opção Auto Graphics API ou configurando manualmente as APIs gráficas.

Instalar o plug-in VkQuality para o mecanismo do Unity

Faça o download do plug-in VkQuality no GitHub. O plug-in é compatível com o Unity 2021 e versões mais recentes. Use o Unity 2021 LTS ou uma versão mais recente para ativar o Vulkan no Android. O pacote do plug-in contém um projeto de exemplo básico que usa o plug-in para definir a API gráfica na inicialização e, em seguida, exibe uma string definida como a API de gráficos ativos do dispositivo.

Gerenciar a lista de recomendações da Vulkan do VkQuality

A VkQuality inclui uma lista de recomendações padrão de dispositivos compatíveis. Para informações sobre como usar uma lista de recomendações personalizadas, consulte a seção Usar uma lista de recomendações personalizadas.

A lista de recomendações inclui três categorias:

  • Lista de permissões de dispositivos Vulkan
  • Lista de permissões de recomendação de GPU
  • Lista de bloqueio de recomendações da GPU

Correspondências da lista de permissões de dispositivos

O VkQuality primeiro verifica se o dispositivo ativo está incluído na lista de permissões e se ele está executando a versão mínima do Android e a versão do driver do Vulkan especificada na lista de permissões do dispositivo. Se esses critérios forem atendidos, a VkQuality vai recomendar o Vulkan retornando o valor da enumeração RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH.

Se o dispositivo estiver na lista de permissões, mas estiver executando uma versão do Android ou do driver abaixo do mínimo especificado na lista de permissões, a VkQuality recomenda o OpenGL ES retornando RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER.

Correspondências de recomendação de GPU

Se nenhuma correspondência de dispositivo for encontrada na lista de permissões, o VkQuality avaliará o modelo da GPU e a versão do driver em relação às listas de permissão e negação das recomendações da GPU. Se o modelo da GPU e a versão do driver corresponderem a uma entrada na lista de permissões de recomendação da GPU, a VkQuality recomenda o Vulkan retornando a constante de enumeração RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH.

Se o modelo da GPU e a versão do driver corresponderem a uma entrada na lista de bloqueio de recomendações de GPU, a VkQuality recomenda o OpenGL ES retornando RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH.

Recomendações sem correspondência

Se nenhuma correspondência for encontrada, a VkQuality vai recomendar o Vulkan se o nível da API do Android do dispositivo em execução for igual ou mais recente que o nível da API Future na lista de recomendações. A lista de recomendações padrão tem um nível de API Future de 36, o que significa que, em dispositivos sem correspondência que executam a API de nível 36 ou mais recente, a VkQuality retorna a constante de enumeração RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID.

Se nenhuma correspondência for encontrada na lista de permissões de dispositivos ou nas listas de recomendações de GPU e o nível da API do dispositivo estiver abaixo do nível Future da API, a VkQuality recomenda o OpenGL ES retornando RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH.

Adicionar o arquivo VkQuality ao seu projeto

O plug-in VkQuality é o arquivo VkQuality-1.x.x.aar localizado no diretório Assets/Android/Plugins do arquivo de pacotes transferido por download. O número real da versão do arquivo .aar corresponde ao número da versão do nome do arquivo do pacote. Para instalar o plug-in, siga estas etapas:

  1. Copie o arquivo .aar para o diretório Assets/Android/Plugins do projeto. Crie os subdiretórios Android e Plugins necessários, se eles não existirem.
O arquivo .aar VkQuality no diretório do projeto necessário.
Figura 1.O arquivo .aar VkQuality no diretório do projeto necessário.
  1. Selecione o arquivo de plug-in VkQuality-1.x.x na hierarquia Project do Unity para exibir as Import Settings no painel Inspector. Verifique se a plataforma Android está marcada.
Figura 2. Configurações de importação da plataforma de plug-ins VkQuality.
Figura 2. Configurações de importação da plataforma de plug-ins VkQuality.

Usar uma atividade personalizada para chamar VkQuality

Ao contrário dos plug-ins comuns do mecanismo Unity, o VkQuality precisa ser executado para receber uma recomendação da API gráfica antes que o mecanismo do Unity seja inicializado. Em seguida, use o recurso de argumentos de linha de comando do player do Unity para definir a API gráfica com base na recomendação da VkQuality. No Android, a transmissão de argumentos de linha de comando exige que o comportamento padrão de UnityPlayerActivity seja substituído criando uma atividade personalizada.

Se o jogo já estiver usando uma atividade personalizada, consulte a seção Adicionar VkQuality a uma atividade personalizada. Para criar uma nova atividade personalizada para seu jogo, consulte Adicionar uma atividade personalizada ao seu projeto do Unity a seguir.

Adicionar uma atividade personalizada ao seu projeto do mecanismo do Unity

Um exemplo de atividade personalizada que usa VkQuality está incluído no pacote de plug-in em Assets/Plugins/Android/VkQualityTestActivity.java. Para personalizar o arquivo e usá-lo no jogo, siga estas etapas:

  1. Copie o arquivo VkQualityTestActivity.java para o diretório Assets/Plugins/Android.
  2. Renomeie-o para algo adequado ao jogo (por exemplo, MyGameActivity.java).
  3. Abra o arquivo em um editor de texto.
  4. Altere o nome da classe de VkQualityTestActivity para o nome que você forneceu ao arquivo (por exemplo, MyGameActivity.java).
  5. Mude o nome do pacote de com.google.android.games.VkQualityTest para corresponder ao valor do campo Package Name na categoria Player das configurações do projeto do Unity em Other Settings (por exemplo, com.mycompany.mygame).
  6. Salve e feche o arquivo.

Adicione um arquivo de manifesto personalizado que faça referência à sua atividade personalizada e instrua o Unity a usar esse arquivo:

  1. Copie o arquivo AndroidManifest.xml do diretório Assets/Plugins/Android do pacote de plug-in para o diretório Asset/Plugins/Android do projeto.
  2. Abra o arquivo em um editor de texto.
  3. Mude o valor da configuração activity android:name de com.google.android.games.VkQualityTest.VkQualityTestActivity para os nomes de pacote e atividade usados nas etapas anteriores (por exemplo, com.mycompany.mygame.MyGameActivity).
  4. Salve e feche o arquivo.
  5. Abra a janela de configurações do Unity e selecione as configurações do Player. Expanda a seção Configurações de publicação e marque a caixa de seleção Manifesto principal personalizado.
Figura 3.A opção Custom Main Manifest nas configurações do Unity Player.
Figura 3.A opção Custom Main Manifest nas configurações do Player do Unity.

Seu projeto agora está configurado para usar a atividade personalizada que chama VkQuality na inicialização e escolhe Vulkan ou OpenGL ES com base na recomendação VkQuality.

Adicionar VkQuality a uma atividade personalizada que já existe

Se o jogo já tiver uma atividade personalizada substituindo a UnityPlayerActivity padrão, integre as recomendações da VkQuality adicionando o seguinte código:

Primeiro, adicione a instrução de importação da VkQuality à lista de importações na parte de cima do arquivo de atividade personalizada:

Kotlin

import com.google.android.games.vkquality.VKQuality;

Java

import com.google.android.games.vkquality.VKQuality;

Em seguida, crie algumas constantes no corpo da classe Activity para as opções da API gráfica:

Kotlin

companion object {
  private const val OVERRIDE_NONE = 0
  private const val OVERRIDE_GLES = 1
  private const val OVERRIDE_VULKAN = 2

Java

private static final int OVERRIDE_NONE = 0;
private static final int OVERRIDE_GLES = 1;
private static final int OVERRIDE_VULKAN = 2;

Crie uma variável para rastrear a seleção da API:

Kotlin

private var apiOverride = OVERRIDE_NONE

Java

private int apiOverride = OVERRIDE_NONE;

Adicione a seguinte função à classe Activity:

Kotlin

private fun CheckVkQuality() {
    val vkQuality = VKQuality(this)
    val startResult = vkQuality.StartVkQuality("")
    if (startResult == VKQuality.INIT_SUCCESS) {
        // In the current release, we can assume GetVkQuality is
        // ready as soon as StartVkQuality has returned success.
        val getResult = vkQuality.GetVkQuality()
        LogVkQualityResult(getResult)
        apiOverride =
            when (getResult) {
                VKQuality.RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH,
                VKQuality.RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH,
                VKQuality.RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID -> OVERRIDE_VULKAN
                VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE,
                VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER,
                VKQuality.RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH,
                VKQuality.RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH -> OVERRIDE_GLES
                else -> OVERRIDE_GLES
            }
        vkQuality.StopVkQuality()
    } else {
        Log.e("VKQUALITY", "VkQuality start failed with result: $startResult")
    }
}

Java

private void CheckVkQuality() {
  VKQuality vkQuality = new VKQuality(this);
  // An empty string specifies use of the default
  // built-in device list file.
  int startResult = vkQuality.StartVkQuality("");
  if (startResult == VKQuality.INIT_SUCCESS) {
      // In the current release, we can assume GetVkQuality is
      // ready as soon as StartVkQuality has returned success.
      int getResult = vkQuality.GetVkQuality();

      switch (getResult) {
          case VKQuality.RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH:
          case VKQuality.RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH:
          case VKQuality.RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID:
              apiOverride = OVERRIDE_VULKAN;
              break;
          case VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE:
          case VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER:
          case VKQuality.RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH:
          case VKQuality.RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH:
          default:
              apiOverride = OVERRIDE_GLES;
              break;
      }
      vkQuality.StopVkQuality();
  } else {
      Log.e("VKQUALITY", "VkQuality start failed with result: " + startResult);
  }
}

Chame a função CheckVkQuality na parte superior de uma função de substituição onCreate() antes de chamar a implementação da classe de base:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  CheckVkQuality()
  super.onCreate(savedInstanceState)
}

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
    CheckVkQuality();
    super.onCreate(savedInstanceState);
}

Por fim, adicione uma substituição da função updateUnityCommandLineArguments() que usa o valor de apiOverride para transmitir um argumento de linha de comando para o mecanismo do Unity especificando qual API gráfica usar:

Kotlin

override fun updateUnityCommandLineArguments(cmdLine: String): String {
  if (apiOverride == OVERRIDE_VULKAN) {
      Log.i("VKQUALITY", "Passing -force-vulkan")
      return appendCommandLineArgument(cmdLine, "-force-vulkan")
  } else if (apiOverride == OVERRIDE_GLES) {
      Log.i("VKQUALITY", "Passing -force-gles")
      return appendCommandLineArgument(cmdLine, "-force-gles")
  }
  Log.i("VKQUALITY", "No override passed")
  // let Unity pick the Graphics API based on PlayerSettings
  return cmdLine
}

private fun appendCommandLineArgument(cmdLine: String, arg: String?): String {
    return if (arg == null || arg.isEmpty()) cmdLine
    else if (cmdLine == null || cmdLine.isEmpty()) arg else "$cmdLine $arg"
}

Java

@Override protected String updateUnityCommandLineArguments(String cmdLine)
{
    if (apiOverride == OVERRIDE_VULKAN) {
        Log.i("VKQUALITY", "Passing -force-vulkan");
        return appendCommandLineArgument(cmdLine, "-force-vulkan");
    }
    else if (apiOverride == OVERRIDE_GLES) {
        Log.i("VKQUALITY", "Passing -force-gles");
        return appendCommandLineArgument(cmdLine, "-force-gles");
    }
    Log.i("VKQUALITY", "No override passed");
    // let Unity pick the Graphics API based on PlayerSettings
    return cmdLine;
}

private String appendCommandLineArgument(String cmdLine, String arg) {
    if (arg == null || arg.isEmpty())
        return cmdLine;
    else if (cmdLine == null || cmdLine.isEmpty())
        return arg;
    else
        return cmdLine + " " + arg;
}

Sua atividade personalizada agora chama VkQuality na inicialização e escolhe Vulkan ou OpenGL ES com base na recomendação da VkQuality.

Usar uma lista de recomendações personalizada

Especifique um arquivo de lista de recomendações personalizada transmitindo o nome do arquivo que contém a lista para StartVkQuality(), em vez de transmitir uma string vazia:

Kotlin

val startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq")

Java

int startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq");

O VkQuality procura primeiro o arquivo no diretório de armazenamento interno do aplicativo. Se o arquivo não estiver no armazenamento interno, o VkQuality vai tentar carregar o arquivo dos recursos do pacote de apps. Se o arquivo não estiver em nenhum dos locais, VkQuality vai retornar o valor de enumeração ERROR_MISSING_DATA_FILE.

Para criar um arquivo de lista de recomendações personalizada, use a ferramenta VkQuality List Editor, localizada no repositório do GitHub (link em inglês). A documentação da ferramenta está localizada no arquivo README (em inglês).