Le plug-in VkQuality pour le moteur Unity fournit des recommandations de lancement de l'API graphique (Vulkan ou OpenGL ES) à utiliser pour votre jeu sur des appareils spécifiques.
VkQuality recommande Vulkan sur un ensemble d'appareils plus limité que la liste d'autorisation par défaut du moteur Unity. Utilisez VkQuality pour bénéficier des avantages de performances de Vulkan tout en limitant son utilisation aux appareils plus récents dotés de pilotes graphiques plus récents, ce qui limite l'exposition de votre jeu aux problèmes de pilotes. VkQuality ne fournit que des recommandations de qualité, et non des garanties, car il est toujours possible de rencontrer des problèmes de pilote sur les appareils recommandés. VkQuality prend en charge les listes personnalisées, ce qui vous permet d'ajouter ou de supprimer des recommandations d'appareils pour votre jeu.
Activer Vulkan dans votre jeu de moteur Unity
Pour VkQuality, les moteurs de rendu OpenGL ES et Vulkan doivent être activés dans les paramètres du projet Unity pour votre jeu. Activez les moteurs de rendu à l'aide de l'option API Auto Graphics ou en définissant 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 les versions ultérieures. Utilisez Unity 2021 LTS ou une version ultérieure pour activer Vulkan sur Android. Le package de plug-in contient un exemple de projet de base qui utilise le plug-in pour définir l'API Graphics au démarrage, puis affiche une chaîne définie pour l'API Graphics active de l'appareil.
Gérer la liste des recommandations de VkQuality Vulkan
VkQuality inclut une liste de recommandations par défaut d'appareils compatibles. Pour en savoir plus sur l'utilisation d'une liste de recommandations personnalisée, consultez la section Utiliser une liste de recommandations personnalisée.
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 de la liste d'autorisation des appareils
VkQuality vérifie d'abord si l'appareil actif est inclus dans la liste d'autorisation des appareils, et s'il exécute la version minimale d'Android et la version du pilote Vulkan spécifiées dans la liste d'autorisation pour 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 de pilote inférieure au minimum spécifié dans la liste d'autorisation, VkQuality recommande OpenGL ES en renvoyant RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER.
Correspondances avec les recommandations de GPU
Si aucun appareil ne figure dans la liste d'autorisation des appareils, VkQuality évalue le modèle de GPU et la version du pilote par rapport aux listes d'autorisation et de refus des recommandations de GPU. Si le modèle de GPU et la version du pilote correspondent à une entrée de la liste d'autorisation des recommandations de GPU, 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 de la liste de refus des recommandations de GPU, 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 égal ou supérieur au niveau d'API Future dans la liste de recommandations. La liste de recommandations par défaut a un niveau d'API "Future" de 36, ce qui signifie que 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 Future, VkQuality recommande OpenGL ES en renvoyant RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH.
Ajouter le fichier d'archive VkQuality à votre projet
Le plug-in VkQuality correspond au fichier VkQuality-1.x.x.aar situé dans le répertoire Assets/Android/Plugins de l'archive du package téléchargée. Le numéro de version réel du fichier .aar correspond au numéro de version du nom de l'archive du package. Pour installer le plug-in, procédez comme suit:
- Copiez le fichier .aar dans le répertoire
Assets/Android/Pluginsde votre projet. (Créez les sous-répertoiresAndroidetPluginsnécessaires s'ils n'existent pas.)
- Sélectionnez le fichier de plug-in
VkQuality-1.x.xdans la hiérarchie du projet Unity pour afficher ses Import Settings (Paramètres d'importation) dans le volet Inspector (Inspecteur). Assurez-vous que la plate-forme Android est cochée.
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 d'API graphique avant l'initialisation du moteur Unity. Vous utiliserez ensuite la fonctionnalité Arguments de ligne de commande du lecteur Unity pour définir l'API graphique en fonction de la recommandation VkQuality. Sur Android, la transmission d'arguments de ligne de commande nécessite de remplacer le comportement par défaut de UnityPlayerActivity en créant une activité personnalisée.
Si votre jeu utilise déjà une activité personnalisée, consultez la section Ajouter VkQuality à une activité personnalisée existante. Pour créer une activité personnalisée pour votre jeu, consultez la section 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 qui utilise VkQuality est inclus dans le package de plug-in dans Assets/Plugins/Android/VkQualityTestActivity.java.
Pour personnaliser le fichier et l'utiliser dans votre jeu, procédez comme suit:
- Copiez le fichier
VkQualityTestActivity.javadans votre répertoireAssets/Plugins/Android. - Renommez-le en un nom adapté à votre jeu (par exemple,
MyGameActivity.java). - Ouvrez le fichier dans un éditeur de texte.
- Remplacez le nom de classe
VkQualityTestActivitypar le nom que vous avez donné au fichier (par exemple,MyGameActivity.java). - Modifiez le nom du package
com.google.android.games.VkQualityTestpour qu'il corresponde à la valeur du champ Package Name (Nom du package) dans la catégorie Player des paramètres de votre projet Unity sous Other Settings (Autres paramètres), par exemplecom.mycompany.mygame. - Enregistrez et fermez le fichier.
Ajoutez un fichier manifeste personnalisé qui référence votre activité personnalisée et indiquez à Unity d'utiliser votre fichier manifeste personnalisé:
- Copiez le fichier
AndroidManifest.xmldu répertoireAssets/Plugins/Androiddu package de plug-in dans le répertoireAsset/Plugins/Androidde votre projet. - Ouvrez le fichier dans un éditeur de texte.
- Remplacez la valeur du paramètre
activity android:namecom.google.android.games.VkQualityTest.VkQualityTestActivitypar les noms de package et d'activité 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éveloppez la section Publishing Settings (Paramètres de publication), puis cochez la case Custom Main Manifest (Fichier manifeste principal personnalisé).
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 dispose déjà d'une activité personnalisée remplaçant la valeur UnityPlayerActivity par défaut, intégrez les recommandations VkQuality en ajoutant le code suivant:
Tout d'abord, ajoutez l'instruction d'importation VkQuality à la liste des importations en haut du 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 la classe Activity pour les choix de l'API graphique:
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 à votre 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 en haut d'une fonction de remplacement 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 en fonction de la recommandation 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 commence par rechercher le fichier dans le répertoire de stockage interne de votre application. Si le fichier ne se trouve pas dans la mémoire de stockage interne, VkQuality tente de le charger à 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ée, utilisez l'outil VkQuality List Editor (Éditeur de liste VkQuality) situé dans le dépôt GitHub. La documentation de l'outil se trouve dans le fichier README correspondant.