Plug-in del motore VkQualità Unity

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:

1. Copia il file .aar nella directory Assets/Android/Plugins del tuo progetto. (Crea le sottodirectory Android e Plugins necessarie se non esistono.)

1. 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.

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:

1. Copia il file VkQualityTestActivity.java nella directory Assets/Plugins/Android.
2. Rinominalo con un nome appropriato per il tuo gioco (ad esempio, MyGameActivity.java).
3. Apri il file in un editor di testo.
4. Modifica il nome della classe da VkQualityTestActivity con il nome che hai assegnato al file (ad esempio, MyGameActivity.java).
5. 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).
6. 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:

1. Copia il file AndroidManifest.xml dalla directory Assets/Plugins/Android del pacchetto del plug-in nella directory Asset/Plugins/Android del progetto.
2. Apri il file in un editor di testo.
3. Cambia il valore dell'impostazione activity android:name da com.google.android.games.VkQualityTest.VkQualityTestActivity ai nomi di pacchetti e attività utilizzati nei passaggi precedenti (ad esempio, com.mycompany.mygame.MyGameActivity).
4. Salva e chiudi il file.
5. 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.

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:

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

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

Quindi, crea alcune costanti nel corpo della classe Activity per le scelte dell'API Graphic:

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;

Crea una variabile per monitorare la selezione dell'API:

private var apiOverride = OVERRIDE_NONE

private int apiOverride = OVERRIDE_NONE;

Aggiungi la funzione seguente alla tua classe 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);
  }
}

Richiama la funzione CheckVkQuality dall'alto di una funzione di override onCreate() prima di chiamare l'implementazione della classe base:

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

@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:

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

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:

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

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.