Il plug-in VkQualità per il motore Unity fornisce suggerimenti al momento del lancio dell'API grafica (Vulkan o OpenGL ES) da utilizzare per il gioco su dispositivi specifici.
VkQualità consiglia Vulkan su un insieme di dispositivi più ristretto rispetto all'elenco di dispositivi predefiniti del motore Unity. Utilizza VkQualità per sfruttare i vantaggi in termini di prestazioni di Vulkan, limitando al contempo l'utilizzo di Vulkan ai dispositivi più recenti con driver grafici più recenti, limitando l'esposizione del tuo gioco a problemi del driver. VkQualità fornisce solo consigli sulla qualità, non garanzie, dato che è ancora possibile riscontrare problemi del driver sui dispositivi consigliati. VkQualità supporta gli elenchi personalizzati, che ti consentono di aggiungere o rimuovere consigli sui dispositivi per il tuo gioco.
Attiva Vulkan nel tuo gioco del motore Unity
VkQualità richiede che per il gioco siano attivati sia i renderer OpenGL ES che quello Vulkan nelle impostazioni del progetto Unity. Attiva i renderer utilizzando l'opzione API Auto Graphics oppure impostando manualmente le API grafiche.
Scarica il plug-in VkQualità per il motore Unity
Scarica il plug-in VkQualità da GitHub. Il plug-in è compatibile con Unity 2021 e versioni successive. Utilizza Unity 2021 LTS o versioni successive per abilitare Vulkan su Android. Il pacchetto plug-in contiene un progetto di esempio di base che utilizza il plug-in per impostare l'API grafica all'avvio e poi visualizza una stringa impostata per l'API grafica attiva del dispositivo.
Gestire l'elenco di consigli di VkQualità Vulkan
VkQualità include un elenco predefinito di consigli dei dispositivi supportati. Per informazioni sull'utilizzo di un elenco di suggerimenti personalizzato, consulta la sezione Utilizzare un elenco di suggerimenti personalizzato.
L'elenco dei consigli include tre categorie:
- Elenco di dispositivi consentiti per Vulkan
- Lista consentita dei suggerimenti per le GPU
- Elenco di suggerimenti GPU non consentiti
Corrispondenze nella lista consentita dei dispositivi
VkQualità verifica innanzitutto se il dispositivo attivo è incluso nella lista consentita dei dispositivi e se ha la versione minima di Android e la versione del driver Vulkan specificate nella lista consentita del dispositivo. Se questi criteri vengono soddisfatti, VkQualità consiglia Vulkan restituendo il valore enum RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH
.
Se il dispositivo si trova nella lista consentita, ma ha una versione di Android o una versione del driver
inferiore al minimo specificato nella lista consentita, VkQualità
consiglia OpenGL ES restituendo RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER
.
Corrispondenze dei suggerimenti per la GPU
Se non viene trovata alcuna corrispondenza di dispositivi nella lista consentita dei dispositivi, VkQualità valuta il modello di GPU e la versione del driver in base alle liste consentite e bloccate dei suggerimenti per le GPU. Se il modello GPU e la versione del driver corrispondono a una voce nell'elenco di autorizzazioni suggerite per le GPU, VkQualità consiglia Vulkan restituendo la costante enum RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH
.
Se il modello di GPU e la versione del driver corrispondono a una voce nell'elenco di tipi non consentiti dei suggerimenti per le GPU, VkQualità consiglia OpenGL ES restituendo RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH
.
Consigli senza una corrispondenza
Se non vengono trovate corrispondenze, VkQualità consiglia Vulkan se il livello API Android del dispositivo in esecuzione è uguale o superiore al livello API Future nell'elenco dei suggerimenti. L'elenco dei suggerimenti predefinito ha un livello API Future pari a
36, il che significa che sui dispositivi senza corrispondenza con livello API 36 o successivo VkQualità
restituisce la costante enum RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID
.
Se non vengono trovate corrispondenze nell'elenco di dispositivi consentiti o negli elenchi di suggerimenti per le GPU e se il livello API del dispositivo è inferiore al livello API futuro, VkQualità consiglia OpenGL ES restituendo RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH
.
Aggiungi il file di archivio VkQualità al tuo progetto
Il plug-in Vk Quality è il file VkQuality-1.x.x.aar
che si trova nella directory Assets/Android/Plugins
dell'archivio dei pacchetti scaricato. Il numero di versione effettivo del file .aar corrisponde a quello del nome dell'archivio del pacchetto. Per installare il plug-in, procedi nel seguente modo:
- Copia il file .aar nella directory
Assets/Android/Plugins
del tuo progetto. (Crea le sottodirectoryAndroid
ePlugins
necessarie se non esistono.)
![Il file .aar VkQualità nella directory del progetto richiesta.](https://developer.android.com/static/images/games/engines/unity/unity-vkquality-unityassets.png?authuser=8&hl=it)
- Seleziona il file del plug-in
VkQuality-1.x.x
nella gerarchia Project di Unity per visualizzare le relative Impostazioni di importazione nel riquadro Ispezionatore. Assicurati che la piattaforma Android sia selezionata.
![Figura 2. Impostazioni di importazione della piattaforma plug-in VkQualità.](https://developer.android.com/static/images/games/engines/unity/unity-vkquality-unityplugin.png?authuser=8&hl=it)
Utilizza un'attività personalizzata per chiamare VkQualità
A differenza dei tipici plug-in del motore Unity, VkQualità deve essere eseguita per ottenere un suggerimento per l'API di grafica prima dell'inizializzazione del motore Unity. Successivamente, potrai utilizzare la funzionalità argomenti della riga di comando del player Unity per impostare l'API Graphic in base al suggerimento VkQualità. Su Android, il passaggio degli argomenti della riga di comando richiede di sostituire il comportamento predefinito di UnityPlayerActivity creazione di un'attività personalizzata.
Se il tuo gioco utilizza già un'attività personalizzata, consulta la sezione Aggiungere VkQualità a un'attività personalizzata esistente. Per creare una nuova attività personalizzata per il tuo gioco, consulta la sezione Aggiungere un'attività personalizzata al progetto Unity che segue.
Aggiungere un'attività personalizzata al progetto del motore Unity
Un'attività personalizzata di esempio che utilizza VkQualità è inclusa nel pacchetto di plug-in in Assets/Plugins/Android/VkQualityTestActivity.java
.
Per personalizzare il file e utilizzarlo nel tuo gioco, svolgi i seguenti passaggi:
- Copia il file
VkQualityTestActivity.java
nella directoryAssets/Plugins/Android
. - Rinominalo con un nome appropriato per il tuo gioco (ad esempio,
MyGameActivity.java
). - Apri il file in un editor di testo.
- Modifica il nome della classe da
VkQualityTestActivity
con il nome che hai assegnato al file (ad esempio,MyGameActivity.java
). - Modifica il nome del pacchetto da
com.google.android.games.VkQualityTest
in modo che corrisponda al valore del campo Nome pacchetto nella categoria Player delle impostazioni del progetto Unity in Altre impostazioni (ad esempio,com.mycompany.mygame
). - Salva e chiudi il file.
Aggiungi un file manifest personalizzato che faccia riferimento alla tua attività personalizzata e chiedi a Unity di utilizzare il file manifest personalizzato:
- Copia il file
AndroidManifest.xml
dalla directoryAssets/Plugins/Android
del pacchetto del plug-in nella directoryAsset/Plugins/Android
del progetto. - Apri il file in un editor di testo.
- Cambia il valore dell'impostazione
activity android:name
dacom.google.android.games.VkQualityTest.VkQualityTestActivity
ai nomi di pacchetti e attività utilizzati nei passaggi precedenti (ad esempio,com.mycompany.mygame.MyGameActivity
). - Salva e chiudi il file.
- Apri la finestra delle impostazioni Unity e seleziona le impostazioni Player (Giocatore). Espandi la sezione Impostazioni di pubblicazione e seleziona la casella di controllo manifest principale personalizzato.
![Figura 3: l'opzione Manifest principale personalizzato nelle impostazioni del player Unity.](https://developer.android.com/static/images/games/engines/unity/unity-vkquality-unitymanifest.png?authuser=8&hl=it)
Il tuo progetto è ora configurato per utilizzare l'attività personalizzata che chiama VkQualità all'avvio e sceglie Vulkan o OpenGL ES in base al suggerimento di VkQualità.
Aggiungi VkQualità a un'attività personalizzata esistente
Se il tuo gioco ha già un'attività personalizzata che esegue l'override dell'attività predefinita UnityPlayerActivity
, integra i suggerimenti di VkQualità aggiungendo il seguente codice:
Innanzitutto, aggiungi l'istruzione di importazione di VkQualità all'elenco delle importazioni nella parte superiore del file delle attività personalizzate:
Kotlin
import com.google.android.games.vkquality.VKQuality;
Java
import com.google.android.games.vkquality.VKQuality;
Quindi, crea alcune costanti nel corpo della classe Activity
per le scelte dell'API Graphic:
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;
Crea una variabile per monitorare la selezione dell'API:
Kotlin
private var apiOverride = OVERRIDE_NONE
Java
private int apiOverride = OVERRIDE_NONE;
Aggiungi la funzione seguente alla tua 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); } }
Richiama la funzione CheckVkQuality
dall'alto di una funzione di override onCreate()
prima di chiamare l'implementazione della classe base:
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { CheckVkQuality() super.onCreate(savedInstanceState) }
Java
@Override protected void onCreate(Bundle savedInstanceState) { CheckVkQuality(); super.onCreate(savedInstanceState); }
Infine, aggiungi un override della funzione updateUnityCommandLineArguments()
che utilizza il valore apiOverride
per passare un argomento della riga di comando al motore Unity che specifica l'API grafica da utilizzare:
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; }
Ora l'attività personalizzata chiama VkQualità all'avvio e sceglie Vulkan o OpenGL ES in base al suggerimento di VkQualità.
Utilizza un elenco di consigli personalizzato
Specifica un file di elenco di suggerimenti personalizzato passando a StartVkQuality()
il nome del file contenente l'elenco anziché passare una stringa vuota:
Kotlin
val startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq")
Java
int startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq");
Vkquality prima cerca il file nella directory di archiviazione interna della tua applicazione. Se il file non si trova nella memoria interna, Vkquality cerca di caricarlo dagli asset dell'app bundle. Se il file non si trova in nessuna delle due posizioni, VkQualità restituisce il valore enum ERROR_MISSING_DATA_FILE
.
Per creare un file di elenco di suggerimenti personalizzato, utilizza lo strumento VkQualità List Editor che si trova nel repository GitHub. La documentazione dello strumento si trova nel relativo file README.