Плагин движка VkQuality Unity

Плагин VkQuality для движка Unity предоставляет рекомендации по запуску графического API — Vulkan или OpenGL ES — для использования в вашей игре на определенных устройствах.

VkQuality рекомендует использовать Vulkan на более ограниченном наборе устройств, чем список разрешений движка Unity по умолчанию. Используйте VkQuality, чтобы получить преимущества Vulkan в производительности, одновременно ограничивая использование Vulkan новыми устройствами с новыми графическими драйверами, что ограничивает подверженность вашей игры проблемам с драйверами. VkQuality дает только рекомендации по качеству, а не гарантии, поскольку на рекомендуемых устройствах все еще можно столкнуться с проблемами драйверов. VkQuality поддерживает настраиваемые списки, что дает вам возможность добавлять или удалять рекомендации по устройствам для вашей игры.

Примечание. VkQuality всегда рекомендует OpenGL ES на старых устройствах под управлением Android 9.0 (уровень API 28) или ниже или не поддерживающих как минимум версию 1.1 API Vulkan. VkQuality возвращает значение перечисления RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE на этих устройствах.

Включите Vulkan в вашей игре на движке Unity.

VkQuality требует, чтобы в настройках проекта Unity в вашей игре были включены средства рендеринга OpenGL ES и Vulkan. Включите средства визуализации, используя параметр Auto Graphics API или вручную настроив графические API.

Загрузите плагин VkQuality для движка Unity.

Загрузите плагин VkQuality с GitHub . Плагин совместим с Unity 2021 и выше. Используйте Unity 2021 LTS или более позднюю версию, чтобы включить Vulkan на Android. Пакет плагина содержит базовый пример проекта, который использует плагин для установки графического API при запуске, а затем отображает строку, заданную для активного графического API устройства.

Управление списком рекомендаций VkQuality Vulkan

VkQuality включает список поддерживаемых устройств по умолчанию. Информацию об использовании настраиваемого списка рекомендаций см. в разделе «Использование настраиваемого списка рекомендаций» .

Список рекомендаций включает в себя три категории:

• Список разрешенных устройств Vulkan
• Список разрешенных рекомендаций по графическому процессору
• Список запрещенных рекомендаций по графическому процессору

Список разрешенных устройств соответствует

VkQuality сначала проверяет, включено ли активное устройство в список разрешенных устройств и работает ли на нем минимальная версия Android и версия драйвера Vulkan, указанная в списке разрешений для этого устройства. Если эти критерии соблюдены, VkQuality рекомендует Vulkan, возвращая значение перечисления RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH .

Если устройство находится в списке разрешений, но на нем установлена ​​версия Android или версия драйвера ниже минимальной, указанной для него в списке разрешений, VkQuality рекомендует OpenGL ES, возвращая RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER .

Рекомендации по графическому процессору совпадают

Если в списке разрешенных устройств не найдено ни одного соответствующего устройства, VkQuality оценивает модель графического процессора и версию драйвера по рекомендациям разрешенных и запрещенных списков графического процессора. Если модель графического процессора и версия драйвера соответствуют записи в списке разрешенных рекомендаций графического процессора, VkQuality рекомендует Vulkan, возвращая константу перечисления RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH .

Если модель графического процессора и версия драйвера совпадают с записью в списке запрещенных рекомендаций графического процессора, VkQuality рекомендует OpenGL ES, возвращая RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH .

Рекомендации без совпадения

Если совпадений не найдено, VkQuality рекомендует Vulkan, если уровень Android API работающего устройства равен или выше уровня Future API в списке рекомендаций. Список рекомендаций по умолчанию имеет уровень Future API 36. Это означает, что на несовпадающих устройствах с уровнем API 36 или выше VkQuality возвращает константу перечисления RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID .

Если в списке разрешенных устройств или списках рекомендаций графических процессоров совпадений не найдено, а уровень API устройства ниже уровня Future API, VkQuality рекомендует OpenGL ES, возвращая RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH .

Добавьте архивный файл VkQuality в свой проект.

Плагин VkQuality — это файл VkQuality-1.xxaar , расположенный в каталоге Assets/Android/Plugins скачанного архива пакета. Фактический номер версии файла .aar соответствует номеру версии имени архива пакета. Чтобы установить плагин, выполните следующие действия:

1. Скопируйте файл .aar в каталог Assets/Android/Plugins вашего проекта. (Создайте необходимые подкаталоги Android и Plugins , если они не существуют.)

Рисунок 1. Файл VkQuality .aar в нужном каталоге проекта.

1. Выберите файл плагина VkQuality-1.xx в иерархии проекта Unity, чтобы отобразить его настройки импорта на панели «Инспектор» . Убедитесь, что платформа Android проверена.

Рисунок 2. Настройки импорта платформы плагина VkQuality.

Используйте пользовательское действие для вызова VkQuality

В отличие от типичных плагинов движка Unity, VkQuality необходимо запустить для получения рекомендаций графического API до инициализации движка Unity. Затем вы используете функцию аргументов командной строки проигрывателя Unity, чтобы настроить графический API на основе рекомендации VkQuality. В Android передача аргументов командной строки требует переопределения поведения UnityPlayerActivity по умолчанию путем создания пользовательского действия .

Если ваша игра уже использует пользовательское действие, см. раздел «Добавление VkQuality к существующему пользовательскому действию» . Чтобы создать новое пользовательское действие для своей игры, см. раздел «Добавление пользовательского действия в проект Unity» ниже.

Добавьте пользовательское действие в свой проект движка Unity.

Пример пользовательского действия, использующего VkQuality, включен в пакет плагина в Assets/Plugins/Android/VkQualityTestActivity.java . Чтобы настроить файл и использовать его в своей игре, выполните следующие действия:

1. Скопируйте файл VkQualityTestActivity.java в каталог Assets/Plugins/Android .
2. Переименуйте его во что-нибудь подходящее для вашей игры (например, MyGameActivity.java ).
3. Откройте файл в текстовом редакторе.
4. Измените имя класса с VkQualityTestActivity на имя, которое вы дали файлу (например, MyGameActivity.java ).
5. Измените имя пакета с com.google.android.games.VkQualityTest , чтобы оно соответствовало значению поля «Имя пакета» в категории «Проигрыватель » настроек проекта Unity в разделе « Другие настройки» (например, com.mycompany.mygame ).
6. Сохраните и закройте файл.

Добавьте пользовательский файл манифеста, который ссылается на вашу пользовательскую активность, и сообщите Unity использовать ваш пользовательский файл манифеста:

1. Скопируйте файл AndroidManifest.xml из каталога Assets/Plugins/Android пакета плагина в каталог Asset/Plugins/Android вашего проекта.
2. Откройте файл в текстовом редакторе.
3. Измените значение activity android:name с com.google.android.games.VkQualityTest.VkQualityTestActivity на имена пакета и действия, которые вы использовали на предыдущих шагах (например, com.mycompany.mygame.MyGameActivity ).
4. Сохраните и закройте файл.
5. Откройте окно настроек Unity и выберите настройки проигрывателя . Разверните раздел «Настройки публикации» и установите флажок «Пользовательский основной манифест» .

Рисунок 3. Параметр Custom Main Manifest в настройках Unity Player .

Теперь ваш проект настроен на использование пользовательского действия, которое вызывает VkQuality при запуске и выбирает Vulkan или OpenGL ES на основе рекомендации VkQuality.

Добавьте VkQuality в существующее пользовательское действие.

Если в вашей игре уже есть пользовательская активность, переопределяющая UnityPlayerActivity по умолчанию, интегрируйте рекомендации VkQuality, добавив следующий код:

Сначала добавьте оператор импорта VkQuality в список импорта в верхней части файла пользовательской активности:

Котлин

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

Ява

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

Затем создайте несколько констант в теле вашего класса Activity для выбора графического API:

Котлин

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

Ява

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

Создайте переменную для отслеживания выбора API:

Котлин

private var apiOverride = OVERRIDE_NONE

Ява

private int apiOverride = OVERRIDE_NONE;

Добавьте следующую функцию в свой класс Activity :

Котлин

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")
    }
}

Ява

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);
  }
}

Вызовите функцию CheckVkQuality из верхней части переопределяющей функции onCreate() перед вызовом реализации базового класса:

Котлин

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

Ява

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

Наконец, добавьте переопределение функции updateUnityCommandLineArguments() , которая использует значение apiOverride для передачи аргумента командной строки в механизм Unity, определяющий, какой графический API использовать:

Котлин

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"
}

Ява

@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;
}

Ваша пользовательская активность теперь вызывает VkQuality при запуске и выбирает Vulkan или OpenGL ES на основе рекомендации VkQuality.

Используйте собственный список рекомендаций

Укажите собственный файл списка рекомендаций, передав в StartVkQuality() имя файла, содержащего список, вместо пустой строки:

Котлин

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

Ява

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

VkQuality сначала ищет файл во внутреннем хранилище вашего приложения. Если файла нет во внутренней памяти, VkQuality пытается загрузить файл из ресурсов вашего пакета приложений. Если файла нет ни в одном месте, VkQuality возвращает значение перечисления ERROR_MISSING_DATA_FILE .

Чтобы создать собственный файл списка рекомендаций, используйте инструмент VkQuality List Editor , расположенный в репозитории GitHub . Документация по инструменту находится в его README .

Примечание. Чтобы включить пользовательский файл списка рекомендаций в ресурсы пакета приложения, экспортируйте список из редактора списков VkQuality, используя опцию библиотеки .aar , и поместите экспортированный файл .aar в каталог Assets/Android/Plugins . Unity не включает файл .vkq если вы поместите его непосредственно в каталог Assets/Android/Plugins , он должен быть упакован в контейнер библиотеки .aar . Расширение типа файла .vkq по-прежнему используется при указании имени файла для StartVkQuality() .