Das VkQuality-Plug-in für die Unity-Engine gibt Empfehlungen zur Startzeit der Graphics API (Vulkan oder OpenGL ES) für Ihr Spiel auf bestimmten Geräten.
VkQuality empfiehlt Vulkan auf einer Reihe von Geräten, die stärker eingeschränkt sind als die Standard-Zulassungsliste der Unity-Engine. Mit VkQuality profitierst du von den Leistungsvorteilen von Vulkan und kannst Vulkan auf neuere Geräte mit neueren Grafiktreibern beschränken. Dadurch wird die Anfälligkeit deines Spiels für Treiberprobleme eingeschränkt. VkQuality gibt nur Empfehlungen zur Qualität, keine Garantien, da auf empfohlenen Geräten weiterhin Treiberprobleme auftreten können. VkQuality unterstützt benutzerdefinierte Listen, mit denen Sie Geräteempfehlungen für Ihr Spiel hinzufügen oder entfernen können.
Vulkan in deinem Unity-Engine-Spiel aktivieren
Für VkQuality ist für Ihr Spiel sowohl der OpenGL ES- als auch der Vulkan-Renderer in den Unity-Projekteinstellungen aktiviert. Aktivieren Sie die Renderer mithilfe der Option Auto Graphics API oder durch manuelle Festlegung der Grafik-APIs.
VkQuality-Plug-in für Unity-Engine abrufen
Laden Sie das VkQuality-Plug-in von GitHub herunter. Das Plug-in ist mit Unity 2021 und höher kompatibel. Verwenden Sie Unity 2021 LTS oder höher, um Sense unter Android zu aktivieren. Das Plug-in-Paket enthält ein grundlegendes Beispielprojekt, das das Plug-in verwendet, um die Grafik-API beim Start festzulegen, und dann einen String anzeigt, der für die aktive Grafik-API des Geräts festgelegt ist.
Empfehlungsliste für VkQuality Vulkan verwalten
VkQuality enthält eine Standardliste mit Empfehlungen für unterstützte Geräte. Informationen zum Verwenden einer benutzerdefinierten Empfehlungsliste finden Sie im Abschnitt Benutzerdefinierte Empfehlungsliste verwenden.
Die Liste der Empfehlungen umfasst drei Kategorien:
- Zulassungsliste mit Vulkan-Geräten
- Zulassungsliste mit GPU-Empfehlungen
- Sperrliste für GPU-Empfehlungen
Übereinstimmende Geräte in der Zulassungsliste
VkQuality prüft zuerst, ob das aktive Gerät auf der Zulassungsliste für Geräte steht und ob die mindestens erforderliche Android- und Vulkan-Treiberversion ausgeführt wird, die in der Zulassungsliste für dieses Gerät angegeben sind. Wenn diese Kriterien erfüllt sind, empfiehlt VkQuality Vulkan und gibt den enum-Wert RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH
zurück.
Wenn das Gerät auf der Zulassungsliste steht, aber eine Android-Version oder Treiberversion ausgeführt wird, die unter dem in der Zulassungsliste angegebenen Minimum liegt, empfiehlt VkQualityem OpenGL ES, indem RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER
zurückgegeben wird.
GPU-Empfehlung stimmt überein mit
Wenn auf der Zulassungsliste für Geräte keine Übereinstimmung gefunden wird, wertet VkQuality das GPU-Modell und die Treiberversion anhand der GPU-Empfehlungs- und Zulassungslisten aus. Wenn das GPU-Modell und die Treiberversion mit einem Eintrag in der Zulassungsliste der GPU-Empfehlungen übereinstimmen, empfiehlt VkQuality, Vulkan durch die Rückgabe der enum-Konstante RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH
zu empfehlen.
Wenn das GPU-Modell und die Treiberversion mit einem Eintrag in der Liste zum Ablehnen von GPU-Empfehlungen übereinstimmen, empfiehlt VkQuality die Verwendung von OpenGL ES durch Rückgabe von RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH
.
Empfehlungen ohne Übereinstimmung
Wenn keine Übereinstimmungen gefunden werden, empfiehlt VkQuality Vulkan, wenn das Android API-Level des laufenden Geräts dem Future API-Level in der Empfehlungsliste entspricht oder höher ist. Die standardmäßige Empfehlungsliste hat das Future API-Level 36. Das bedeutet, dass auf nicht übereinstimmenden Geräten mit API-Level 36 oder höher die enum-Konstante RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID
zurückgegeben wird.
Wenn in der Zulassungsliste für Geräte oder in den GPU-Empfehlungslisten keine Übereinstimmungen gefunden werden und das API-Level des Geräts unter dem Future API-Level liegt, empfiehlt VkQualityem OpenGL ES durch die Rückgabe von RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH
.
Fügen Sie Ihrem Projekt die VkQuality-Archivdatei hinzu
Das VkQuality-Plug-in ist die Datei VkQuality-1.x.x.aar
, die sich im Verzeichnis Assets/Android/Plugins
des heruntergeladenen Paketarchivs befindet. Die tatsächliche Versionsnummer der AAR-Datei stimmt mit der Versionsnummer des Paketnamens des Pakets überein. Führen Sie die folgenden Schritte aus, um das Plug-in zu installieren:
- Kopieren Sie die AAR-Datei in das Verzeichnis
Assets/Android/Plugins
Ihres Projekts. Erstellen Sie die erforderlichen UnterverzeichnisseAndroid
undPlugins
, falls sie noch nicht vorhanden sind.
![Die VkQuality-AAR-Datei im erforderlichen Projektverzeichnis.](https://developer.android.google.cn/static/images/games/engines/unity/unity-vkquality-unityassets.png?authuser=6&hl=de)
- Wählen Sie in der Unity-Projekthierarchie die Plug-in-Datei
VkQuality-1.x.x
aus, um die zugehörigen Importeinstellungen im Bereich Inspector aufzurufen. Achten Sie darauf, dass die Android-Plattform aktiviert ist.
![Abbildung 2. Die Plattformimporteinstellungen für das VkQuality-Plug-in](https://developer.android.google.cn/static/images/games/engines/unity/unity-vkquality-unityplugin.png?authuser=6&hl=de)
Benutzerdefinierte Aktivität zum Aufrufen von VkQuality verwenden
Im Gegensatz zu typischen Unity-Engine-Plug-ins muss VkQuality ausgeführt werden, um eine Grafik-API-Empfehlung zu erhalten, bevor die Unity-Engine initialisiert wird. Anschließend verwenden Sie die Funktion Unity-Player-Befehlszeilenargumente, um die Grafik-API basierend auf der VkQuality-Empfehlung festzulegen. Unter Android muss für die Übergabe von Befehlszeilenargumenten das Standardverhalten von UnityPlayerActivity überschrieben werden, indem eine benutzerdefinierte Aktivität erstellt wird.
Wenn Ihr Spiel bereits eine benutzerdefinierte Aktivität verwendet, lesen Sie den Abschnitt VkQuality zu einer vorhandenen benutzerdefinierten Aktivität hinzufügen. Wie Sie eine neue benutzerdefinierte Aktivität für Ihr Spiel erstellen, erfahren Sie im Abschnitt Benutzerdefinierte Aktivität zu Ihrem Unity-Projekt hinzufügen.
Dem Unity-Engine-Projekt eine benutzerdefinierte Aktivität hinzufügen
Das Plug-in-Paket in Assets/Plugins/Android/VkQualityTestActivity.java
enthält ein Beispiel für eine benutzerdefinierte Aktivität, die VkQuality verwendet.
So passen Sie die Datei an und verwenden sie in Ihrem Spiel:
- Kopieren Sie die Datei
VkQualityTestActivity.java
in das VerzeichnisAssets/Plugins/Android
. - Geben Sie dem Namen einen für Ihr Spiel geeigneten Namen, z. B.
MyGameActivity.java
. - Öffnen Sie die Datei in einem Texteditor.
- Ändern Sie den Klassennamen von
VkQualityTestActivity
in den Namen, den Sie der Datei gegeben haben (z. B.MyGameActivity.java
). - Ändern Sie den Paketnamen von
com.google.android.games.VkQualityTest
so, dass er mit dem Wert im Feld Paketname in der Kategorie Player der Unity-Projekteinstellungen unter Weitere Einstellungen übereinstimmt, z. B.com.mycompany.mygame
. - Speichern und schließen Sie die Datei.
Fügen Sie eine benutzerdefinierte Manifestdatei hinzu, die auf Ihre benutzerdefinierte Aktivität verweist, und weisen Sie Unity an, diese zu verwenden:
- Kopieren Sie die Datei
AndroidManifest.xml
aus dem VerzeichnisAssets/Plugins/Android
des Plug-in-Pakets in das VerzeichnisAsset/Plugins/Android
Ihres Projekts. - Öffnen Sie die Datei in einem Texteditor.
- Ändern Sie den Wert der Einstellung
activity android:name
voncom.google.android.games.VkQualityTest.VkQualityTestActivity
in die Paket- und Aktivitätsnamen, die Sie in den vorherigen Schritten verwendet haben (z. B.com.mycompany.mygame.MyGameActivity
). - Speichern und schließen Sie die Datei.
- Öffnen Sie das Unity-Einstellungsfenster und wählen Sie die Player-Einstellungen aus. Maximieren Sie den Bereich Veröffentlichungseinstellungen und klicken Sie das Kästchen Benutzerdefiniertes Hauptmanifest an.
![Abbildung 3: Die Option „Custom Main Manifest“ (Benutzerdefiniertes Hauptmanifest) in den Unity Player-Einstellungen.](https://developer.android.google.cn/static/images/games/engines/unity/unity-vkquality-unitymanifest.png?authuser=6&hl=de)
Ihr Projekt ist jetzt so eingerichtet, dass die benutzerdefinierte Aktivität verwendet wird, die beim Start VkQuality aufruft und Vulkan oder OpenGL ES basierend auf der VkQuality-Empfehlung auswählt.
VkQuality zu einer vorhandenen benutzerdefinierten Aktivität hinzufügen
Wenn Ihr Spiel bereits eine benutzerdefinierte Aktivität hat, die den standardmäßigen UnityPlayerActivity
überschreibt, integrieren Sie die VkQuality-Empfehlungen, indem Sie den folgenden Code hinzufügen:
Fügen Sie zuerst die VkQuality-Importanweisung zur Liste der Importe oben in der Datei der benutzerdefinierten Aktivität hinzu:
Kotlin
import com.google.android.games.vkquality.VKQuality;
Java
import com.google.android.games.vkquality.VKQuality;
Erstellen Sie als Nächstes im Textkörper Ihrer Activity
-Klasse einige Konstanten für die Auswahl der APIs für die Grafik-API:
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;
Erstellen Sie eine Variable, um die API-Auswahl zu verfolgen:
Kotlin
private var apiOverride = OVERRIDE_NONE
Java
private int apiOverride = OVERRIDE_NONE;
Fügen Sie der Klasse Activity
die folgende Funktion hinzu:
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); } }
Rufen Sie die Funktion CheckVkQuality
über die Überschreibungsfunktion onCreate()
auf, bevor Sie die Basisklassenimplementierung aufrufen:
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { CheckVkQuality() super.onCreate(savedInstanceState) }
Java
@Override protected void onCreate(Bundle savedInstanceState) { CheckVkQuality(); super.onCreate(savedInstanceState); }
Fügen Sie schließlich eine Überschreibung der Funktion updateUnityCommandLineArguments()
hinzu, die den Wert von apiOverride
verwendet, um ein Befehlszeilenargument an die Uneinheitlichkeit zu übergeben und festzulegen, welche Grafik-API verwendet werden soll:
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; }
Ihre benutzerdefinierte Aktivität ruft jetzt beim Start VkQuality auf und wählt Vulkan oder OpenGL ES basierend auf der VkQuality-Empfehlung aus.
Benutzerdefinierte Empfehlungsliste verwenden
Geben Sie eine benutzerdefinierte Empfehlungslistendatei an. Übergeben Sie dazu den Namen der Datei, die die Liste enthält, an StartVkQuality()
, anstatt einen leeren String zu übergeben:
Kotlin
val startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq")
Java
int startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq");
VkQuality sucht zuerst im internen Speicherverzeichnis Ihrer Anwendung nach der Datei. Wenn sich die Datei nicht im internen Speicher befindet, versucht VkQuality, die Datei aus den Assets Ihres App Bundles zu laden. Wenn sich die Datei nicht an einem der beiden Speicherorte befindet, gibt VkQuality den enum-Wert ERROR_MISSING_DATA_FILE
zurück.
Mit dem Tool VkQuality List Editor im GitHub-Repository können Sie eine benutzerdefinierte Datei mit einer Empfehlungsliste erstellen. Die Dokumentation zum Tool finden Sie in der Readme-Datei.