Plug-in VkQuality do mecanismo para Unity

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

O VkQuality recomenda o Vulkan em um conjunto de dispositivos mais restrito do que o Unity à lista de permissões padrão do mecanismo. Use o VkQuality para ter os benefícios de desempenho do Vulkan enquanto limita o uso do Vulkan a dispositivos mais novos com gráficos mais recentes o que limita a exposição do jogo a problemas de driver. Somente VkQuality faz recomendações de qualidade, não garantias, pois ainda é possível encontrar problemas de driver nos dispositivos recomendados. O VkQuality oferece suporte a listas personalizadas, que permite adicionar ou remover recomendações de dispositivos para sua jogo.

Observação: o VkQuality sempre recomenda o OpenGL ES em dispositivos mais antigos com Android. 9.0 (nível 28 da API) ou anterior ou não oferecem suporte ao menos para a versão 1.1 do Vulkan API. A VkQuality retorna o valor do tipo enumerado RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE. nesses dispositivos.

Ativar o Vulkan no jogo de mecanismo do Unity

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

Fazer o download do plug-in VkQuality para o mecanismo do Unity

Faça o download do plug-in VkQuality no GitHub. O plug-in é compatível com Unity 2021 e versões mais recentes. Use o Unity 2021 LTS ou mais recente para ativar 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 da API de gráficos ativos do dispositivo.

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

O VkQuality inclui uma lista padrão de recomendações de dispositivos com suporte. Para informações sobre como usar uma lista de recomendações personalizadas, consulte a seção Usar uma lista lista de recomendações.

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 de GPU

Correspondências da lista de permissões de dispositivos

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

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

Correspondências da recomendação de GPU

Se nenhuma correspondência de dispositivo for encontrada na lista de permissões, o VkQuality avaliará a Permitir e negar a versão do driver e do modelo da GPU de acordo com a recomendação da GPU listas. Se o modelo da GPU e a versão do driver corresponderem a uma entrada na GPU lista de permissões de recomendação, o VkQuality recomenda o Vulkan retornando o 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 GPU lista de bloqueio de recomendações, o VkQuality recomenda o OpenGL ES retornando RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH:

Recomendações sem correspondência

Se nenhuma correspondência for encontrada, o VkQuality recomendará o Vulkan se o nível da API do Android de o dispositivo em execução é igual ou maior que o nível da API futura no lista de recomendações. A lista de recomendações padrão tem um nível de API Future de 36, ou seja, em dispositivos sem correspondência com o nível 36 da API ou mais recente, o 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 de recomendações de GPU, e o nível da API do dispositivo estiver abaixo do nível futuro da API, VkQuality recomenda o OpenGL ES retornando RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH.

Adicione o arquivo VkQuality ao seu projeto

O plug-in VkQuality é o arquivo VkQuality-1.x.x.aar localizado na Diretório Assets/Android/Plugins do arquivo de pacotes transferido por download. O real o número da versão do arquivo .aar corresponde ao número da versão do pacote. nome do arquivo. 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 existem.

.

Figura 1.O arquivo .aar do VkQuality no diretório do projeto necessário.

1. Selecione o arquivo de plug-in VkQuality-1.x.x na hierarquia do Project do Unity. para abrir as Configurações de importação no painel Inspetor. Assegure-se de que Android está marcada.

Figura 2. As 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 do Unity, é necessário executar o VkQuality para conseguir uma da API de gráficos do Google antes da inicialização do mecanismo do Unity. Depois, você usa O recurso de argumentos de linha de comando do player do Unity para definir os API gráfica com base na recomendação VkQuality. No Android, transmitir os argumentos de linha de comando exigem a substituição do comportamento padrão do UnityPlayerActivity criando um objeto atividade.

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

Adicionar uma atividade personalizada ao projeto do mecanismo do Unity

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

1. Copie o arquivo VkQualityTestActivity.java no Assets/Plugins/Android.
2. Renomeie-o para algo apropriado ao seu jogo (por exemplo, MyGameActivity.java).
3. Abra o arquivo em um editor de texto.
4. Mude o nome da turma de VkQualityTestActivity para o nome que você deu à (por exemplo, MyGameActivity.java).
5. Mude o nome do pacote de com.google.android.games.VkQualityTest para Corresponde ao valor do campo Package Name nas configurações do seu projeto do Unity. Categoria Player 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 informe ao Unity para usar seu arquivo de manifesto personalizado:

1. Copie o arquivo AndroidManifest.xml do Assets/Plugins/Android. do pacote de plug-ins no Asset/Plugins/Android do projeto diretório.
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 o nomes de pacotes e atividades 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. Expandir a seção Configurações de publicação e verifique o Manifesto principal personalizado caixa de seleção.

.

Figura 3.A opção Manifesto principal personalizado nas configurações do Player do Unity.

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

Adicionar VkQuality a uma atividade personalizada já existente

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

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

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 o opções de 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 acompanhar 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);
  }
}

Chamar a função CheckVkQuality na parte de cima de uma substituição de onCreate(). antes de chamar a implementação da classe 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 VkQuality.

Usar uma lista de recomendações personalizadas

Especifique um arquivo de lista de recomendações personalizadas transmitindo o nome dele 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 armazenamento interno do seu aplicativo. diretório. Se o arquivo não estiver no armazenamento interno, o VkQuality tentará carregar o nos recursos do seu pacote de app. Se o arquivo não estiver em nenhum dos locais, VkQuality retorna o valor do tipo enumerado ERROR_MISSING_DATA_FILE.

Para criar um arquivo de lista de recomendações personalizadas, use o editor de lista VkQuality. localizada no repositório do GitHub. A documentação da está localizado em README.

Observação: para incluir um arquivo de lista de recomendações personalizadas nos recursos do seu pacote de app, faça o seguinte: exporte a lista do VkQuality List Editor usando a biblioteca .aar (em inglês). e coloque o arquivo .aar exportado na pasta Assets/Android/Plugins diretório. O Unity não incluirá o arquivo .vkq se você colocá-lo diretamente no Diretório Assets/Android/Plugins, ele precisa ser empacotado em uma biblioteca .aar. contêiner do Docker. A extensão de tipo de arquivo .vkq ainda é usada ao especificar o nome do arquivo de StartVkQuality().