Portabilidad de aplicaciones de HoloLens (1.ª generación) a HoloLens 2Porting HoloLens (1st Gen) apps to HoloLens 2

Esta guía está diseñada específicamente para ayudar a los desarrolladores que tienen una aplicación existente de Unity para HoloLens (1.ª generación) para realizar la portabilidad de su aplicación al 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. Hay cuatro pasos clave para portar una aplicación de Unity de HoloLens (1.ª generación) a HoloLens 2.There are four key steps to porting a HoloLens (1st gen) Unity application to HoloLens 2.

En las secciones siguientes se detalla la información de cada fase:The sections below detail information for each stage:

Paso 1Step 1 Paso 2Step 2 Paso 3Step 3 Paso 4Step 4
Logotipo de Visual Studio Logotipo de Unity Icono de Unity Logotipo de MRTK
Descarga de las herramientas más recientesDownload latest tools Actualización del proyecto de UnityUpdate Unity Project Compilación para ARMCompile for ARM Migración a versión 2 de MRTKMigrate to MRTK v2

Requisitos previosPrerequisites

Se recomienda encarecidamente usar el control de código fuente para guardar una instantánea del estado original de la aplicación antes de iniciar el proceso de portabilidad.We highly recommended using source control to save a snapshot your applications original state before starting the porting process. Además, se recomienda guardar estados de punto de control en varios momentos durante el proceso.Additionally, we recommend saving checkpoint states at various times during the process. También puede ser útil tener otra instancia de Unity de la aplicación original para compararlas en paralelo durante el proceso de portabilidad.It can also be helpful to have another Unity instance of the original application to compare side by side during the porting process.

Nota

Antes de realizar la portabilidad, asegúrate de que tienes instaladas las herramientas más recientes para el desarrollo de Windows Mixed Reality.Before porting, ensure you have the latest tools installed for Windows Mixed Reality development. Para la mayoría de los desarrolladores de HoloLens existentes, esto implica actualizar a la versión más reciente de Visual Studio 2019 e instalar el Windows SDK adecuado.For most existing HoloLens developers, this involves updating to the latest version of Visual Studio 2019 and installing the appropriate Windows SDK. El contenido siguiente profundiza más en las diferentes versiones de Unity y la versión 2 de Mixed Reality Toolkit (MRTK).The content that follows dives further into different Unity versions and the Mixed Reality Toolkit (MRTK) Version 2.

Para más información, consulta Instalar las herramientas.For more information, please see Install the tools.

Migración del proyecto a la última versión de UnityMigrate project to the latest version of Unity

Si usa MRTK v2, Unity 2019 LTS será la mejor vía de compatibilidad a largo plazo sin cambios importantes en Unity ni en 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. Debe evaluar cualquier dependencia de complemento que exista actualmente en el proyecto, y determinar si estos archivos DLL pueden compilarse para ARM64.Assess any plugin dependencies that currently exist in your project, and determine whether these DLLs can be built for ARM64. En el caso de los proyectos con un complemento dependiente de ARM64, es posible que deba seguir compilando la aplicación para ARM.For projects with a hard ARM64 dependent plugin, you may need to continue building your app for ARM.

Actualización de la configuración de la escena o proyecto en UnityUpdate scene/project settings in Unity

Después de actualizar a Unity 2019 LTS, se recomienda actualizar valores concretos en Unity para obtener los mejores resultados en el dispositivo.After updating to Unity 2019 LTS, it's recommended that you update particular settings in Unity for optimal results on the device. Estos valores se describen en detalle en Configuración recomendada para Unity.These settings are outlined in detail under recommended settings for Unity.

Recuerde que el back-end de scripting de .NET estará en desuso en Unity 2018 y se habrá eliminado de Unity 2019.To reiterate, the .NET scripting back-end is being deprecated in Unity 2018 and removed in Unity 2019. Es muy recomendable que los desarrolladores consideren la posibilidad de cambiar su proyecto a IL2CPP.Developers should strongly consider switching their project to IL2CPP.

Nota

El back-end del scripting de IL2CPP puede aumentar los tiempos de compilación de Unity a Visual Studio, y los desarrolladores deben configurar la máquina de desarrollo para optimizar los tiempos de compilación de 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. También puede resultar útil configurar un servidor de caché, especialmente para los proyectos de Unity con una gran cantidad de activos (sin contar con los archivos de script), o que cambien constantemente de escenas y activos.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. Al abrir un proyecto, Unity almacena los activos aplicables en un formato de la memoria caché interna en la máquina del desarrollador.When opening a project, Unity stores qualifying assets into an internal cache format on the developer machine. Los elementos se tienen que volver a importar y a procesar cuando se modifican.Items must be re-imported and re-processed when modified. Este proceso se puede realizar una vez y guardar en un servidor de caché, de esta forma se comparte con otros desarrolladores, lo que ahorra tiempo, en lugar de que cada desarrollador tenga que procesar localmente la reimportación de los nuevos cambios.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.

Después de solucionar los cambios importantes tras el cambio a la versión actualizada de Unity, debe compilar y probar sus aplicaciones actuales en HoloLens (1.ª generación).After addressing any breaking changes from moving to the updated Unity version, build and test your current applications on HoloLens (1st gen). Este es un buen momento para crear y guardar una confirmación en el control de código fuente.This is a good time to create and save a commit into source control.

Compilación de dependencias/complementos para procesadores ARMCompile dependencies/plugins for ARM processor

HoloLens (1.ª generación) ejecuta las aplicaciones en un procesador x86, mientras que el dispositivo HoloLens 2 usa un procesador ARM.HoloLens (1st gen) executes applications on an x86 processor while the HoloLens 2 uses an ARM processor. Por lo tanto, las aplicaciones de HoloLens existentes se tienen que portar para admitir ARM.Existing HoloLens applications need to be ported over to support ARM. Como se indicó anteriormente, Unity 2018 LTS admite la compilación para las aplicaciones de ARM32, mientras que Unity 2019.x admite la compilación para las aplicaciones de ARM32 y ARM64.As noted earlier, Unity 2018 LTS supports compiling ARM32 apps while Unity 2019.x supports compiling ARM32 and ARM64 apps. Es preferible desarrollar para aplicaciones de ARM64, ya que existe una diferencia sustancial en el rendimiento.Developing for ARM64 applications is preferred, as there's a material difference in performance. Sin embargo, esto requiere que todas las dependencias de complemento se compilen también para ARM64.However, this requires all plugin dependencies to also be built for ARM64.

Revisa todas las dependencias DLL en la aplicación.Review all DLL dependencies in your application. Se recomienda quitar las dependencias que ya no sean necesarias para el proyecto.We recommend removing dependencies that are no longer needed for your project. Para el resto de complementos que son necesarios, se deben ingerir los respectivos archivos binarios de ARM32 o ARM64 en el proyecto de Unity.For remaining plugins that are required, ingest the respective ARM32 or ARM64 binaries into your Unity project.

Después de la ingesta de las DLL pertinentes, compile una solución de Visual Studio desde Unity y, a continuación, compile un paquete AppX para ARM en Visual Studio para probar que la aplicación se pueda compilar para procesadores 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. Se recomienda guardar la aplicación como una confirmación en la solución de control de código fuente.It's advised to save the application as a commit in your source control solution.

Importante

La aplicación que usa MRTK v1 puede ejecutarse en HoloLens 2 después de cambiar el destino de compilación a ARM, suponiendo que se cumplen todos los demás requisitos.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. Esto incluye asegurarse de que tiene versiones ARM de todos los complementos.This includes making sure you have ARM versions of all your plugins. Sin embargo, la aplicación no tendrá acceso a funciones específicas de HoloLens 2, como el seguimiento de la mano articulada y el ojo.However, your app won't have access to HoloLens 2 specific functions like articulated hand and eye tracking. MRTK v1 y MRTK v2 tienen distintos espacios de nombres que permiten que ambas versiones estén en el mismo proyecto, lo que resulta útil para realizar la transición de una a otra.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.

Actualización a la versión 2 de MRTKUpdate to MRTK version 2

MRTK versión 2 es el nuevo kit de herramientas además de Unity que admite tanto HoloLens (1.ª generación) como HoloLens 2.MRTK Version 2 is the new toolkit on top of Unity that supports both HoloLens (1st gen) and HoloLens 2. También es donde se agregan todas las nuevas funcionalidades de HoloLens 2, como las interacciones con la mano y el seguimiento de los ojos.It's also where all the new HoloLens 2 capabilities have been added, such as hand interactions and eye tracking.

Consulte los recursos siguientes para obtener más información sobre el uso de la versión 2 de MRTK:Check out the following resources for more information on using MRTK version 2:

Preparación para la migraciónPrepare for the migration

Antes de realizar la ingesta de los nuevos archivos *.unitypackage para la versión 2 de MRTK, se recomienda realizar un inventario de 1) cualquier código personalizado que se integre con la versión 1 de MRTK y 2) cualquier código personalizado para las interacciones de entrada o los componentes de la experiencia de usuario.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. El conflicto más común y que se da con más frecuencia para un desarrollador de realidad mixta en relación con la ingesta de la versión 2 de MRTK tiene que ver con las entradas y las interacciones.The most common and prevalent conflict for a mixed reality developer ingesting MRTK v2 involves input and interactions. Se recomienda comenzar a leer el modelo de entrada de la versión 2 de MRTK para obtener una mejor comprensión del mismo.It's advised to begin reading and understanding the MRTK v2 input model.

Por último, la nueva versión 2 de MRTK ha pasado de un modelo de scripts y objetos de administrador en la escena a una arquitectura de configuración y proveedor de servicios.Finally, the new MRTK v2 has transitioned from a model of scripts and in-scene manager objects to a configuration and services provider architecture. Esto da como resultado un modelo de arquitectura y jerarquía de escena más limpio, pero requiere una curva de aprendizaje para comprender los nuevos perfiles de configuración.This results in a cleaner scene hierarchy and architecture model, but requires a learning curve for understanding the new configuration profiles. Por ello, le recomendamos que lea Guía de configuración del kit de herramientas de Mixed Reality para familiarizarse con los perfiles y opciones más importantes con los que podrá ajustarse a las necesidades de la aplicación.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.

Migración del proyectoMigrating the project

Después de importar MRTK v2, el proyecto de Unity probablemente tenga muchos errores relacionados con el compilador.After importing MRTK v2, your Unity project most likely has many compiler-related errors. Generalmente, estos errores se deben a la nueva estructura del espacio de nombres y de los nuevos nombres de componente.These are commonly because of the new namespace structure and new component names. Puede resolver estos errores mediante la modificación de los scripts con los espacios de nombres y componentes nuevos.continue to resolve these errors by modifying your scripts to the new namespaces and components.

Para más información sobre las diferencias de API específicas entre HTK/MRTK y MRTK v2, consulta la guía de migración en la wiki de la versión 2 de MRTK.For information on the specific API differences between HTK/MRTK and MRTK v2, see the porting guide on the MRTK Version 2 wiki.

Procedimientos recomendadosBest practices

  • Da preferencia al uso del sombreador MRTK Standard.Prefer use of the MRTK standard shader.
  • Trabaja en un solo tipo de cambio importante a la vez (por ejemplo: IFocusable a IMixedRealityFocusHandler).Work on one breaking change type at a time (ex: IFocusable to IMixedRealityFocusHandler).
  • Haz una prueba después de cada cambio y usa el control de código fuente.Test after every change and use source control.
  • Use experiencias de usuario de MRTK predeterminadas (botones, tabletas táctiles, etc.) cuando sea posible.Use default MRTK UX (buttons, slates, and so on), when possible.
  • Intenta evitar la modificación de los archivos de MRTK directamente; en su lugar, crea contenedores en torno a los componentes de MRTK.Refrain from modifying MRTK files directly; create wrappers around MRTK components.
    • Esta acción facilita las futuras ingestas y actualizaciones de MRTK.This action eases future MRTK ingestions and updates.
  • Revisa y explora escenas de ejemplo proporcionadas en MRTK (especialmente HandInteractionExamples.scene).Review and explore sample scenes provided in the MRTK, especially HandInteractionExamples.scene.
  • Vuelve a generar la interfaz de usuario basada en lienzo con cuadrángulos, colisionadores y texto TextMeshPro.Rebuild canvas-based UI with quads, colliders, and TextMeshPro text.
  • Habilita el uso compartido del búfer de profundidad o establece el punto de enfoque; es preferible usar un búfer de profundidad de 16 bits para mejorar el rendimiento.Enable Depth Buffer Sharing or set focus point; prefer to use a 16-bit depth buffer for better performance. Al representar el color, asegúrate de representar también la profundidad.Ensure when rendering color, to also render depth. Por lo general, Unity no escribe la profundidad de objetos GameObject de texto y transparentes.Unity generally doesn't write depth for transparent and text gameobjects.
  • Establece la ruta de representación de instancia de paso único.Set Single Pass Instanced Rendering Path.
  • Use el perfil de configuración de HoloLens 2 para MRTK.Use the HoloLens 2 configuration profile for MRTK

Prueba de la aplicaciónTesting your application

En la versión 2 de MRTK, puede simular las interacciones con las manos directamente en Unity, así como desarrollar elementos con las nuevas API para las interacciones con las manos y el seguimiento de los ojos.In MRTK Version 2, you can simulate hand interactions directly in Unity and develop with the new APIs for hand interactions and eye tracking. El dispositivo HoloLens 2 es necesario para crear una experiencia de usuario satisfactoria.The HoloLens 2 device is required to create a satisfying user experience. Es recomendable que comience examinando la documentación y las herramientas para comprender mejor este tema.You're encouraged to start studying the documentation and tools for greater understanding. La versión 2 de MRTK admite el desarrollo en HoloLens (1.ª generación) y los modelos de entrada tradicionales, como la selección mediante pulsación en el aire, se pueden probar en los dispositivos HoloLens (1.ª generación).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).

Actualización del modelo de interacción para HoloLens 2Updating your interaction model for HoloLens 2

Precaución

Si el proyecto usa cualquiera de las API XR.WSA, tenga en cuenta que se van a retirar gradualmente en favor de las nuevas API de entrada de XR de Unity en futuras versiones de 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. Puede encontrar más información sobre estas las API de entrada de XR aquí.You can find more information about the XR input APIs here.

Una vez que la aplicación está portada y preparada para HoloLens 2, ya estás listo para considerar la actualización de las ubicaciones del diseño del holograma y del modelo.Once your application is ported and prepped for HoloLens 2, you're ready to consider updating your interaction model and hologram design placements. En HoloLens (1ª generación), es muy posible que tu aplicación tenga un modelo de interacción de mirada y confirmación con hologramas relativamente lejanos para encajar en el campo de visión.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.

Pasos para actualizar el diseño de la aplicación al diseño más adecuado para HoloLens 2:Steps to update your application design to be best suited for HoloLens 2:

  1. Componentes de MRTK: por el trabajo previo, si agregas la versión 2 de MRTK, hay varios componentes o scripts para aprovechar que se han diseñado y optimizado para 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. Modelo de interacción: Plantéate la posibilidad de actualizar el modelo de interacción.Interaction model: Consider updating your interaction model. Para la mayoría de los escenarios, se recomienda cambiar de mirada y confirmación a interacciones con las manos.For most scenarios, we recommend switching from gaze and commit to hands. Con tus hologramas normalmente fuera del alcance de la mano, el cambio a las entradas de interacción con las manos produce gestos de agarre y haces apuntadores de interacción lejana.With your holograms typically being out of arms-reach, switching to hands results in far interaction pointing rays and grab gestures.

  3. Ubicación de hologramas: después de cambiar a un modelo de interacción con las manos, considera la posibilidad de acercar algunos hologramas para interactuar directamente con ellos, utilizando gestos de agarre de interacción cercana con las manos.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. Los tipos de hologramas recomendados para el acercamiento que te permita agarrar o interactuar directamente, son los menús de destino pequeños, controles, botones y los hologramas más pequeños que caben dentro del campo de visión de HoloLens 2 al agarrar e inspeccionar el holograma.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.
    Cada aplicación y escenario son diferentes, y vamos a seguir mejorando y publicando instrucciones para el diseño basadas en comentarios y en lo que vamos aprendiendo cada día.Every application and scenario are different, and we’ll continue to refine and post design guidance based on feedback and continued learnings.

Advertencias y aprendizajes adicionales sobre cómo mover aplicaciones de x86 a ARMAdditional caveats and learnings about moving applications from x86 to ARM

  • Las aplicaciones directas de Unity son sencillas porque puedes compilar un paquete de aplicaciones de ARM o realizar la implementación directamente en el dispositivo para que se ejecute la agrupación.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. Algunos complementos nativos de Unity pueden presentar ciertos desafíos de desarrollo.Some Unity native plugins can present certain development challenges. Por este motivo, debes actualizar todos los complementos nativos de Unity a Visual Studio 2019 y, a continuación, volver a generarlos para ARM.Because of this, you must upgrade all Unity native plugins to Visual Studio 2019 and then rebuild for ARM.

  • Una aplicación usó el complemento AudioKinetic Wwise de Unity y esa versión de Unity no tenía ningún complemento de ARM para UWP, lo que exigió un esfuerzo considerable para volver a crear las funcionalidades de sonido en la aplicación en cuestión para su ejecución en 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. Asegúrate de que todos los complementos necesarios para tus planes de desarrollo están instalados y disponibles en Unity.Ensure that all required plugins for your development plans are installed and available in Unity.

  • En algunos casos, puede que no exista un complemento de UWP/ARM para los complementos necesarios para la aplicación, lo que bloquea la capacidad de portar la aplicación y ejecutarla en 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. Ponte en contacto con tu proveedor de complementos para resolver el problema y obtener compatibilidad con ARM.Contact your plugin provider to resolve the issue and provide support for ARM.

  • El comando minfloat (y sus variantes, como min16float, minint, etc.) puede comportarse en los sombreadores de manera diferente en HoloLens 2 a como lo hacía en HoloLens (1.ª generación).The minfloat (and variants such as min16float, minint, and so on) in shaders might behave differently on HoloLens 2 than on HoloLens (1st gen). En concreto, estos garantizan que se utilizará al menos el número especificado de bits.Specifically, these guarantee that at least the specified number of bits will be used. En las GPU de Nvidia o Intel, estos comandos minfloat se tratan generalmente como de 32 bits.On Intel/Nvidia GPUs, minfloats are largely treated as 32 bits. En ARM, el número de bits especificado se respeta.On ARM, the number of bits specified is actually adhered to. En la práctica, esto significa que estos números pueden tener menos precisión o rango en HoloLens 2 del que tenían en HoloLens (1.ª generación).That means in practice, these numbers might have less precision or range on HoloLens 2 than they did on HoloLens (1st gen).

  • Las instrucciones _asm no parecen funcionar en ARM, lo que significa que cualquier código con instrucciones _asm tiene que volverse a escribir.The _asm instructions don’t appear to work on ARM, meaning any code using _asm instructions must be rewritten.

  • ARM no admite el conjunto de instrucciones SIMD, ya que varios encabezados, como xmmintrin.h, emmintrin.h, tmmintrin.h e immintrin.h, no están disponibles en 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.

  • El compilador del sombreador en ARM se ejecuta durante la primera llamada draw, después de que el sombreador se haya cargado, o algo en lo que se basa sombreador haya cambiado, no en el tiempo de carga de sombreador.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. El impacto en la velocidad de fotogramas puede ser apreciable, en función de cuántos sombreadores deban compilarse; asimismo, hay que tener en cuenta que los sombreadores se deben controlar, empaquetar y actualizar de forma diferente en HoloLens 2, en comparación con HoloLens (1.ª generación).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).

Consulta tambiénSee also