VR/MR — LeonardoXR SDK

Version: 1.0.2
Target Device: Youbiquo Leonardo XR
Base SDK: Snapdragon Spaces 1.0.4

Configurazione Manuale del Progetto Unity

È raccomandato usare il Configuration Tool per la configurazione iniziale del progetto (vedi Getting Started). Questa guida descrive i passi manuali equivalenti per chi preferisce un controllo diretto sulle impostazioni.

Modifica le Project Settings

1. Vai su Edit > Project Settings > XR Plug-in Management e apri la scheda Android.
2. Abilita il plug-in OpenXR e il Snapdragon Spaces feature group.
3. Clicca sul punto esclamativo rosso accanto a OpenXR per aprire la finestra OpenXR Project Validation.
4. Clicca Fix accanto a ciascuna voce.
5. Applica l’impostazione “Enable both Input Systems” per ultima, poiché richiede un riavvio dell’editor.

Play In Editor: Per le impostazioni aggiuntive relative al workflow in editor vedi la sezione dedicata in Getting Started.

Abilita le Spaces Features

Abilita le features che devono essere attive a runtime in OpenXR Settings. Ciascuna feature corrisponde a un AR Foundation Manager e un XR Subsystem:

Aggiungi i Feature Usage Data all’Android Manifest

Vai su Edit > Project Settings > Snapdragon Spaces Launcher Settings per dichiarare le features richieste o supportate dall’applicazione per: Hand Tracking, Eye Tracking, Passthrough, Controllers e Room Scale.

Attenzione: Per default tutti i valori uses-feature sono impostati su true. Imposta su false le features non utilizzate dall’applicazione per evitare falsi requisiti nel manifest.

Importa i Samples

1. Apri Window > Package Manager, seleziona il pacchetto Snapdragon Spaces.
2. Clicca Import su Core Samples.
3. Aggiungi tutte le scene al build tramite Window > XR > Snapdragon Spaces > Add Scenes to Build Settings.

Importante: Il sample Camera Frame Access richiede la modalità unsafe abilitata in Player Settings > Android > Other Settings > Script Compilation > Allow ‘unsafe’ Code.

Passthrough Setup

Il Passthrough permette di visualizzare l’ambiente fisico come overlay di immagine su dispositivi VR. Su LeonardoXR è disponibile sui dispositivi compatibili.

• Si attiva tramite il pannello Extend Content nell’UI in-app (visibile solo su dispositivi compatibili con Passthrough).
• Può essere attivato anche con i tasti X e A del controller.
• La funzione di abilitazione è OnPassthroughToggle() in MainMenuSampleController, che imposta PassthroughToggle su BaseRuntimeFeature.

ATTENZIONE: La camera della sessione deve avere il canale Alpha del Background impostato su 0 per usare il Passthrough correttamente. Viene registrato un avviso automatico se le impostazioni sono errate.

Il delegate OnSpacesAppSpaceChange in BaseRuntimeFeature notifica quando il dispositivo esegue un recenter (attivato tenendo premuto il tasto menu per 2 secondi sul VRX).

Scene Setup

Nota: Questa guida presuppone conoscenza pregressa di AR Foundation e OpenXR. Consulta la documentazione ufficiale di AR Foundation e OpenXR per i concetti base.

Gerarchia Minima della Scena

Per abilitare il positional head tracking su LeonardoXR sono necessari i seguenti oggetti:

AR Session
XR Origin
  └── Camera Offset
        └── Main Camera (tagged as "MainCamera")

Creali facendo clic destro nella Hierarchy e selezionando XR > AR Session oppure XR > XR Origin.

Attenzione: Disabilita il componente AR Camera Manager se non stai recuperando frame RGB dalla camera, per evitare problemi nel lifecycle.
Importante: Disabilita il componente AR Camera Background — non è supportato e verrà disabilitato automaticamente a runtime.

Application Lifecycle — Compatibilità con Runtime Precedenti

La libreria Older Runtime Compatibility impedisce l’avvio dell’applicazione quando l’SDK non è compatibile con il runtime OpenXR installato sul dispositivo.

All’avvio vengono aggiunte due voci all’Android manifest:

• targetAPI — corrisponde alla versione del runtime OpenXR inclusa nell’SDK.
• minAPI — la versione minima del runtime che ciascuna feature supporta.

Versione: A partire da Snapdragon Spaces 1.0.4, il minAPI per tutte le features è 0.22.0.

Risultati di Compatibilità

Quando viene rilevata un’incompatibilità compare un popup con un messaggio di errore e un pulsante Quit. Per le app con Dual Render Fusion l’utente viene informato ma l’applicazione può comunque avviarsi.

Known Issues — VR/MR su LeonardoXR

Per problemi non elencati qui, consulta le known issues generali della piattaforma Snapdragon Spaces.

Gradle Build Issue

L’aggiunta di un archivio controller personalizzato può causare errori di caching Gradle. Eliminare la cartella Temp > gradleOut risolve generalmente il problema.

AR Foundation Issues

• AR Raycast Hit restituisce Trackable ID errato — ARRaycastHit.trackableId restituisce sempre 0-0.
• Plane Detection bloccata — La triangolazione mesh entra in un loop infinito in AR Foundation 6.2.1.

XRIT Issues

• AR Raycast Manager aggiunto automaticamente — XRIT 3.x aggiunge un AR Raycast Manager quando è presente un XR Raycast Interactor, abilitando lo Spatial Meshing indipendentemente dal flag EnableARRaycasting. Questo può ridurre le performance.
• Proprietà AR Mesh Manager non supportate — L’uso di proprietà non supportate genera avvisi a runtime.
• AR Camera Manager / AR Camera Background Issues — Spostarsi tra scene con AR Camera Manager abilitato può causare freeze. Disabilita AR Camera Background per evitare problemi di rendering.

Play In Editor Known Issues

• Memory Leak in Camera Access Simulation — Risolto in AR Foundation 6.0+.
• AR Mesh Manager crash senza Normals — Aggiorna AR Foundation o abilita le normals.
• QR Code Tracking non caricato in Simulation — Non esiste un subsystem di simulazione; aggira i controlli nelle build editor.
• ScriptableSingleton Warning — Risolto in AR Foundation 5.1.2+.