Come usare le funzionalità EasyAR su Apple Vision Pro

Questa guida accompagna la configurazione del progetto Unity e di Xcode per sbloccare, sulle app Apple Vision Pro, tutte le funzionalità principali di EasyAR, inclusa la localizzazione cloud Mega.

Prima di iniziare

• Imparare a usare gli esempi per visori
• Assicurarsi che l'ambiente di sviluppo soddisfi questi requisiti:
  • visionOS 2.0 o superiore
  • Xcode 16.0 o superiore per la versione corrispondente di visionOS e installazione del simulatore visionOS
  • versione Unity LTS consigliata 6000.0.23 o superiore

Richiedere ad Apple Inc. la licenza API enterprise

Poiché l'accesso ai frame della fotocamera e ai relativi parametri su Apple Vision Pro è una API enterprise che richiede un entitlement, è necessario richiedere ad Apple Inc. un file license che includa tale entitlement. Per il processo di richiesta e utilizzo fare riferimento a Building spatial experiences for business apps with enterprise APIs for visionOS.

Importante

Il Bundle ID nell'entitlement ottenuto da Apple deve corrispondere esattamente a quello inserito al momento della creazione della EasyAR Sense License Key.

Come scegliere la modalità App di visionOS

Le app eseguite su visionOS possono ottenere dati ARKit solo in Immersive Space. Le app compilate dall'editor Unity, in Immersive Space, devono usare RealityKit with PolySpatial oppure Metal Rendering with Compositor Services a seconda del flusso di rendering e dell'API usata.

Per la definizione di Immersive Space si può consultare la documentazione ufficiale Apple.

Per una descrizione dettagliata della modalità App di Unity, si può fare riferimento alla documentazione PolySpatial di Unity, in visionOS Platform Overview.

Consiglio

Suggerimento per la scelta della modalità App

• Scelta consigliata: RealityKit with PolySpatial

  Se è la prima volta che si lavora con visionOS, si consiglia di partire da questa modalità. Il vantaggio è una forte integrazione con il rendering a livello di sistema di visionOS, stabilità elevata e buon risultato visivo. Questa modalità non supporta shader personalizzati (HLSL/ShaderLab): bisogna usare Shader Graph e solo le funzionalità approvate dai controlli di compatibilità PolySpatial, che verranno convertite in MaterialX.

  Gli shader Standard (Built-in) e Lit (URP) inclusi in Unity sono già stati adattati ufficialmente e possono essere usati direttamente.

• Per esigenze avanzate/specifiche: Metal Rendering with Compositor Services

  Adatta a progetti complessi con molte risorse 3D già esistenti da migrare o con la necessità obbligatoria di usare shader personalizzati. Poiché in questa modalità Unity gestisce tutta la logica di rendering, aggirando la pipeline RealityKit del sistema, il risultato visivo in genere è meno buono di RealityKit e si possono incontrare problemi di rendering non prevedibili.

Suggerimento per l'integrazione EasyAR:

Quando si prova a integrare EasyAR, usare prima la modalità RealityKit with PolySpatial per far funzionare il flusso di base. In questo modo si isolano le variabili ed si evitano problemi di adattamento Metal che si mescolano a quelli AR, rendendo più difficile individuare la causa dei guasti.

Configurazione nel progetto Unity

Nel progetto Unity è necessario fare le seguenti configurazioni:

Importare i package necessari nel progetto Unity

Unity 6 (consigliato):

• RealityKit/Hybrid
• Metal

• com.unity.xr.visionos (2.0.4+)
• com.unity.polyspatial (2.0.4+)
• com.unity.polyspatial.visionos (2.0.4+)

Importante

La versione di tutti i package deve essere identica.

Si consiglia di usare prima Unity 6; alcune versioni precedenti di Unity 2023.x non supportano visionOS.

Unity 2022.3:

• RealityKit/Hybrid
• Metal

• com.unity.xr.visionos (1.2.3)
• com.unity.polyspatial (1.2.3)
• com.unity.polyspatial.visionos (1.2.3)

Importante

La versione di tutti i package deve essere identica.

Non è supportata la versione 1.3.x: assicurarsi di restare su 1.2.3.

Scegliere la piattaforma di build

Fare clic su File > Build Profiles nel menu per cambiare la piattaforma in visionOS.

Configurare Input System

Assicurarsi di usare la nuova Input System Package:

Fare clic su Edit > Project Settings > Player, quindi impostare Active Input Handling su Input System Package(New).

Unity potrebbe chiedere di riavviare il progetto; fare clic su Apply per applicare le modifiche.

Configurare XR Plug-in Management

Fare clic su Edit > Project Settings > XR Plug-in Management e, nella scheda visionOS, selezionare Apple visionOS tra i Plug-in Providers.

Configurare il plugin Apple visionOS

Fare clic su Edit > Project Settings > XR Plug-in Management > Apple visionOS.

Scegliere la App Mode adatta in base a quanto descritto in precedenza.

Nota

La modalità Windowed, non essendo eseguita in Immersive Space, non può usare le funzionalità AR.

La modalità Hybrid richiede che lo sviluppatore passi manualmente tra Metal e RealityKit. Poiché l'uso è abbastanza complesso, non è consigliata. Per i dettagli si può consultare la documentazione ufficiale Unity su questa modalità.

Effettuare poi le seguenti modifiche nella stessa pagina:

• Aggiungere una descrizione nel campo World Sensing Usage Description.

• Impostare Metal Immersion Style su Mixed.

• Impostare Reality Kit Immersion Style su Mixed.

• Selezionare IL2CPP Large Exe Workaround.

[Solo per la modalità RealityKit] Importare TextMesh Pro Essentials

Fare clic su Edit > Project Settings > TextMesh Pro > Import TMP Essentials

Nota

Al momento la modalità RealityKit with PolySpatial supporta solo testo TextMesh Pro; senza importarlo il testo non potrà essere renderizzato.

[Solo per la modalità RealityKit] Impostazioni PolySpatial

Fare clic su Edit > Project Settings > PolySpatial e modificare quanto segue:

• Impostare Default Volume Camera Window Config su Default Unbounded Configuration.

• Selezionare Auto-Create Volume Camera

Se è necessario specificare anche Default Volume Camera Window Config, assicurarsi che la sua Mode sia Unbounded.

Se nella scena esiste una Volume Camera, eliminarla.

Avvertenza

• Non sono supportate le Volume Camera il cui valore di World Transform non sia identity.
• Se per motivi speciali è necessario aggiungere una singola Volume Camera personalizzata nella scena, assicurarsi di:
  • impostare World Transform su identity;
  • impostare Mode di Volume Camera Window Configuration su Unbounded;
  • usarla solo dopo aver compreso bene significato e uso nella documentazione ufficiale Unity.

[Quando si usa Mega] Aggiungere la descrizione di uso della posizione

Attenzione

Se nella configurazione EasyAR è stata abilitata l'autorizzazione Location (quando si usa Mega), è necessario aggiungere la descrizione dell'autorizzazione, altrimenti la build fallirà.

Poiché al momento nella scheda visionOS di Project Settings > Player non è visibile il campo Location Usage Description, seguire questi passaggi:

1. Cambiare scheda piattaforma: passare temporaneamente alla scheda iOS.
2. Inserire la descrizione: compilare il campo Location Usage Description con una descrizione adeguata dello scopo dell'autorizzazione.
3. Tornare a visionOS: rientrare nella scheda visionOS; la configurazione inserita prima verrà mantenuta e resa effettiva automaticamente.

Configurazione nel progetto Xcode

Nel progetto Xcode generato da Unity è necessario fare le seguenti configurazioni:

Configurare l'entitlement dei dati della fotocamera

• Copiare il file Enterprise.license ottenuto nella cartella del progetto Xcode.

  

• Trascinare il file Enterprise.license nella cartella del progetto Xcode dentro Xcode.

  

Modificare info.plist per consentire all'app di salvare e condividere file

Se è necessario registrare EIF nell'app e inviarlo al computer o ad altri dispositivi tramite l'app File di visionOS, bisogna aggiungere e modificare questi campi in Info.plist:

• Aggiungere LSSupportsOpeningDocumentsInPlace e impostarlo su true.

• Aggiungere UIFileSharingEnabled e impostarlo su true.

Consiglio

Dopo l'aggiunta dei campi, il Key mostrato da Xcode è diverso dalla stringa inserita manualmente (per esempio, se si inserisce LSSupportsOpeningDocumentsInPlace verrà mostrato Supports opening documents in place): è normale.