Cette page a été traduite par l'API Cloud Translation.

Plug-in de moteur Unity VkQuality

Le plug-in VkQuality pour le moteur Unity fournit des recommandations lors du lancement. de l'API graphique (Vulkan ou OpenGL ES) à utiliser pour votre jeu sur des appareils.

VkQuality recommande Vulkan sur un ensemble d'appareils plus restreint que sur Unity. la liste d'autorisation par défaut du moteur de recherche. Utilisez VkQuality pour améliorer les performances de Vulkan tout en limitant l'utilisation de Vulkan aux appareils plus récents avec des graphismes plus récents ce qui limite l'exposition de votre jeu aux problèmes de pilote. VkQuality uniquement fait des recommandations de qualité, pas des garanties, puisqu'il est toujours possible de rencontrer des problèmes de pilotes sur les appareils recommandés. VkQuality prend en charge les listes personnalisées, qui vous permet d'ajouter ou de supprimer des recommandations jeu.

Activer Vulkan dans votre jeu de moteur Unity

VkQuality exige que votre jeu dispose à la fois des moteurs de rendu OpenGL ES et Vulkan dans les paramètres du projet Unity. Activez les moteurs de rendu à l'aide du bouton Auto l'API Graphics ou en configurant manuellement les API graphiques.

Obtenir le plug-in VkQuality pour le moteur Unity

Téléchargez le plug-in VkQuality sur GitHub. Le plug-in est compatible avec Unity 2021 et versions ultérieures. Utilisez Unity 2021 LTS ou version ultérieure pour activer Vulkan sur Android. Le package du plug-in contient un exemple de projet de base qui utilise le plug-in de définir l'API graphique au démarrage, puis affiche une chaîne définie sur l'API graphique active de l'appareil.

Gérer la liste de recommandations VkQuality Vulkan

VkQuality comprend une liste de recommandations par défaut d'appareils compatibles. Pour sur l'utilisation d'une liste de recommandations personnalisée, reportez-vous à la section Utiliser une liste de recommandations.

La liste de recommandations comprend trois catégories:

Liste d'autorisation des appareils Vulkan
Liste d'autorisation des recommandations de GPU
Liste de refus des recommandations de GPU

Correspondances avec la liste d'autorisation des appareils

VkQuality vérifie d'abord si l'appareil actif est inclus dans la liste et s'il exécute la version minimale d'Android et le pilote Vulkan spécifiée dans la liste d'autorisation de cet appareil. Si ces critères sont remplis, VkQuality recommande Vulkan en renvoyant la Valeur d'énumération RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH.

Si l'appareil figure sur la liste d'autorisation, mais qu'il exécute une version d'Android ou un pilote version inférieure à la version minimale spécifiée dans la liste autorisée, VkQuality recommande OpenGL ES en renvoyant RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER.

La recommandation de GPU correspond

Si aucun appareil ne correspond à cette liste, VkQuality évalue les Le modèle de GPU et la version du pilote par rapport aux recommandations d'autorisation et de refus du GPU . Si le modèle de GPU et la version du pilote correspondent à une entrée du GPU liste d'autorisation des recommandations, VkQuality recommande Vulkan en renvoyant la Constante d'énumération RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH.

Si le modèle de GPU et la version du pilote correspondent à une entrée du GPU liste de refus des recommandations, VkQuality recommande OpenGL ES en renvoyant RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH

Recommandations sans correspondance

Si aucune correspondance n'est trouvée, VkQuality recommande Vulkan si le niveau d'API Android de l'appareil en cours d'exécution est supérieur ou égal au niveau d'API Future dans le liste de recommandations. Le niveau d'API Future de la liste de recommandations par défaut est 36, soit sur les appareils sans correspondance exécutant le niveau d'API 36 ou supérieur, VkQuality renvoie la constante d'énumération RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID.

Si aucune correspondance n'est trouvée dans la liste d'autorisation des appareils ou dans les listes de recommandations de GPU, et que le niveau d'API de l'appareil est inférieur au niveau d'API futur, VkQuality recommande OpenGL ES en renvoyant RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH.

Ajouter le fichier d'archive VkQuality à votre projet

Le plug-in VkQuality est le fichier VkQuality-1.x.x.aar situé dans Répertoire Assets/Android/Plugins de l'archive de packages téléchargée. La valeur réelle Le numéro de version du fichier .aar correspond au numéro de version du package nom de l'archive. Pour installer le plug-in, procédez comme suit:

Copiez le fichier .aar dans le répertoire Assets/Android/Plugins de votre projet. (Créez les sous-répertoires Android et Plugins nécessaires s'ils n'existent pas.)

Le fichier .aar VkQuality dans le répertoire de projet requis. — **Figure 1** : Fichier .aar VkQuality dans le répertoire de projet requis.

Sélectionnez le fichier de plug-in VkQuality-1.x.x dans la hiérarchie des projets Unity. pour afficher ses Import Settings (Paramètres d'importation) dans le volet Inspector (Inspecteur). Vérifiez que le paramètre la plate-forme Android est cochée.

Figure 2. Paramètres d'importation de la plate-forme de plug-in VkQuality. — **Figure 2**. Paramètres d'importation de la plate-forme de plug-in VkQuality.

Utiliser une activité personnalisée pour appeler VkQuality

Contrairement aux plug-ins de moteur Unity classiques, VkQuality doit être exécuté pour obtenir une recommandation de l'API graphique avant l'initialisation du moteur Unity. Vous utiliserez ensuite la fonctionnalité d'arguments de ligne de commande de lecteur Unity pour définir en fonction de la recommandation de VkQuality. Sur Android, la transmission les arguments de ligne de commande nécessitent de remplacer le comportement par défaut UnityPlayerActivity en créant une activité.

Si votre jeu utilise déjà une activité personnalisée, reportez-vous à la section Ajouter VkQuality à une section "Activité personnalisée existante". Pour créer une activité personnalisée pour votre consultez Ajouter une activité personnalisée à votre projet Unity ci-après.

Ajouter une activité personnalisée à votre projet de moteur Unity

Un exemple d'activité personnalisée utilisant VkQuality est inclus dans le plug-in package dans Assets/Plugins/Android/VkQualityTestActivity.java. Pour personnaliser le fichier et l'utiliser dans votre jeu, procédez comme suit:

Copiez le fichier VkQualityTestActivity.java dans votre Assets/Plugins/Android.
Renommez-le en fonction de votre jeu (par exemple, MyGameActivity.java).
Ouvrez le fichier dans un éditeur de texte.
Remplacez le nom de classe VkQualityTestActivity par celui que vous avez donné au (par exemple, MyGameActivity.java).
Remplacez le nom du package com.google.android.games.VkQualityTest par correspondre à la valeur du champ Package Name (Nom du package) dans les paramètres de votre projet Unity ; Lecteur sous Autres paramètres (par exemple, com.mycompany.mygame).
Enregistrez et fermez le fichier.

Ajoutez un fichier manifeste personnalisé qui référence votre activité personnalisée et indiquez à Unity pour utiliser votre fichier manifeste personnalisé:

Copiez le fichier AndroidManifest.xml à partir de Assets/Plugins/Android. du package du plug-in dans le répertoire Asset/Plugins/Android de votre projet .
Ouvrez le fichier dans un éditeur de texte.
Remplacez la valeur du paramètre activity android:name com.google.android.games.VkQualityTest.VkQualityTestActivity jusqu'à les noms de packages et d'activités que vous avez utilisés aux étapes précédentes (par exemple, com.mycompany.mygame.MyGameActivity).
Enregistrez et fermez le fichier.
Ouvrez la fenêtre des paramètres Unity et sélectionnez les paramètres Player (Lecteur). Développer Section Paramètres de publication, puis consultez le fichier Fichier manifeste principal personnalisé .

Figure 3. Option "Custom Main Manifest" (Fichier manifeste principal personnalisé) dans les paramètres du lecteur Unity — **Figure 3**. Option **Custom Main Manifest** (Fichier manifeste principal personnalisé) dans les paramètres **Player** d'Unity

Votre projet est maintenant configuré pour utiliser l'activité personnalisée qui appelle VkQuality à au démarrage et choisit Vulkan ou OpenGL ES en fonction de la recommandation VkQuality.

Ajouter VkQuality à une activité personnalisée existante

Si votre jeu comporte déjà une activité personnalisée remplaçant l'activité par défaut UnityPlayerActivity, intégrez les recommandations de VkQuality en ajoutant le code suivant:

Tout d'abord, ajoutez l'instruction d'importation VkQuality à la liste des importations en haut de le fichier d'activité personnalisée:

Kotlin

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

Java

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

Ensuite, créez des constantes dans le corps de votre classe Activity pour le API de graphiques disponibles:

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;

Créez une variable pour suivre la sélection de l'API:

Kotlin

private var apiOverride = OVERRIDE_NONE

Java

private int apiOverride = OVERRIDE_NONE;

Ajoutez la fonction suivante à la 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);
  }
}

Appelez la fonction CheckVkQuality à partir du haut d'un forçage onCreate(). avant d'appeler l'implémentation de la classe de base:

Kotlin

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

Java

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

Enfin, ajoutez un forçage de la fonction updateUnityCommandLineArguments(). qui utilise la valeur de apiOverride pour transmettre un argument de ligne de commande au Moteur Unity spécifiant l'API graphique à utiliser:

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

Votre activité personnalisée appelle désormais VkQuality au démarrage et choisit Vulkan ou OpenGL. ES sur la base de la recommandation de VkQuality.

Utiliser une liste de recommandations personnalisée

Spécifiez un fichier de liste de recommandations personnalisées en transmettant le nom du fichier contenant la liste à StartVkQuality() au lieu de transmettre une chaîne vide:

Kotlin

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

Java

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

VkQuality recherche d'abord le fichier dans la mémoire de stockage interne de votre application. . Si le fichier ne se trouve pas dans la mémoire de stockage interne, VkQuality tente de charger le à partir des éléments de votre app bundle. Si le fichier ne se trouve à aucun emplacement, VkQuality renvoie la valeur d'énumération ERROR_MISSING_DATA_FILE.

Pour créer un fichier de liste de recommandations personnalisées, utilisez l'éditeur de liste VkQuality. situé dans le dépôt GitHub. Documentation du module se trouve dans son fichier README.