Conversione di app HoloLens (prima generazione) in HoloLens 2Porting HoloLens (1st Gen) apps to HoloLens 2

Questa guida è progettata appositamente per aiutare gli sviluppatori con un'applicazione Unity per HoloLens (prima generazione) a convertirla per il dispositivo HoloLens 2.This guide is tailored to help developers with an existing Unity application for HoloLens (1st gen) port their application for the HoloLens 2 device. Per la conversione di un'applicazione Unity da HoloLens (prima generazione) a HoloLens 2, è necessario completare quattro passaggi.There are four key steps to porting a HoloLens (1st gen) Unity application to HoloLens 2.

Le sezioni seguenti forniscono informazioni dettagliate per ogni fase:The sections below detail information for each stage:

Passaggio 1Step 1 Passaggio 2Step 2 Passaggio 3Step 3 Passaggio 4Step 4
Logo di Visual Studio Logo di Unity Icona di Unity Logo di MRTK
Scaricare gli strumenti più recentiDownload latest tools Aggiornare un progetto UnityUpdate Unity Project Eseguire la compilazione per ARMCompile for ARM Eseguire la migrazione a MRTK v2Migrate to MRTK v2

PrerequisitiPrerequisites

Prima di iniziare il processo di conversione, è consigliabile usare il controllo del codice sorgente per salvare uno snapshot dello stato originale dell'applicazione.We highly recommended using source control to save a snapshot your applications original state before starting the porting process. Inoltre, è consigliabile salvare gli stati dei checkpoint in vari momenti durante il processo.Additionally, we recommend saving checkpoint states at various times during the process. Può anche essere utile avere un'altra istanza Unity dell'applicazione originale per eseguire il confronto affiancato durante il processo di conversione.It can also be helpful to have another Unity instance of the original application to compare side by side during the porting process.

Nota

Prima della conversione, assicurati che siano installati gli strumenti più recenti per lo sviluppo con Windows Mixed Reality.Before porting, ensure you have the latest tools installed for Windows Mixed Reality development. Per la maggior parte degli attuali sviluppatori HoloLens, questo passaggio comporta l'aggiornamento all'ultima versione di Visual Studio 2019 e l'installazione dell'istanza appropriata di Windows SDK.For most existing HoloLens developers, this involves updating to the latest version of Visual Studio 2019 and installing the appropriate Windows SDK. Di seguito verranno analizzate in dettaglio diverse versioni di Unity e Mixed Reality Toolkit (MRTK) versione 2.The content that follows dives further into different Unity versions and the Mixed Reality Toolkit (MRTK) Version 2.

Per altre informazioni, vedi Installare gli strumenti.For more information, please see Install the tools.

Eseguire la migrazione del progetto all'ultima versione di UnityMigrate project to the latest version of Unity

Se si usa MRTK v2, Unity 2019 LTS è il percorso di supporto a lungo termine ottimale senza modifiche di rilievo in Unity o in MRTK.If you're using MRTK v2, Unity 2019 LTS is the best long-term support path with no breaking changes in Unity or in MRTK. Valutare tutte le dipendenze da plug-in attualmente esistenti nel progetto e stabilire se è possibile creare le DLL per ARM64.Assess any plugin dependencies that currently exist in your project, and determine whether these DLLs can be built for ARM64. Per i progetti con un plug-in fortemente dipendente da ARM64, può essere necessario continuare a creare l'app per ARM.For projects with a hard ARM64 dependent plugin, you may need to continue building your app for ARM.

Aggiornare le impostazioni di scena o progetto in UnityUpdate scene/project settings in Unity

Dopo l'aggiornamento a Unity 2019 LTS, è consigliabile aggiornare specifiche impostazioni di Unity per ottenere risultati ottimali nel dispositivo.After updating to Unity 2019 LTS, it's recommended that you update particular settings in Unity for optimal results on the device. Queste impostazioni sono descritte in dettaglio nella sezione Impostazioni consigliate per Unity.These settings are outlined in detail under recommended settings for Unity.

Si ribadisce che il back-end di scripting .NET è stato deprecato in Unity 2018 e rimosso in Unity 2019.To reiterate, the .NET scripting back-end is being deprecated in Unity 2018 and removed in Unity 2019. Per gli sviluppatori è consigliabile passare a IL2CPP per il loro progetto.Developers should strongly consider switching their project to IL2CPP.

Nota

Il back-end di scripting IL2CPP può comportare tempi di compilazione da Unity a Visual Studio più lunghi, quindi gli sviluppatori devono configurare i computer di sviluppo in modo da ottimizzare i tempi di compilazione di IL2CPP.IL2CPP scripting back-end can cause longer build times from Unity to Visual Studio, and developers should set up their developer machine for optimizing IL2CPP build times. Inoltre, potrebbe essere utile configurare un server di cache, soprattutto per i progetti Unity con una grande quantità di asset (esclusi i file di script) o con asset e scene che cambiano continuamente.It might also be beneficial to set up a cache server, especially for Unity projects with a large amount of assets (excluding script files) or constantly changing scenes and assets. All'apertura di un progetto, Unity archivia gli asset validi in un formato della cache interna nel computer di sviluppo.When opening a project, Unity stores qualifying assets into an internal cache format on the developer machine. Gli elementi devono essere reimportati e rielaborati in caso di modifica.Items must be re-imported and re-processed when modified. Questo processo può essere eseguito una volta sola, salvato in un server di cache e quindi condiviso con altri sviluppatori in modo da risparmiare tempo, evitando a ciascuno sviluppatore di elaborare la reimportazione di nuove modifiche in locale.This process can be done once and saved in a cache server and consequently shared with other developers to save time, as opposed to every developer processing the re-import of new changes locally.

Dopo aver gestito tutte le modifiche di rilievo derivanti dal passaggio alla versione aggiornata di Unity, creare e testare le applicazioni correnti in HoloLens (prima generazione).After addressing any breaking changes from moving to the updated Unity version, build and test your current applications on HoloLens (1st gen). In questa fase è anche opportuno creare e salvare un commit per il controllo del codice sorgente.This is a good time to create and save a commit into source control.

Compilare dipendenze/plug-in per il processore ARMCompile dependencies/plugins for ARM processor

HoloLens (prima generazione) esegue le applicazioni su un processore x86, mentre HoloLens 2 si basa su un processore ARM.HoloLens (1st gen) executes applications on an x86 processor while the HoloLens 2 uses an ARM processor. Le applicazioni HoloLens esistenti devono essere convertite per supportare ARM.Existing HoloLens applications need to be ported over to support ARM. Come indicato in precedenza, Unity 2018 LST supporta la compilazione per app ARM32, mentre Unity 2019.x supporta la compilazione per app ARM32 e ARM64.As noted earlier, Unity 2018 LTS supports compiling ARM32 apps while Unity 2019.x supports compiling ARM32 and ARM64 apps. Lo sviluppo per le applicazioni ARM64 è preferibile in quanto esiste una differenza sostanziale nelle prestazioni.Developing for ARM64 applications is preferred, as there's a material difference in performance. Tuttavia, in questo modo è necessario creare tutte le dipendenze da plug-in anche per ARM64.However, this requires all plugin dependencies to also be built for ARM64.

Esamina tutte le dipendenze da DLL dell'applicazione.Review all DLL dependencies in your application. È consigliabile rimuovere le dipendenze che non sono più necessarie per il progetto.We recommend removing dependencies that are no longer needed for your project. Per i plug-in rimanenti che sono necessari, inserisci i rispettivi file binari ARM32 o ARM64 nel progetto Unity.For remaining plugins that are required, ingest the respective ARM32 or ARM64 binaries into your Unity project.

Dopo aver inserito le DLL pertinenti, creare una soluzione Visual Studio da Unity e compilare un'applicazione AppX per ARM in Visual Studio per verificare che l'applicazione possa essere creata per processori ARM.After ingesting the relevant DLLs, build a Visual Studio solution from Unity and compile an AppX for ARM in Visual Studio to test your application can be built for ARM processors. È consigliabile salvare l'applicazione come commit nella soluzione di controllo del codice sorgente.It's advised to save the application as a commit in your source control solution.

Importante

Le applicazioni che usano MRTK v1 possono essere eseguite in HoloLens 2 dopo aver impostato la destinazione di compilazione su ARM, presupponendo che tutti gli altri requisiti siano soddisfatti,Application's using MRTK v1 can be run on HoloLens 2 after changing the build target to ARM, assuming that all other requirements are met. inclusa la presenza di versioni ARM di tutti i plug-in.This includes making sure you have ARM versions of all your plugins. L'app, tuttavia, non potrà accedere alle funzioni specifiche di HoloLens 2, ad esempio il tracciamento della mano e il tracciamento oculare articolati.However, your app won't have access to HoloLens 2 specific functions like articulated hand and eye tracking. MRTK v1 e MRTK v2 hanno spazi dei nomi diversi che consentono di mantenere entrambe le versioni nello stesso progetto, meccanismo utile per la transizione da una versione all'altra.MRTK v1 and MRTK v2 have different namespaces that allow both versions to be in the same project, which is useful for transitioning from one to the other.

Eseguire l'aggiornamento a MRTK versione 2Update to MRTK version 2

MRTK versione 2 è il nuovo toolkit che controlla Unity e che supporta sia HoloLens (prima generazione) che HoloLens 2.MRTK Version 2 is the new toolkit on top of Unity that supports both HoloLens (1st gen) and HoloLens 2. In questo toolkit sono state aggiunte tutte le nuove funzionalità di HoloLens 2, ad esempio le interazioni con le mani e il tracciamento oculare.It's also where all the new HoloLens 2 capabilities have been added, such as hand interactions and eye tracking.

Per altre informazioni sull'uso di MRTK versione 2, vedere le risorse seguenti:Check out the following resources for more information on using MRTK version 2:

Prepararsi per la migrazionePrepare for the migration

Prima dell'inserimento di nuovi file *.unitypackage per MRTK v2, è consigliabile eseguire un inventario di 1) tutto il codice personalizzato che si integra con MRTK v1 e di 2) tutto il codice personalizzato per le interazioni di input o i componenti dell'esperienza utente.Before ingesting the new *.unitypackage files for MRTK v2, it's recommended to take an inventory of 1) any custom-built code that integrates with MRTK v1 and 2) any custom-built code for input interactions or UX components. L'impegno maggiore per uno sviluppatore di realtà mista che inserisce il toolkit MRTK v2 è relativo all'input e alle interazioni.The most common and prevalent conflict for a mixed reality developer ingesting MRTK v2 involves input and interactions. È consigliabile pertanto leggere e comprendere il modello di input di MRTK v2.It's advised to begin reading and understanding the MRTK v2 input model.

Infine, il nuovo toolkit MRTK v2 è passato da un modello di script e di oggetti di gestione in scena a un'architettura di provider di servizi e configurazione.Finally, the new MRTK v2 has transitioned from a model of scripts and in-scene manager objects to a configuration and services provider architecture. Ne deriva un modello di architettura e gerarchia di scene più chiaro, ma anche l'esigenza di una curva di apprendimento per comprendere i nuovi profili di configurazione.This results in a cleaner scene hierarchy and architecture model, but requires a learning curve for understanding the new configuration profiles. Leggi la Guida alla configurazione di Mixed Reality Toolkit per acquisire familiarità con le impostazioni e i profili importanti per soddisfare i requisiti dell'applicazione.Read the Mixed Reality Toolkit Configuration Guide to start becoming familiar with the important settings and profiles to adjust to the needs of your application.

Migrazione del progettoMigrating the project

Dopo l'importazione di MRTK v2, il progetto Unity conterrà probabilmente molti errori relativi al compilatore.After importing MRTK v2, your Unity project most likely has many compiler-related errors. Si tratta in genere di errori dovuti alla struttura dei nuovi spazi dei nomi e ai nomi dei nuovi componenti.These are commonly because of the new namespace structure and new component names. Per risolvere questi errori, inserire negli script i nuovi spazi dei nomi e componenti.continue to resolve these errors by modifying your scripts to the new namespaces and components.

Per informazioni sulle differenze di API specifiche tra HTK/MRTK e MRTK v2, vedi la guida di conversione nella wiki di MRTK versione 2.For information on the specific API differences between HTK/MRTK and MRTK v2, see the porting guide on the MRTK Version 2 wiki.

Procedure consigliateBest practices

  • Prediligi l'uso dello shader MRTK Standard.Prefer use of the MRTK standard shader.
  • Lavora su un tipo di modifica sostanziale per volta (ad esempio: da IFocusable a IMixedRealityFocusHandler).Work on one breaking change type at a time (ex: IFocusable to IMixedRealityFocusHandler).
  • Esegui il test dopo ogni modifica e usa il controllo del codice sorgente.Test after every change and use source control.
  • Quando possibile, usare l'esperienza utente MRTK predefinita (pulsanti, slate e così via).Use default MRTK UX (buttons, slates, and so on), when possible.
  • Evita di modificare direttamente i file MRTK e crea invece wrapper intorno ai componenti MRTK.Refrain from modifying MRTK files directly; create wrappers around MRTK components.
    • Questa azione semplifica inserimenti e aggiornamenti MRTK futuri.This action eases future MRTK ingestions and updates.
  • Esamina ed esplora le scene di esempio fornite in MRTK (soprattutto HandInteractionExamples.scene).Review and explore sample scenes provided in the MRTK, especially HandInteractionExamples.scene.
  • Ricrea l'interfaccia utente basata su aree di disegno con quadrilateri, collisori e testo TextMeshPro.Rebuild canvas-based UI with quads, colliders, and TextMeshPro text.
  • Abilita la condivisione dei buffer di intensità o imposta il punto di messa a fuoco; usa un buffer di intensità di 16 bit per prestazioni migliori.Enable Depth Buffer Sharing or set focus point; prefer to use a 16-bit depth buffer for better performance. Quando esegui il rendering del colore, assicurati di farlo anche per la profondità.Ensure when rendering color, to also render depth. Unity in genere non scrive la profondità per oggetti gioco trasparenti e di testo.Unity generally doesn't write depth for transparent and text gameobjects.
  • Imposta il percorso di rendering con istanze a singolo passaggio.Set Single Pass Instanced Rendering Path.
  • Usare il profilo di configurazione di HoloLens 2 per MRTK.Use the HoloLens 2 configuration profile for MRTK

Controllo dell'applicazioneTesting your application

In MRTK versione 2 è possibile simulare le interazioni con le mani direttamente in Unity e sviluppare con le nuove API le interazioni con le mani e il tracciamento oculare.In MRTK Version 2, you can simulate hand interactions directly in Unity and develop with the new APIs for hand interactions and eye tracking. Il dispositivo HoloLens 2 è necessario per creare un'esperienza utente soddisfacente.The HoloLens 2 device is required to create a satisfying user experience. È consigliabile iniziare a studiare la documentazione e gli strumenti per acquisire una maggiore familiarità.You're encouraged to start studying the documentation and tools for greater understanding. MRTK v2 supporta lo sviluppo in HoloLens (prima generazione) e i modelli di input tradizionali, come la selezione tramite simulazione del tocco, possono essere testati in questa generazione di dispositivi.MRTK v2 supports development on HoloLens (1st gen) and traditional input models, such as select via air-tap can be tested on HoloLens (1st gen).

Aggiornamento del modello di interazione per HoloLens 2Updating your interaction model for HoloLens 2

Attenzione

Se il progetto usa una delle API XR.WSA, tenere presente che sono in fase di eliminazione a favore delle nuove API di input XR di Unity per le versioni future di Unity.If your project is using any of the XR.WSA APIs, these are being phased out in favor of Unity's new XR input APIs in future Unity releases. Altre informazioni sulle API di input XR sono disponibili qui.You can find more information about the XR input APIs here.

Dopo aver convertito e preparato l'applicazione per HoloLens 2, puoi iniziare a prendere in considerazione l'aggiornamento del modello di interazione del posizionamento degli ologrammi.Once your application is ported and prepped for HoloLens 2, you're ready to consider updating your interaction model and hologram design placements. In HoloLens (prima generazione) è probabile che l'applicazione abbia un modello di interazione basato sullo sguardo fisso e il commit, con ologrammi relativamente lontani per rientrare nel campo di visualizzazione.In HoloLens (1st gen), your application likely has a gaze and commit interaction model with holograms relatively far away to fit into the field of view.

Passaggi per aggiornare la progettazione dell'applicazione in modo ottimale per HoloLens 2:Steps to update your application design to be best suited for HoloLens 2:

  1. Componenti MRTK: per le operazioni preliminari, se hai aggiunto MRTK v2, sono disponibili diversi componenti/script progettati e ottimizzati per HoloLens 2.MRTK components: Per the pre-work, if you added MRTK v2, there are various components/scripts to leverage that have been designed and optimized for HoloLens 2.

  2. Modello di interazione: valuta l'opportunità di aggiornare il modello di interazione.Interaction model: Consider updating your interaction model. Per la maggior parte degli scenari, è consigliabile passare da sguardo fisso e commit alle mani.For most scenarios, we recommend switching from gaze and commit to hands. Con gli ologrammi che in genere non sono raggiungibili stendendo le braccia, il passaggio all'uso delle mani consente di sfruttare raggi di puntamento e movimenti di cattura per l'interazione da lontano.With your holograms typically being out of arms-reach, switching to hands results in far interaction pointing rays and grab gestures.

  3. Posizionamento dell'ologramma: dopo il passaggio a un modello di interazione con le mani, valuta la possibilità di avvicinare alcuni ologrammi per interagire direttamente usando movimenti di cattura per l'interazione da vicino con le mani.Hologram placement: After switching to a hands interaction model, consider moving some holograms closer to directly interact with them, by using near-interaction grab gestures with your hands. I tipi di ologrammi consigliati per avvicinarsi e afferrare o interagire direttamente sono menu, controlli e pulsanti di destinazione di dimensioni ridotte e ologrammi più piccoli che rientrano nel campo visivo di HoloLens 2 quando si afferra e si esamina l'ologramma.The types of holograms recommended to move closer to directly grab or interact are small target menus, controls, buttons, and smaller holograms that fit within the HoloLens 2 field of view when grabbing and inspecting the hologram.
    Ogni applicazione e ogni scenario hanno caratteristiche diverse e si proseguirà con il perfezionamento e la pubblicazione di indicazioni di progettazione in base al feedback e alle nuove informazioni.Every application and scenario are different, and we’ll continue to refine and post design guidance based on feedback and continued learnings.

Avvertenze e informazioni aggiuntive sullo spostamento di applicazioni da x86 ad ARMAdditional caveats and learnings about moving applications from x86 to ARM

  • Le applicazioni Unity lineari sono semplici perché è possibile creare un bundle di applicazioni ARM o distribuirle direttamente nel dispositivo per l'esecuzione del bundle.Straight-forward Unity applications are simple because you can build an ARM application bundle or deploy directly to the device for the bundle to run. Alcuni plug-in nativi di Unity possono presentare specifici problemi di sviluppo.Some Unity native plugins can present certain development challenges. Per questo motivo, è necessario aggiornare tutti i plug-in nativi di Unity a Visual Studio 2019 e quindi rieseguire la compilazione per ARM.Because of this, you must upgrade all Unity native plugins to Visual Studio 2019 and then rebuild for ARM.

  • Per un'applicazione è stato usato il plug-in AudioKinetic Wwise di Unity e tale versione di Unity non include un plug-in ARM UWP, quindi è stato necessario un notevole sforzo per rielaborare le funzionalità audio nell'applicazione in questione per l'esecuzione in ARM.One application used the Unity AudioKinetic Wwise plugin and that version of Unity didn't have a UWP ARM plugin, which caused a considerable effort to rework sound capabilities into the application in question to run on ARM. Assicurati che tutti i plug-in necessari per i tuoi piani di sviluppo siano installati e disponibili in Unity.Ensure that all required plugins for your development plans are installed and available in Unity.

  • In alcuni casi, tra i plug-in richiesti dall'applicazione potrebbe non esistere un plug-in ARM/UWP, il che impedisce la possibilità di convertirla ed eseguirla in HoloLens 2.In some cases, a UWP/ARM plugin might not exist for application-required plugins, which blocks the ability to port the application and run it on HoloLens 2. Contatta il provider di plug-in per risolvere il problema e fornire il supporto per ARM.Contact your plugin provider to resolve the issue and provide support for ARM.

  • I valori minfloat (e varianti come min16float, minint e così via) negli shader possono avere un comportamento diverso in HoloLens 2 rispetto a HoloLens (prima generazione).The minfloat (and variants such as min16float, minint, and so on) in shaders might behave differently on HoloLens 2 than on HoloLens (1st gen). In particolare, garantiscono che venga usato almeno il numero specificato di bit.Specifically, these guarantee that at least the specified number of bits will be used. Nelle GPU Intel/Nvidia i valori minfloat vengono considerati per lo più come 32 bit.On Intel/Nvidia GPUs, minfloats are largely treated as 32 bits. In ARM il numero di bit specificato viene effettivamente rispettato.On ARM, the number of bits specified is actually adhered to. Ciò significa che in pratica questi numeri possono avere una portata o una precisione minore in HoloLens 2 rispetto a quanto accade in HoloLens (prima generazione).That means in practice, these numbers might have less precision or range on HoloLens 2 than they did on HoloLens (1st gen).

  • Le istruzioni _asm non sembrano funzionare in ARM, pertanto il codice con istruzioni _asm deve essere riscritto.The _asm instructions don’t appear to work on ARM, meaning any code using _asm instructions must be rewritten.

  • ARM non supporta il set di istruzioni SIMD perché varie intestazioni, ad esempio xmmintrin.h, emmintrin.h, tmmintrin.h e immintrin.h, non sono disponibili in ARM.ARM doesn't support the SIMD instruction set because various headers, such as xmmintrin.h, emmintrin.h, tmmintrin.h, and immintrin.h, aren't available on ARM.

  • Il compilatore dello shader in ARM viene eseguito durante la prima chiamata di disegno dopo il caricamento dello shader o dopo che è cambiato qualcosa su cui si basa lo shader, non in fase di caricamento dello shader.The shader compiler on ARM runs during the first draw call after the shader has been loaded or something the shader relies on has changed, not at shader load time. L'impatto sulla frequenza dei fotogrammi può essere più o meno evidente, a seconda del numero di shader che devono essere compilati, con implicazioni sulle diverse modalità di gestione degli shader, creazione dei pacchetti e aggiornamento in HoloLens 2 rispetto a HoloLens (prima generazione).The impact on framerate can be noticeable, depending on how many shaders need to be compiled, with implications for how shaders should be handled, packaged, updated differently on HoloLens 2 vs HoloLens (1st gen).

Vedere ancheSee also