Youbiquo — SDK LeonardoXR — Documentazione per sviluppatori

Indice dei documenti

01. Iniziare

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

Introduzione

Questa guida spiega come configurare un progetto Unity per lo sviluppo su Leonardo XR, il visore AR di Youbiquo basato su Snapdragon Spaces. L’obiettivo è familiarizzare gli sviluppatori con la configurazione dell’SDK per la creazione di applicazioni su Leonardo. La prossima guida illustrerà come interagire con i controller e le mani.

Leonardo XR utilizza Android 12 e segue un flusso di lavoro di sviluppo familiare a chiunque abbia già creato applicazioni Android.

Software richiesto

Prima di iniziare, assicurarsi che i seguenti software e pacchetti siano installati nelle versioni specificate:

NOTA: A differenza della guida base di Snapdragon Spaces (che raccomanda la versione 1.10.0 per Unity 2022), Unity 6 con LeonardoXR utilizza OpenXR 1.15.1. Non modificare manualmente questa versione: il Package Manager la gestisce tramite le dipendenze dell’SDK.

Crea un nuovo progetto

1. Apri Unity Hub e fai clic su Nuovo progetto.
2. Seleziona il modello Universal 3D.
3. Assegna un nome al progetto (ad esempio LeonardoXR_Test) e scegli una cartella di destinazione.
4. Fai clic su Crea progetto.

Dopo la creazione, Unity apre il progetto con una scena di esempio nel pannello Gerarchia.

Passa alla piattaforma Android

1. Dal menu principale, seleziona File > Crea profili.

2. Nella finestra Crea profili, seleziona Android dall’elenco Piattaforma.

3. Fai clic su Cambia piattaforma e attendi il completamento del processo.

4. Chiudi la finestra Crea profili.

Installa l’SDK di Snapdragon Spaces

IMPORTANTE: Snapdragon Spaces SDK deve essere installato prima di LeonardoXR SDK. Il runtime di LeonardoXR dipende da esso e non verrà compilato senza di esso.

1. Scarica Snapdragon Spaces SDK v1.0.4 dal portale per sviluppatori Qualcomm (è necessario un account sviluppatore): https://spaces.qualcomm.com/developer/vr-mr-sdk/#downloads
2. Apri Package Manager (Window > Package Manager).
3. Clic + e seleziona Add package from tarball…
4. Individua il file .tgz scaricato e fai clic su Apri. L’installazione si avvierà automaticamente.

Durante l’installazione potrebbero comparire due messaggi:

• “Abilitare il nuovo sistema di input?” → clic Yes.
• “XAggiornamento della maschera del livello di interazione R necessario” → oppure un nuovo progetto, clicca I Made a Backup, Go Ahead!

NOTA: L’editor si riavvierà dopo l’installazione: questo è un comportamento previsto, non un arresto anomalo. Per il controllo della versione, copiare il file .tgz nella cartella Packages/ del progetto prima di aggiungerlo; il manifesto utilizzerà quindi un percorso relativo, che è preferibile per il controllo della versione.

Unity 6.3+ — Problema comune dell’SDK Spaces: Dopo l’installazione, potrebbe comparire il seguente errore di compilazione:

BaseRuntimeFeature.InterceptEnvironmentBlendMode.cs(15,10): error CS0592:
Attribute 'SerializeField' is not valid on this declaration type.

Per risolvere il problema, fai doppio clic sull’errore nella Console per aprire il file, quindi rimuovi l’attributo [SerializeField] alla riga 15. Si tratta di un bug presente in Snapdragon Spaces 1.0.4 che si manifesta solo su Unity 6.3 e versioni successive.

Installare l’SDK di LeonardoXR

1. Scarica LeonardoXR SDK v1.0.2 dall’area sviluppatori di Youbiquo.
2. Apri il Package Manager (Window > Package Manager).
3. Clic + e sceli Add package from tarball…
4. Individua il file .tgz dell’SDK di LeonardoXR e fai clic su Open.

L’SDK verrà installato insieme alle sue dipendenze: OpenXR Plugin 1.15.1, AR Foundation 6.2.1, XR Interaction Toolkit 3.3.0, e XR Hands 1.7.2 — Non è richiesta alcuna installazione manuale di questi pacchetti.

Gestore SDK LeonardoXR

Dopo l’installazione dell’SDK LeonardoXR, Si aprirà automaticamente la finestra di LeonardoXR SDK Manager, Se non viene visualizzata, aprirla da LeonardoXR > SDK Manager nella barra dei menu.

La finestra ha due schede:

Setup tab — Mostra lo stato dei due pacchetti che non possono essere risolti automaticamente:

Una volta che entrambi i pacchetti mostrano ✓, la configurazione è completa. Utilizza il pulsante ↺ Aggiorna in qualsiasi momento per verificare nuovamente lo stato attuale.

About tab — Visualizza le informazioni sulla versione dell’SDK, del dispositivo e dell’editor Unity.

Configurazione di XR Plugin Management e OpenXR

Apri Project Settings

Vai a Edit > Project Settings e scegli XR Plug-in Management nella barra laterale sinistra.

Abilita OpenXR e Snapdragon Spaces

1. Clic su Android tab (in alto a destra della finestra).
2. Sotto Plug-in Providers, assicurarsi che entrambi siano controllati: OpenXR e Snapdragon Spaces feature group.

Configure OpenXR Features

1. Clic OpenXR nella barra laterale sinistra.
2. Nell’elenco delle funzionalità di Snapdragon Spaces, abilita solo Base Runtime e disabilitare tutte le altre. Le funzionalità avanzate (Hit Testing, Plane Detection, ecc.) possono essere abilitate in seguito, se necessario.

NOTA affinché il tracciamento delle mani funzioni correttamente su LeonardoXR, l’opzione Sottosistema di tracciamento delle mani deve essere abilitata nella sezione Tutte le funzionalità di OpenXR.

Aggiungi LeonardoXR Feature Group

1. Torna a XR Plug-in Management > Android.
2. Nell’elenco dei fornitori di plug-in, controlla anche LeonardoXR feature group.

Esecuzione della convalida del progetto

1. Nella barra laterale delle impostazioni del progetto, fai clic Project Validation.
2. La finestra mostra un elenco di errori di configurazione da correggere.
3. Clic Fix All per risolverli automaticamente.

NOTA Alcune correzioni potrebbero richiedere il riavvio dell’editor. Eseguire nuovamente la convalida dopo il riavvio per verificare che tutti gli errori siano stati risolti.

Importa campioni

Prima di creare le tue scene, è utile importare gli esempi inclusi in ciascun pacchetto. Per ogni pacchetto: open Window > Package Manager, scegli In Project, scegli il package, espandendo il sezione di Samples e clicca Import.

Dopo aver importato tutti i campioni, aggiungi le scene alla build tramite Window > XR > Snapdragon Spaces > Add Scenes to Build Settings.

Configurazione di URP

Impostazioni grafiche e di qualità

1. Apri Edit > Project Settings > Graphics.
2. Sotto Default Render Pipeline, clic il cerchio e scegli Mobile_RPAsset.
3. Vai a Project Settings > Quality.
4. Nella sezione Livelli, assicurati che Mobile ha una casella di controllo verde nella colonna Android. In caso contrario, fai clic su Fai clic sul triangolo predefinito sotto Android e seleziona Mobile.
5. Chusi Project Settings.

Configurazione di Assets URP 

In Assets/Settings, scegli Mobile_Renderer e applica:

• Rendering → Depth Priming Mode: impostare su disabilitato
• Shadows → Transparent Receive Shadows: deselezionare
• Post-processing → Enabled: deselezionare
• Renderer Feature → SSAO: assicurarsi che sia disabilitato o rimosso

Nel Assets/Settings, scegli Mobile_RPAsset e applica:

• HDR: disable
• Anti Aliasing (MSAA): set to 4x

Esegui nella configurazione dell’editor

Questa sezione descrive come configurare il progetto per lo sviluppo Play-In-Editor, riducendo la necessità di distribuire il progetto sul dispositivo a ogni modifica.

Impostazioni del progetto OpenXR

Vai a Edit > Project Settings > XR Plug-in Management e scegli il tab Windows, Mac, Linux.

Inizializza XR all’avvio — il valore deve corrispondere all’impostazione della scheda Android:

• Senza Dual Render Fusion → deve essere enabled.
• Con Dual Render Fusion → deve essere disabled.

NOTA Abilita il XR Simulation sul Windows/Mac/Linux tab per utilitzare AR Foundation simulation environments. Si noti che il tracciamento tramite codice QR non ha un sottosistema di simulazione equivalente.

Abilita la funzionalità di runtime di base per Windows/Mac/Linux

Vai a Edit > Project Settings > XR Plug-in Management > OpenXR (Windows, Mac, Linux tab) e abilita le funzionalità Base Runtime.

Configurazione della scena — Simulatore XR Spaces

Aggiungi il componente Spaces XR Simulator a un GameObject radice nella scena. Il componente persiste anche dopo il caricamento della scena (DontDestroyOnLoad) e può esistere una sola istanza alla volta.

Scorciatoie dell’editor Dual Render Fusion

NOTA Tutti i comportamenti finali devono essere sempre verificati sul dispositivo fisico, non solo nell’editor.

02 VR / MR

Versione 1.0.2 | Dispositivo: Youbiquo Leonardo XR | SDK di base: Snapdragon Spaces 1.0.4

Configurazione manuale del progetto

Si consiglia di utilizzare lo Strumento di configurazione per la configurazione iniziale del progetto (vedere la sezione “Per iniziare”). Questa guida descrive i passaggi manuali equivalenti per gli sviluppatori che preferiscono avere il controllo diretto sulle impostazioni.

Modifica le impostazioni del progetto

1. Vai su Edit > Project Settings > XR Plug-in Management e apri la scheda Android.

2. Abilita il plug-in OpenXR e il e il gruppo di funzionalità Snapdragon Spaces.

3. Fai clic sul punto esclamativo rosso accanto a OpenXR per aprire il OpenXR Project Validation.

4. Fai clic su Fix accanto a ciascun elemento.

5. Applica l’impostazione “Enable both Input Systems” scorsa, poiché richiede il riavvio dell’editor.

Abilita le funzionalità di Spaces

Nelle impostazioni di OpenXR, abilita le funzionalità che devono essere attive in fase di esecuzione. Ogni funzionalità corrisponde a un AR Foundation Manager e a un sottosistema XR:

Aggiungi i dati di utilizzo delle funzionalità al file AndroidManifest

Vai su Edit > Project Settings > Snapdragon Spaces Launcher Settings Dichiarare le funzionalità richieste o supportate dall’applicazione per: tracciamento della mano, tracciamento oculare, passthrough, controller e rilevamento della scala ambientale.

NOTA Per impostazione predefinita, tutti i valori di uses-feature sono impostati su true. Impostare le funzionalità non utilizzate su false per evitare requisiti errati nel manifesto.

Configurazione pass-through

La funzione Passthrough consente di visualizzare l’ambiente fisico come sovrapposizione di immagini sui dispositivi VR. Su LeonardoXR è disponibile sui dispositivi compatibili.

• Attivabile tramite il pannello “Extended contents” nell’interfaccia utente dell’app (visibile solo sui dispositivi compatibili con Passthrough).

• Può essere attivato/disattivato anche tramite i pulsanti X e A sul controller.

• La funzione di abilitazione è OnPassthroughToggle() in MainMenuSampleController, che imposta PassthroughToggle su BaseRuntimeFeature.

ATTENZIONE: affinché la funzione Passthrough funzioni correttamente, il Alpha channel dello sfondo della telecamera di sessione deve essere impostato su 0. In caso di impostazioni errate, verrà registrato automaticamente un avviso.

Il delegato OnSpacesAppSpaceChange in BaseRuntimeFeature notifica quando il dispositivo esegue un ricentraggio (attivato tenendo premuto il pulsante menu per 2 secondi sul VRX).

Impostazione della scena

NOTA Questa guida presuppone una conoscenza pregressa di AR Foundation e OpenXR. Per i concetti fondamentali, fare riferimento alla documentazione ufficiale di AR Foundation e OpenXR.

Gerarchia minima della scena

Per abilitare il tracciamento posizionale della testa su LeonardoXR sono necessari i seguenti oggetti:

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

Creali facendo clic con il pulsante destro del mouse nella gerarchia e selezionando XR > AR Session or XR > XR Origin.

NOTA Disabilita il AR Camera Manager se non stai recuperando frame RGB dalla fotocamera, per evitare problemi di ciclo di vita. Disabilita anche AR Camera Background — Non è supportato e verrà disabilitato automaticamente in fase di esecuzione.

Ciclo di vita dell’applicazione: 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 al manifest di Android:

• targetAPI — corrisponde alla versione runtime di OpenXR inclusa nell’SDK.
• minAPI — la versione minima di runtime supportata da ciascuna funzionalità.

NOTA A partire da Snapdragon Spaces 1.0.4, il minAPI per tutte le funzionalità è 0.22.0.

Problemi noti — VR/MR su LeonardoXR

NOTA Per i problemi non elencati qui, fare riferimento ai problemi noti in generale per la piattaforma Snapdragon Spaces.

Problema di compilazione Gradle

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

Problemi della Fondazione AR

• AR Raycast Hit returns wrong Trackable ID — ARRaycastHit.trackableId restituisce sempre 0-0.
• Plane Detection stalled — In AR Foundation 6.2.1, la triangolazione della mesh entra in un ciclo infinito.

Problemi XRIT

• AR Raycast Manager added automatically — XRIT 3.x aggiunge un AR Raycast Manager quando è presente un XR Raycast Interactor, abilitando la mesh spaziale indipendentemente dal flag EnableARRaycasting. Ciò potrebbe ridurre le prestazioni.
• Unsupported AR Mesh Manager properties — L’utilizzo di proprietà non supportate genera avvisi in fase di esecuzione.
• AR Camera Manager / AR Camera Background Issues — Il passaggio tra le scene con AR Camera Manager abilitato può causare blocchi. Disabilita AR Camera Background per evitare problemi di rendering.

Riproduzione nell’editor – Problemi noti

• Perdita di memoria nella simulazione di accesso alla telecamera — Risolto in AR Foundation 6.0+.
• Arresto anomalo di AR Mesh Manager senza Normals — Aggiorna AR Foundation o abilita le normali.
• Il tracciamento tramite codice QR non è stato caricato nella simulazione — Non esiste alcun sottosistema di simulazione; ignorare i controlli del sottosistema nelle build dell’editor.
• Avviso di ScriptableSingleton — Risolto in AR Foundation 5.1.2+.

03 Funzionalità

Versione 1.0.2 | Dispositivo: Youbiquo Leonardo XR | SDK di base: Snapdragon Spaces 1.0.4

Questa pagina documenta le funzionalità disponibili nell’SDK di LeonardoXR, organizzate in due sezioni:

• Funzionalità di Snapdragon Spaces — Funzionalità AR/XR fornite dalla piattaforma Snapdragon Spaces, accessibili tramite AR Foundation.
• Funzionalità di LeonardoXR — Funzionalità proprietarie specifiche di Leonardo XR.

Funzionalità di Snapdragon Spaces

Ancore locali

Come abilitare

Vai su Project Settings > XR Plug-in Management > OpenXR (Android) > Snapdragon Spaces > Spatial Anchors e abilita la funzione.

Negozio Spaces Anchor

NOTA Osserva l’ambiente circostante per generare una mappa di tracciamento migliore e ridurre i tempi di salvataggio/caricamento. Il salvataggio simultaneo di più ancore blocca il thread principale: utilizza la funzione di callback per salvare le ancore successive in sequenza.

namespace Qualcomm.Snapdragon.Spaces
{
    public class SpacesAnchorStore
    {
        public void ClearStore();
        public void SaveAnchor(ARAnchor anchor, string anchorName, Action<bool> onSavedCallback = null);
        public void SaveAnchorWithResult(ARAnchor anchor, string anchorName, Action<SaveAnchorResult> callback = null);
        public void DeleteSavedAnchor(string anchorName);
        public void LoadSavedAnchor(string anchorName, Action<bool> onLoadedCallback = null);
        public void LoadAllSavedAnchors(Action<bool> onLoadedCallback = null);
        public string[] GetSavedAnchorNames();
        public string GetSavedAnchorNameFromARAnchor(ARAnchor anchor);
    }
}

Riferimento API

Valori di SaveAnchorResult

Hit test

Abilita tramite Project Settings > XR Plug-in Management > OpenXR (Android) > Snapdragon Spaces > Hit Testing.

Utilizza AR Raycast Manager di AR Foundation (XRRaycastSubsystem). Supporta il rilevamento continuo di intersezioni con piani e mesh del mondo reale. Il sistema proietta un raggio dalla telecamera (o da un punto specificato) e restituisce le intersezioni con le superfici rilevate. Ogni intersezione contiene posizione, normale e tipo di superficie (piano o mesh).

List<ARRaycastHit> hits = new List<ARRaycastHit>();
if (raycastManager.Raycast(screenCenter, hits, TrackableType.PlaneWithinPolygon))
{
    Pose hitPose = hits[0].pose;
    // Place AR content at hitPose.position
}

ATTENZIONE: ARRaycastHit.trackableId restituisce sempre 0-0. (Problema noto)

Tracciamento delle immagini

Abilita tramite Project Settings > XR Plug-in Management > OpenXR (Android) > Snapdragon Spaces > Image Tracking. Utilizza il AR Tracked Image Manager (XRImageTrackingSubsystem). Supporta librerie di immagini di riferimento statiche e modificabili (in fase di esecuzione).

// Mutable library example
var library = trackedImageManager.CreateRuntimeLibrary() as MutableRuntimeReferenceImageLibrary;
await library.ScheduleAddImageWithValidationJob(texture, "image-name", 0.1f); // 0.1f = physical width in metres
trackedImageManager.referenceLibrary = library;

Rilevamento aereo

Abilita tramitte Project Settings > XR Plug-in Management > OpenXR (Android) > Snapdragon Spaces > Plane Detection. Utiliza il AR Plane Manager (XRPlaneSubsystem). L’utilizzo del backend di comprensione della scena è abilitato per impostazione predefinita.

arPlaneManager.requestedDetectionMode = PlaneDetectionMode.Horizontal | PlaneDetectionMode.Vertical;

ATTENZIONE In AR Foundation 6.0, la funzione di rilevamento dei piani entra in un ciclo infinito di triangolazione della mesh. In Unity 6 + OpenXR 1.15.1, la funzione di rilevamento dei piani non funziona nelle app Dual Render Fusion.

Accesso alla cornice della fotocamera

Abilita tramitte Project Settings > XR Plug-in Management > OpenXR (Android) > Snapdragon Spaces > Camera Frame Access. Utiliza il AR Camera Manager (XRCameraSubsystem). Funzionalità chiave:

• Raw camera frame access in YUV (Y’UV420sp) and YUYV / YUY2 formats.
• XRCpuImage.GetPlane(int) for CPU-side image access.
• XRCpuImage.ConvertAsync for asynchronous conversion.
• GPU-accelerated RGB frame access for AiO devices (via OpenGL).
• Sensor extrinsics / pose retrieval via InputBindings.

NOTA Abilita il Allow ‘unsafe’ Code in Player Settings > Android > Other Settings > Script Compilation Quando si utilizza l’esempio Camera Frame Access, disabilitare AR Camera Background per evitare problemi di rendering.

void OnCameraFrameReceived(ARCameraFrameEventArgs args)
{
    if (cameraManager.TryAcquireLatestCpuImage(out XRCpuImage image))
    {
        using (image)
        {
            XRCpuImage.Plane yPlane = image.GetPlane(0); // Luminance plane
            // yPlane.data contains the raw data
        }
    }
}

Mesh spaziale

Abilita il Project Settings > XR Plug-in Management > OpenXR (Android) > Snapdragon Spaces > Spatial Meshing. Utiliza il AR Mesh Manager (XRMeshSubsystem). Il componente opzionale SpacesARMeshManagerConfig controlla le caratteristiche della mesh e gli offset di altezza della telecamera per TrackingOriginMode.Floor.

Monitoraggio del codice QR

Abilita tramitte Project Settings > XR Plug-in Management > OpenXR (Android) > Snapdragon Spaces > QR Code Tracking. Utilizza il componente personalizzato SpacesQrCodeManager. Supporta diverse modalità di tracciamento per controllare la frequenza di aggiornamento dell’algoritmo.

// Editor build workaround (no simulation subsystem for QR Code Tracking)
bool CheckSubsystem()
{
#if UNITY_EDITOR
    return arQrCodeManager.subsystem?.running ?? false;
#else
    return true;
#endif
}

Tracciamento delle mani

Abilita tramitte Project Settings > XR Plug-in Management > OpenXR (Android) > Snapdragon Spaces > Hand Tracking. Il tracciamento delle mani è fornito dai pacchetti di plugin QCHT (Qualcomm Hand Tracking). LeonardoXR utilizza il pacchetto Unity XR Hands (v1.7.2) come livello di accesso ai dati per i dati articolari, integrato con le estensioni QCHT.

NOTA Affinché il tracciamento delle mani funzioni correttamente su LeonardoXR, l’opzione “Sottosistema di tracciamento delle mani” deve essere attiva in “Tutte le funzioni” di OpenXR.

Per l’integrazione completa del tracciamento della mano con XR Interaction Toolkit, consultare il documento Interaction Package Guides

Rendering fovetato

Abilita tramitte Project Settings > XR Plug-in Management > OpenXR (Android) > Snapdragon Spaces > Foveated Rendering. Riduce il carico sulla GPU eseguendo il rendering della periferia del campo visivo a una risoluzione inferiore. Le impostazioni di foveazione vengono mantenute anche dopo la pausa e la ripresa dell’applicazione.

Funzionalita di LeonardoXR

Le seguenti funzionalità sono specifiche di Leonardo XR e non fanno parte della piattaforma base Snapdragon Spaces. Abilitale tramite Project Settings > XR Plug-in Management > OpenXR (Android) > LeonardoXR feature group.

Accesso alla doppia fotocamera

DOCUMENTAZIONE IN CORSO Questa funzionalità consente l’accesso sincronizzato ai fotogrammi di entrambe le fotocamere Leonardo XR. La documentazione API dettagliata, la configurazione e gli esempi saranno disponibili in una versione futura.

Plugin di inferenza QNN

DOCUMENTAZIONE IN CORSO Questa funzionalità espone le capacità di inferenza neurale dell’hardware Leonardo XR tramite il runtime Qualcomm Neural Network (QNN), consentendo l’esecuzione di modelli di IA/ML direttamente sulla NPU del dispositivo. La documentazione API dettagliata, il flusso di lavoro di conversione dei modelli e gli esempi saranno disponibili in una versione futura.

Intercetta la funzione OpenXR

DOCUMENTAZIONE IN CORSO Questa funzionalità avanzata fornisce un meccanismo per intercettare e sovrascrivere le funzioni OpenXR di basso livello. È pensata per casi d’uso specifici che richiedono il controllo diretto sul livello OpenXR. La documentazione dettagliata sarà disponibile in una versione futura.

04 Guida ai campioni

Versione 1.0.2 | Dispositivo: Youbiquo Leonardo XR | SDK di base: Snapdragon Spaces 1.0.4

I campioni sono organizzati in due sezioni:

• Campioni LeonardoXR — campioni specifici per le funzionalità proprietarie di Leonardo XR.
• Esempi principali di Snapdragon Spaces — Esempi forniti da Qualcomm per le funzionalità AR/XR di base.

Importazione di campioni

Esempi principali di Snapdragon Spaces

Il pacchetto Core Samples è importabile da Window > Package Manager > Snapdragon Spaces > Core Samples. Dopo l’importazione, aggiungi tutte le scene alla build tramite Window > XR > Snapdragon Spaces > Add Scenes to Build Settings.

Campioni principali LeonardoXR

Il pacchetto LeonardoXR Core Samples è importabile da Window > Package Manager > LeonardoXR > Core Samples. Dopo l’importazione, le scene sono disponibili in Samples/LeonardoXR/[version]/Core Samples/Scenes/.

Campioni LeonardoXR

Esempio di accesso con doppia fotocamera

DOCUMENTAZIONE IN CORSO Questo esempio mostrerà come accedere ai fotogrammi sincronizzati da entrambe le fotocamere Leonardo XR tramite la funzione Dual Camera Access.

• Scena: Samples/LeonardoXR/.../Core Samples/Scenes/DualCameraAccess
• Prerequisiti: Accesso a doppia fotocamera abilitato nel gruppo di funzionalità LeonardoXR.

Esempio di funzione Intercetta OpenXR

DOCUMENTAZIONE IN CORSO Questo esempio mostrerà come intercettare le funzioni OpenXR di basso livello tramite la funzionalità InterceptOpenXRFunction.

• Scena: Samples/LeonardoXR/.../Core Samples/Scenes/InterceptOpenXRFunction
• Prerequisiti: Intercept OpenXR Function enabled in LeonardoXR feature group.

Esempi principali di Snapdragon Spaces

Esempio di ancore locali

• Scena: Samples/Snapdragon Spaces/.../Core Samples/Scenes/Anchor

Questo esempio mostra come creare e distruggere punti di ancoraggio locali per tracciare con precisione un punto nel mondo reale. Richiede che la funzione “Spatial Anchors” sia abilitata in OpenXR.

Come funziona

Un dispositivo di posizionamento trasparente fluttua a 1 metro di distanza dalla telecamera. Quando l’opzione “Posiziona ancoraggio sulle superfici” è abilitata, un raggio viene proiettato in avanti a ogni fotogramma. Quando una superficie viene colpita, il dispositivo diventa giallo. Toccando il touchpad o utilizzando l’interattore oculare si crea un ARAnchor con un dispositivo di tracciamento.

private void OnAnchorsChanged(ARAnchorsChangedEventArgs args)
{
    foreach (var anchor in args.updated)
    {
        Destroy(anchor.transform.GetChild(0).gameObject);
        var newGizmo = Instantiate(
            anchor.trackingState == TrackingState.None
                ? GizmoUntrackedAnchor
                : GizmoTrackedAnchor);
        newGizmo.transform.SetParent(anchor.transform, false);
    }
}

Salvataggio, eliminazione e caricamento degli ancoraggi

• Abilita “Salva nuovi ancoraggi nella memoria locale” per rendere persistente ogni nuovo ancoraggio.

• Cubo bianco sul gizmo = ancoraggio salvato e tracciato; cubo rosso = ancoraggio non tracciato.

• Carica tutti gli ancoraggi salvati: carica e tenta di localizzare tutti gli ancoraggi memorizzati.

• Svuota la memoria: elimina tutti gli ancoraggi memorizzati (non distrugge gli ancoraggi già caricati).

• Distruggi tutti gli ancoraggi: distrugge tutti i GameObject di ancoraggio attivi (con un breve ritardo).

Esempio di tracciamento delle mani

• Scena: Samples/.../Core Samples/Scenes/HandTracking

Dimostra la visualizzazione delle articolazioni della mano e il riconoscimento dei gesti tramite il pacchetto di interazione QCHT. Richiede i pacchetti Hand Tracking e QCHT/XR Hands.

Esempio di hit test

• Scena: Samples/.../Core Samples/Scenes/HitTesting

Dimostra il rilevamento continuo di collisioni tramite raycast su piani e mesh del mondo reale utilizzando ARRaycastManager. Mostra come posizionare oggetti virtuali sulle superfici rilevate.

Esempio di monitoraggio delle immagini

• Scena: Samples/.../Core Samples/Scenes/ImageTracking

Dimostra il tracciamento di immagini di riferimento stampate e la sovrapposizione di contenuti virtuali. Supporta librerie di immagini statiche e modificabili.

Esempio di rilevamento aereo

• Scena: Samples/.../Core Samples/Scenes/PlaneDetection

Dimostra il rilevamento e la visualizzazione di piani orizzontali e verticali tramite ARPlaneManager. Supporta le modalità di rilevamento e i piani convessi opzionali.

Esempio di accesso al frame della fotocamera

• Scena: Samples/.../Core Samples/Scenes/CameraFrameAccess

Dimostra il recupero dei frame raw della telecamera (YUV/YUYV) utilizzando ARCameraManager. Include informazioni estrinseche del sensore, query sul conteggio delle telecamere e accesso ai frame accelerato dalla GPU. Richiede l’opzione Allow ‘unsafe’ Code nelle impostazioni del lettore.

Esempio di mesh spaziale

• Scena: Samples/.../Core Samples/Scenes/SpatialMeshing

Dimostra la creazione di mesh ambientali in tempo reale utilizzando ARMeshManager. Include un cursore per la regolazione dell’opacità e il componente opzionale SpacesARMeshManagerConfig.

Esempio di tracciamento tramite codice QR

• Scena: Samples/.../Core Samples/Scenes/QRCodeTracking

Dimostra la scansione e il tracciamento dei codici QR tramite SpacesQrCodeManager. Sono disponibili diverse modalità di tracciamento.

Esempio di toolkit di interazione XR

• Scena: Samples/.../Core Samples/Scenes/XRInteractionToolkit

Dimostra le interazioni XRIT standard (interagenti a raggio, interagenti diretti, teletrasporto) in un progetto Snapdragon Spaces. Compatibile con la configurazione LeonardoXR.

Componenti dello strato di composizione

Il livello di The Spaces Composition renderizza le texture direttamente sull’HMD, bypassando le fasi di post-elaborazione. I tipi di geometria supportati sono Quad, Cilindro, Sfera e Cubo. Utile per interfacce utente ad alta nitidezza o elementi che devono mantenere la qualità indipendentemente dagli effetti della scena.

Campioni aggiuntivi

05 Guide ai pacchetti di interazione

Versione 1.0.2 | Dispositivo: Youbiquo Leonardo XR | SDK di base: Snapdragon Spaces 1.0.4

Questa guida descrive come configurare il livello di interazione per le applicazioni LeonardoXR utilizzando i pacchetti standard di Unity:

• XR Interaction Toolkit (XRIT) 3.3.0 — Sistema di interazione di alto livello per controllori, interattori a raggio e interattori diretti.
• XR Hands 1.7.2 — accesso ai dati articolari della mano e riconoscimento dei gesti.

Dipendenze e versioni

NOTA: Tutte le dipendenze devono essere installate come descritto nella guida introduttiva prima di procedere con la configurazione dell’interazione.

1. Configurazione del toolkit di interazione XR

Installazione

Installa tramite Window > Package Manager > Unity Registry > XR Interaction Toolkit > Install (version 3.3.0). Se viene richiesto “Enable the new input system?”, clic Yes. Se viene richiesto “XR Interaction Layer Mask Update Required”, clic I Made a Backup, Go Ahead! (per nuovi progetti) o No Thanks se non era presente alcuna versione precedente di XRIT.

Importa risorse iniziali

1. Apri Window > Package Manager, scegli In Project poi XR Interaction Toolkit.
2. Sotto Samples, clic Import su Starter Assets.
3. Clic anche su Import su Hand Interaction Demo (richiesto per i campioni di tracciamento manuale).

Le risorse iniziali includono:

• Asset di input preconfigurato per controller e mani XR.
• Prefab di riferimento per XR Origin con Ray Interactor e Direct Interactor.
• Materiali di base e shader per il feedback visivo dell’interazione.

Configura le azioni di input

Dopo l’importazione, un XRI Default Input Actions la risorsa viene aggiunta Assets/Samples/XR Interaction Toolkit/[version]/Starter Assets/.Questo asset è preconfigurato per i profili controller standard (incluso il Companion Controller tramite il profilo Microsoft MMRC) e per le mani.

Per associare la risorsa al sistema: vai a Edit > Project Settings > XR Plug-in Management > Input System e garantire Active Input Handling è impostato su Both o Input System Package (New).

2. Configurazione della scena — XR Origin

Gerarchia della scena di base

AR Session
XR Origin (Action-based)
  └── Camera Offset
        ├── Main Camera (tagged "MainCamera")
        ├── LeftHand Controller
        │     ├── XR Ray Interactor (left)
        │     └── XR Direct Interactor (left)
        └── RightHand Controller
              ├── XR Ray Interactor (right)
              └── XR Direct Interactor (right)

Crea la struttura di base selezionando GameObject > XR > XR Origin (Action-based).

NOTA Disabilita AR Camera Background —Non supportato su LeonardoXR e disabilitato automaticamente in fase di esecuzione. Disabilitare anche AR Camera Manager se non si acquisiscono frame RGB dalla fotocamera.

Gestore delle azioni di input

Aggiunga il componente Input Action Manager all’origine XR (o a un GameObject persistente). Nel Campo di Action Assets assegna:

• XR Input Actions (from Samples/LeonardoXR SDK/[version]/Core Samples/Shared Assets).

3. Configurazione delle lancette XR

Installazione

Installa tramite Window > Package Manager > Unity Registry > XR Hands > Install (versione 1.7.2).

Importa campioni manuali

Apri Window > Package Manager > In Project > XR Hands > Samples e importa:

• Gestures — sistema di riconoscimento dei gesti.
• Hand Visualizer — Visualizzazione della mesh manuale.

Abilita il sottosistema di tracciamento della mano

1. Vai a Edit > Project Settings > XR Plug-in Management > OpenXR (Android tab).
2. Sotto All Features, abilita Hand Tracking Subsystem.
3. Abilita anche Hand Tracking nel Snapdragon Spaces feature group.

NOTA Il sottosistema di tracciamento della mano deve essere abilitato in “All Features”, non solo nella sezione “Snapdragon Spaces”, affinché funzioni correttamente su LeonardoXR.

Accesso ai dati della mano tramite l’API XR Hands

using UnityEngine.XR.Hands;

XRHandSubsystem handSubsystem = XRHandSubsystemUtility.GetSubsystem();
if (handSubsystem != null)
{
    XRHand leftHand = handSubsystem.leftHand;
    if (leftHand.isTracked)
    {
        if (leftHand.GetJoint(XRHandJointID.IndexTip).TryGetPose(out Pose indexTipPose))
        {
            // indexTipPose.position = position of left index fingertip
        }
    }
}

Riconoscimento dei gesti

[SerializeField] XRHandGestures gestures;

void OnEnable()
{
    gestures.gesturePerformed += OnGesturePerformed;
}

void OnGesturePerformed(XRHandGesture gesture, Handedness handedness)
{
    Debug.Log($"Gesture: {gesture.gestureName} performed with {handedness}");
}

4. Configurazione degli elementi interattivi

Aggiungere un elemento interattivo a un oggetto

1. Add a Collider to the object (e.g. Box Collider).
2. Add XR Grab Interactable for grabbable objects, or XR Simple Interactable for objects that receive events without being moved.

public class MyButton : MonoBehaviour
{
    [SerializeField] XRSimpleInteractable interactable;

    void OnEnable()
    {
        interactable.selectEntered.AddListener(OnSelected);
    }

    void OnSelected(SelectEnterEventArgs args)
    {
        Debug.Log("Selected by: " + args.interactorObject);
    }
}

Maschera del livello di interazione

XRIT 3.x utiliza Interaction Layer Masks per filtrare quali interattori possono interagire con quali oggetti interattivi:

interactable.interactionLayers = InteractionLayerMask.GetMask("Default", "UI"); 

5. Canvas dell’interfaccia utente e interazione

Tela dello spazio mondiale

1. Crea un Canvas e impostare Render Mode a World Space.
2. Aggiungi il Tracked Device Graphic Raycaster componente per Canvas (sostituisce il Graphic Raycaster standard).
3. Aggiungi XR UI Input Module all’oggetto di gioco EventSystem nella scena (sostituisce il modulo di input predefinito Input System UI).

Impostazioni tela consigliate

6. Combinazione di controllo e tracciamento della mano

Su LeonardoXR non è possibile utilizzare contemporaneamente i controller del visore e il tracciamento completo delle mani (con raycast da entrambe le mani) a causa di conflitti tra i profili OpenXR.

Option A — Solo controller (controller ausiliario)

• Aggiungi il Microsoft MMRC Profile ai profili abilitati.
• Non aggiungere il profilo di interazione manuale.
• Il Companion Controller gestisce l’indicazione; le mani possono essere utilizzate come collider ma non come interattori raycast.

Option B — Solo mani (modalità a due mani)

• Aggiungi il Hand Interaction Profile ai profili abilitati.
• Non aggiungere il profilo Microsoft MMRC.
• Rimuovere il Prefab Device Pointer dal Controller.
• Entrambe le mani sono state tracciate come interattori completi; nessun input dal telefono.

Option C — Controller + One Hand

• Aggiungi il Microsoft MMRC Profile ai profili abilitati.

• Nell’XR Origin, mantieni attivo solo il controller destro.
• La mano sinistra può ancora funzionare come punto di collisione e come trigger di interazione “poke”, ma non come interattore di raggi.

7. UniTask — Asynchronous Operations

UniTask 2.5.10 è incluso come dipendenza per operazioni asincrone ad alte prestazioni (caricamento di risorse, attesa di sottosistemi, ecc.) senza allocazioni di garbage collection.

using Cysharp.Threading.Tasks;

public class HandSubsystemWaiter : MonoBehaviour
{
    async UniTaskVoid Start()
    {
        // Wait until the XR Hands subsystem is ready
        await UniTask.WaitUntil(() =>
            XRHandSubsystemUtility.GetSubsystem()?.running ?? false);
        Debug.Log("XR Hands subsystem ready.");
    }
}

UniTask viene utilizzato internamente dall’SDK di LeonardoXR per le operazioni asincrone. Si consiglia di utilizzarlo anche nel codice dell’applicazione per coerenza con il ciclo di vita dell’SDK.

Riferimento al profilo di interazione OpenXR

06 Avanzato

Versione 1.0.2 | Dispositivo: Youbiquo Leonardo XR | SDK Base: Snapdragon Spaces 1.0.4

Questa sezione illustra le configurazioni e le funzionalità avanzate disponibili su LeonardoXR, suddivise in funzionalità generali della piattaforma Snapdragon Spaces e funzionalità avanzate proprietarie di LeonardoXR.

Avanzato — Snapdragon Spaces

Aggiungere un nuovo profilo di interazione

Per utilizzare un profilo di interazione non incluso nel plugin Snapdragon Spaces:

1. Vai a Project Settings > XR Plug-in Management > OpenXR (Android) > Interaction Profiles.
2. Aggiungi il profilo desiderato facendo clic sul pulsante + .
3. Configura le corrispondenti azioni di input nell’asset del sistema di input.

Controller personalizzato

Descrive come creare un archivio controller Android personalizzato (.aar) utilizzando il Custom Controller Package, ovvero il progetto Android Studio incluso nel pacchetto per sviluppatori.

Panoramica del processo

1. Apri il progetto Android Studio incluso nel pacchetto di sviluppo Snapdragon Spaces.
2. Modifica l’attività complementare secondo necessità (layout, pulsanti, assi aggiuntivi).
3. Compila il progetto per ottenere un file .aar.
4. Importa il file .aar nel progetto Unity come plugin nativo Android (nella cartella Assets/Plugins/Android).
5. Configura il manifest Android per dichiarare la nuova Activity.

NOTE L’aggiunta di un archivio controller personalizzato può causare errori di cache di Gradle. Se si verificano errori di compilazione, eliminare la cartella Temp/gradleOut e ricompilare..

Visualizza la frequenza di aggiornamento

The XR_EXT_display_refresh_rate extension allows querying and setting the display refresh rate at runtime.

Interroga la frequenza di aggiornamento corrente

using Qualcomm.Snapdragon.Spaces;

BaseRuntimeFeature baseRuntime = OpenXRSettings.Instance.GetFeature<BaseRuntimeFeature>();
float currentHz = baseRuntime.GetDisplayRefreshRate();
Debug.Log($"Current refresh rate: {currentHz} Hz");

Get Supported Refresh Rates

float[] supportedRates = baseRuntime.GetSupportedDisplayRefreshRates();
foreach (float rate in supportedRates)
    Debug.Log($"Supported: {rate} Hz");

Imposta la frequenza di aggiornamento

baseRuntime.RequestDisplayRefreshRate(90.0f);

NOTE La frequenza di aggiornamento richiesta deve essere tra quelle restituite da GetSupportedDisplayRefreshRates(). I valori non supportati verranno ignorati.

Prestazioni avanzate del thread Android

Il componente SpacesThreadUtility migliora la priorità di pianificazione dei thread su Android, producendo una temporizzazione dei frame più coerente.

Setup

Aggiungi il componente SpacesThreadUtility a un GameObject persistente nella scena (ad esempio, lo stesso GameObject che ospita la sessione AR o l’origine XR). Non è richiesta alcuna configurazione: si attiva automaticamente all’avvio e agisce sui thread principali di Unity.

Quando usarlo

Consigliato per tutte le applicazioni LeonardoXR che presentano fluttuazioni del frame rate o variabilità nella temporizzazione dei fotogrammi, soprattutto in scene con rendering intensivo o con molti sottosistemi AR attivi.

Impostazioni delle prestazioni

L’estensione OpenXR XR_EXT_performance_settings espone suggerimenti sui livelli di prestazioni per CPU e GPU tramite un nuovo metodo su BaseRuntimeFeature.

using Qualcomm.Snapdragon.Spaces;
using UnityEngine.XR.OpenXR;

BaseRuntimeFeature baseRuntime = OpenXRSettings.Instance.GetFeature<BaseRuntimeFeature>();
baseRuntime.SetPerformanceLevel(PerformanceDomain.Cpu, PerformanceLevel.SustainedHigh);
baseRuntime.SetPerformanceLevel(PerformanceDomain.Gpu, PerformanceLevel.SustainedHigh);

NOTE Il livello Boost consuma molta più energia e, se utilizzato in modo continuativo, può causare surriscaldamento e conseguente limitazione della velocità di elaborazione. Utilizzatelo solo per operazioni critiche di breve durata (ad esempio, il caricamento di una scena complessa).

Advanced — LeonardoXR

QNN Inference Plugin — Advanced Guide

DOCUMENTATION IN PROGRESS This section will cover advanced usage of the QNN (Qualcomm Neural Network) Inference Plugin on Leonardo XR, including:

• Model preparation and conversion (ONNX → QNN format).
• Loading models at runtime via plugin APIs.
• Running inference on the NPU with input/output tensor management.
• Memory management and throughput optimisation.
• Debug and performance profiling of inference.
• Use cases: object detection, pose estimation, real-time segmentation.

Detailed documentation will be available in a future release.

Intercept OpenXR Function — Advanced Guide

DOCUMENTATION IN PROGRESS This section will cover advanced usage of the Intercept OpenXR Function mechanism on Leonardo XR, including:

• Architecture of the OpenXR interception layer.
• Registering custom handlers for specific OpenXR functions.
• Use cases: rendering pipeline override, custom data injection into the XR layer, low-level OpenXR debugging.
• Safety and stability considerations.
• Interaction with other LeonardoXR SDK components.

This feature is intended for developers with direct experience of low-level OpenXR APIs. Detailed documentation will be available in a future release.