Advanced — LeonardoXR SDK

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

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

Funzionalità Avanzate — Snapdragon Spaces

Aggiungere un Nuovo Interaction Profile

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

Vai su Project Settings > XR Plug-in Management > OpenXR (scheda Android) > Interaction Profiles.
Aggiungi il profilo desiderato cliccando sul pulsante +.
Configura le Input Actions corrispondenti nell’Input System Asset.

Vedi anche Interaction Package Guides per la configurazione dei profili raccomandati su LeonardoXR.

Custom Controller

Descrive come costruire un archivio controller Android personalizzato (.aar) usando il Custom Controller Package — il progetto Android Studio incluso nel developer package.

Panoramica del Processo

Apri il progetto Android Studio incluso nel developer package di Snapdragon Spaces.
Modifica l’Activity companion secondo le necessità (layout, pulsanti, assi aggiuntivi).
Compila il progetto per ottenere un file .aar.
Importa il file .aar nel progetto Unity come plugin Android nativo (nella cartella Assets/Plugins/Android).
Configura il manifesto Android per dichiarare la nuova Activity.

Nota: L’aggiunta di un archivio controller personalizzato può causare errori di caching Gradle. Se si verificano errori di build, elimina la cartella Temp/gradleOut e ricompila.

Display Refresh Rate

L’estensione XR_EXT_display_refresh_rate consente di interrogare e impostare il refresh rate del display a runtime.

Query del Refresh Rate Corrente

using Qualcomm.Snapdragon.Spaces;

BaseRuntimeFeature baseRuntime = OpenXRSettings.Instance
    .GetFeature<BaseRuntimeFeature>();

float currentHz = baseRuntime.GetDisplayRefreshRate();
Debug.Log($"Refresh rate corrente: {currentHz} Hz");

Ottenere i Refresh Rate Supportati

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

Impostare il Refresh Rate

baseRuntime.RequestDisplayRefreshRate(90.0f);

Nota: Il refresh rate richiesto deve essere tra quelli restituiti da GetSupportedDisplayRefreshRates(). Valori non supportati vengono ignorati.

Advanced Android Thread Performance

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

Setup

Aggiungi il componente SpacesThreadUtility a un GameObject persistente nella scena (ad esempio lo stesso GameObject che ospita l’AR Session o l’XR Origin).

// SpacesThreadUtility non richiede configurazione:
// aggiungilo semplicemente come componente e si attiva automaticamente.
// Agisce sui thread Unity principali al momento dell'inizializzazione.

Quando Usarlo

Si raccomanda l’uso di SpacesThreadUtility in tutte le applicazioni LeonardoXR che mostrano jitter nel framerate o variabilità nel frame timing, specialmente in scene con heavy rendering o molti subsystem AR attivi.

Performance Settings

L’estensione OpenXR XR_EXT_performance_settings espone hint di livello performance per CPU e GPU tramite un nuovo metodo di BaseRuntimeFeature.

Livelli Disponibili

I livelli di performance vanno da PowerSavings (massimo risparmio energetico) a Boost (massima performance):

Livello	Descrizione
`PowerSavings`	Riduce clock CPU/GPU al minimo necessario. Utile per scene semplici o UI statiche.
`SustainedLow`	Performance sostenuta a livello basso.
`SustainedHigh`	Performance sostenuta ad alto livello. Raccomandata per la maggior parte delle app AR.
`Boost`	Performance massima per brevi periodi (non sostenibile a lungo).

Utilizzo

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

BaseRuntimeFeature baseRuntime = OpenXRSettings.Instance
    .GetFeature<BaseRuntimeFeature>();

// Imposta CPU e GPU a SustainedHigh
baseRuntime.SetPerformanceLevel(
    PerformanceDomain.Cpu,
    PerformanceLevel.SustainedHigh);

baseRuntime.SetPerformanceLevel(
    PerformanceDomain.Gpu,
    PerformanceLevel.SustainedHigh);

Nota: Il livello Boost consuma energia significativamente maggiore e può causare throttling termico se mantenuto a lungo. Usalo solo per operazioni critiche di breve durata (es. caricamento di una scena pesante).

Funzionalità Avanzate — LeonardoXR

QNN Inference Plugin — Guida Avanzata

⚠️ Documentazione in preparazione.
Questa sezione coprirà l’utilizzo avanzato del QNN (Qualcomm Neural Network) Inference Plugin su Leonardo XR, inclusi:
Preparazione e conversione di modelli (ONNX → QNN format).
Caricamento di modelli a runtime tramite le API del plugin.
Esecuzione di inferenza sull’NPU con gestione degli input/output tensor.
Gestione della memoria e ottimizzazione del throughput.
Debug e profiling delle performance di inferenza.
Casi d’uso: object detection, pose estimation, segmentazione in tempo reale.
La documentazione dettagliata sarà disponibile in una prossima versione.

Intercept OpenXR Function — Guida Avanzata

⚠️ Documentazione in preparazione.
Questa sezione coprirà l’utilizzo avanzato del meccanismo Intercept OpenXR Function su Leonardo XR, inclusi:
Architettura del layer di intercettazione OpenXR.
Registrazione di handler personalizzati per funzioni OpenXR specifiche.
Casi d’uso: override del rendering pipeline, injection di dati custom nel layer XR, debug a basso livello del comportamento OpenXR.
Considerazioni di sicurezza e stabilità.
Interazione con gli altri componenti dell’LeonardoXR SDK.
Questa funzionalità è destinata a sviluppatori con esperienza diretta con le API OpenXR a basso livello. La documentazione dettagliata sarà disponibile in una prossima versione.