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:
- Copie o arquivo .aar para o diretório
Assets/Android/Plugins
do projeto. Crie os subdiretóriosAndroid
ePlugins
necessários, se eles não existirem.
![O arquivo .aar VkQuality no diretório do projeto necessário.](https://developer.android.com/static/images/games/engines/unity/unity-vkquality-unityassets.png?authuser=6&hl=pt)
- 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.](https://developer.android.com/static/images/games/engines/unity/unity-vkquality-unityplugin.png?authuser=6&hl=pt)
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:
- Copie o arquivo
VkQualityTestActivity.java
para o diretórioAssets/Plugins/Android
. - Renomeie-o para algo adequado ao jogo (por exemplo,
MyGameActivity.java
). - Abra o arquivo em um editor de texto.
- Altere o nome da classe de
VkQualityTestActivity
para o nome que você forneceu ao arquivo (por exemplo,MyGameActivity.java
). - 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
). - 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:
- Copie o arquivo
AndroidManifest.xml
do diretórioAssets/Plugins/Android
do pacote de plug-in para o diretórioAsset/Plugins/Android
do projeto. - Abra o arquivo em um editor de texto.
- Mude o valor da configuração
activity android:name
decom.google.android.games.VkQualityTest.VkQualityTestActivity
para os nomes de pacote e atividade usados nas etapas anteriores (por exemplo,com.mycompany.mygame.MyGameActivity
). - Salve e feche o arquivo.
- 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.](https://developer.android.com/static/images/games/engines/unity/unity-vkquality-unitymanifest.png?authuser=6&hl=pt)
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).