Portabilidade dos aplicativos HoloLens (1ª geração) para o HoloLens 2Porting HoloLens (1st Gen) apps to HoloLens 2

Este guia foi projetado para ajudar os desenvolvedores com um aplicativo do Unity para HoloLens (1ª geração) a portá-lo para o 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. Há quatro etapas principais para portar um aplicativo do Unity do HoloLens (1ª geração) para o HoloLens 2.There are four key steps to porting a HoloLens (1st gen) Unity application to HoloLens 2.

As seções abaixo fornecem informações detalhadas para cada estágio:The sections below detail information for each stage:

Etapa 1Step 1 Etapa 2Step 2 Etapa 3Step 3 Etapa 4Step 4
Logotipo do Visual Studio Logotipo do Unity Ícone do Unity Logotipo do MRTK
Baixar as ferramentas mais recentesDownload latest tools Atualizar o projeto do UnityUpdate Unity Project Compilar para o ARMCompile for ARM Migrar para o MRTK v2Migrate to MRTK v2

Pré-requisitosPrerequisites

Recomendamos expressamente que você use o controle do código-fonte para salvar um instantâneo do estado original dos seus aplicativos antes de iniciar o processo de portabilidade.We highly recommended using source control to save a snapshot your applications original state before starting the porting process. Além disso, recomendamos salvar os estados de ponto de verificação em vários momentos durante o processo.Additionally, we recommend saving checkpoint states at various times during the process. Também pode ser útil ter outra instância no Unity do aplicativo original para comparação lado a lado durante o processo de portabilidade.It can also be helpful to have another Unity instance of the original application to compare side by side during the porting process.

Observação

Antes da portabilidade, verifique se você tem as ferramentas mais recentes instaladas para o desenvolvimento do Windows Mixed Reality.Before porting, ensure you have the latest tools installed for Windows Mixed Reality development. Para a maioria dos desenvolvedores existentes do HoloLens, isso envolve a atualização para a última versão do Visual Studio 2019 e a instalação do SDK apropriado do Windows.For most existing HoloLens developers, this involves updating to the latest version of Visual Studio 2019 and installing the appropriate Windows SDK. O conteúdo abaixo se aprofunda ainda mais em diferentes versões do Unity e no MRTK (Kit de ferramentas de realidade misturada) versão 2.The content that follows dives further into different Unity versions and the Mixed Reality Toolkit (MRTK) Version 2.

Para obter mais informações, confira Instalar as ferramentas.For more information, please see Install the tools.

Migrar o projeto para a última versão do UnityMigrate project to the latest version of Unity

Se você estiver usando o MRTK v2, o Unity 2019 LTS será o melhor caminho de suporte de longo prazo sem alterações da falha no Unity ou no 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. Avalie as dependências de plug-in atualmente existentes no projeto e determine se essas DLLs podem ser criadas para o ARM64.Assess any plugin dependencies that currently exist in your project, and determine whether these DLLs can be built for ARM64. Para projetos com um plug-in dependente do ARM64, talvez seja necessário continuar criando seu aplicativo para o ARM.For projects with a hard ARM64 dependent plugin, you may need to continue building your app for ARM.

Atualizar as configurações de cena/projeto no UnityUpdate scene/project settings in Unity

Após a atualização para o Unity 2019 LTS, recomendamos atualizar configurações específicas no Unity para obter melhores resultados no dispositivo.After updating to Unity 2019 LTS, it's recommended that you update particular settings in Unity for optimal results on the device. Essas configurações são descritas detalhadamente em Configurações recomendadas para o Unity.These settings are outlined in detail under recommended settings for Unity.

Reiteramos que o back-end de script do .NET está sendo preterido no Unity 2018 e removido no Unity 2019.To reiterate, the .NET scripting back-end is being deprecated in Unity 2018 and removed in Unity 2019. É altamente recomendável que os desenvolvedores mudem seu projeto para IL2CPP.Developers should strongly consider switching their project to IL2CPP.

Observação

O back-end de script do IL2CPP pode causar tempos de build mais longos do Unity para o Visual Studio e, portanto, os desenvolvedores devem configurar seus computadores de desenvolvedor para otimização dos tempos de build do 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. Além disso, também pode ser benéfico configurar um Servidor de Cache, especialmente para projetos do Unity com uma grande quantidade de ativos (excluindo arquivos de script) ou que estejam constantemente alterando cenas e ativos.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. Ao abrir um projeto, o Unity armazena os ativos qualificados em um formato de cache interno no computador do desenvolvedor.When opening a project, Unity stores qualifying assets into an internal cache format on the developer machine. Os itens precisam ser importados novamente e processados novamente quando modificados.Items must be re-imported and re-processed when modified. Esse processo pode ser feito uma vez e salvo em um servidor de cache e, consequentemente, compartilhado com outros desenvolvedores para economizar tempo, em vez de todos os desenvolvedores processarem a nova importação de novas alterações localmente.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.

Depois de resolver as alterações da falha devido à migração para a versão atualizada do Unity, compile e teste seus aplicativos atuais no HoloLens (1ª geração).After addressing any breaking changes from moving to the updated Unity version, build and test your current applications on HoloLens (1st gen). Esse é um bom momento para criar e salvar uma confirmação no controle do código-fonte.This is a good time to create and save a commit into source control.

Compilar dependências/plug-ins para o processador ARMCompile dependencies/plugins for ARM processor

O HoloLens (1ª geração) executa aplicativos em um processador x86, enquanto o HoloLens 2 usa um processador ARM.HoloLens (1st gen) executes applications on an x86 processor while the HoloLens 2 uses an ARM processor. Portanto, é necessário portar os aplicativos HoloLens existentes para que eles deem suporte ao ARM.Existing HoloLens applications need to be ported over to support ARM. Conforme indicado anteriormente, o Unity 2018 LTS é compatível com a compilação de aplicativos ARM32, enquanto o Unity 2019.x é compatível com a compilação de aplicativos ARM32 e ARM64.As noted earlier, Unity 2018 LTS supports compiling ARM32 apps while Unity 2019.x supports compiling ARM32 and ARM64 apps. O desenvolvimento para aplicativos ARM64 é preferível, pois há uma diferença substancial de desempenho.Developing for ARM64 applications is preferred, as there's a material difference in performance. No entanto, isso exige que todas as dependências de plug-in também sejam compiladas para o ARM64.However, this requires all plugin dependencies to also be built for ARM64.

Examine todas as dependências de DLL em seu aplicativo.Review all DLL dependencies in your application. Recomendamos a remoção de dependências que não são mais necessárias para seu projeto.We recommend removing dependencies that are no longer needed for your project. Para os plug-ins restantes que são necessários, ingira os respectivos binários do ARM32 ou do ARM64 no projeto do Unity.For remaining plugins that are required, ingest the respective ARM32 or ARM64 binaries into your Unity project.

Após a ingestão das DLLs relevantes, compile uma solução do Visual Studio por meio do Unity e, em seguida, compile um AppX para ARM no Visual Studio para testar se o aplicativo pode ser compilado para processadores 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. É recomendável salvar o aplicativo como uma confirmação na solução de controle do código-fonte.It's advised to save the application as a commit in your source control solution.

Importante

O uso do MRTK v1 do aplicativo pode ser executado no HoloLens 2 após a alteração do destino de build para o ARM, supondo que todos os outros requisitos sejam atendidos.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. Isso inclui verificar se todos os plug-ins têm versões do ARM.This includes making sure you have ARM versions of all your plugins. No entanto, seu aplicativo não terá acesso a funções específicas do HoloLens 2, como acompanhamento ocular e mão articulada.However, your app won't have access to HoloLens 2 specific functions like articulated hand and eye tracking. O MRTK v1 e o MRTK v2 têm namespaces diferentes que permitem que ambas as versões estejam no mesmo projeto, o que é útil para fazer a transição de uma para a outra.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.

Atualizar para o MRTK versão 2Update to MRTK version 2

A versão 2 do MRTK é o novo kit de ferramentas baseado no Unity que dá suporte ao HoloLens (1ª geração) e ao HoloLens 2.MRTK Version 2 is the new toolkit on top of Unity that supports both HoloLens (1st gen) and HoloLens 2. É nela também em que todas as funcionalidades do HoloLens 2 foram adicionadas, como interações com as mãos e acompanhamento ocular.It's also where all the new HoloLens 2 capabilities have been added, such as hand interactions and eye tracking.

Confira os seguintes recursos para obter mais informações sobre como usar o MRTK versão 2:Check out the following resources for more information on using MRTK version 2:

Preparar a migraçãoPrepare for the migration

Antes da ingestão dos novos arquivos *.unitypackage para o MRTK v2, é recomendável fazer um inventário de 1) qualquer código personalizado integrado ao MRTK v1 e 2) qualquer código personalizado para interações de entrada ou componentes de experiência do usuário.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. O conflito mais comum e predominante para um desenvolvedor de realidade misturada que ingere o MRTK v2 envolve a entrada e as interações.The most common and prevalent conflict for a mixed reality developer ingesting MRTK v2 involves input and interactions. É recomendável começar a ler e entender o modelo de entrada do MRTK v2.It's advised to begin reading and understanding the MRTK v2 input model.

Por fim, o novo MRTK v2 fez a transição de um modelo de scripts e objetos de gerenciador na cena para uma configuração e uma arquitetura de provedor de serviços.Finally, the new MRTK v2 has transitioned from a model of scripts and in-scene manager objects to a configuration and services provider architecture. Isso resulta em um modelo de arquitetura e hierarquia de cena mais limpo, mas exige uma curva de aprendizado para entender os novos perfis de configuração.This results in a cleaner scene hierarchy and architecture model, but requires a learning curve for understanding the new configuration profiles. Leia o Guia de Configuração do Kit de Ferramentas de Realidade Misturada para começar a se familiarizar com os perfis e as configurações importantes para se ajustar às necessidades de seu aplicativo.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.

Migrar o projetoMigrating the project

Após a importação do MRTK v2, provavelmente, seu projeto do Unity terá muitos erros relacionados ao compilador.After importing MRTK v2, your Unity project most likely has many compiler-related errors. Esses se devem comumente à nova estrutura de namespace e aos novos nomes de componentes.These are commonly because of the new namespace structure and new component names. Continue resolvendo esses erros por meio da modificação dos scripts para os novos namespaces e componentes.continue to resolve these errors by modifying your scripts to the new namespaces and components.

Para obter informações sobre as diferenças de API específicas entre o HTK/MRTK e o MRTK v2, confira o guia de portabilidade no wiki do MRTK versão 2.For information on the specific API differences between HTK/MRTK and MRTK v2, see the porting guide on the MRTK Version 2 wiki.

Práticas recomendadasBest practices

  • Prefira o uso do sombreador padrão do MRTK.Prefer use of the MRTK standard shader.
  • Trabalhe em um tipo de alteração da falha por vez (por exemplo: IFocusable para IMixedRealityFocusHandler).Work on one breaking change type at a time (ex: IFocusable to IMixedRealityFocusHandler).
  • Faça um teste após cada alteração e use o controle do código-fonte.Test after every change and use source control.
  • Use a experiência do usuário padrão do MRTK (botões, imagens fixas e assim por diante), quando possível.Use default MRTK UX (buttons, slates, and so on), when possible.
  • Evite modificar os arquivos do MRTK diretamente; em vez disso, crie wrappers em torno de componentes do MRTK.Refrain from modifying MRTK files directly; create wrappers around MRTK components.
    • Essa ação facilita futuras ingestões e atualizações do MRTK.This action eases future MRTK ingestions and updates.
  • Examine e explore cenas de exemplo fornecidas no MRTK, especialmente HandInteractionExamples.scene.Review and explore sample scenes provided in the MRTK, especially HandInteractionExamples.scene.
  • Recompile a interface do usuário baseada em tela com quadrantes, colisores e texto do TextMeshPro.Rebuild canvas-based UI with quads, colliders, and TextMeshPro text.
  • Habilite o Compartilhamento de buffer de profundidade ou defina o ponto de foco; prefira usar um buffer de profundidade de 16 bits para ter melhor desempenho.Enable Depth Buffer Sharing or set focus point; prefer to use a 16-bit depth buffer for better performance. Verifique se, ao renderizar a cor, você também renderiza a profundidade.Ensure when rendering color, to also render depth. O Unity geralmente não grava profundidade para gameobjects de texto e transparentes.Unity generally doesn't write depth for transparent and text gameobjects.
  • Defina o caminho de renderização instanciado de passagem única.Set Single Pass Instanced Rendering Path.
  • Usar o perfil de configuração do HoloLens 2 para MRTKUse the HoloLens 2 configuration profile for MRTK

Testando seu aplicativoTesting your application

No MRTK Versão 2, você pode simular as interações com as mãos diretamente no Unity e desenvolver novas APIs para interações com as mãos e acompanhamento ocular.In MRTK Version 2, you can simulate hand interactions directly in Unity and develop with the new APIs for hand interactions and eye tracking. O dispositivo HoloLens 2 é necessário para criar uma experiência de usuário satisfatória.The HoloLens 2 device is required to create a satisfying user experience. Para adquirir uma melhor compreensão, é recomendável que você comece a estudar a documentação e as ferramentas.You're encouraged to start studying the documentation and tools for greater understanding. O MRTK v2 é compatível com o desenvolvimento no HoloLens (1ª geração) e, assim, os modelos de entrada tradicionais (tais como selecionar por meio do gesto de fechar e abrir dedos indicador e polegar) podem ser testados no HoloLens (1ª geração).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).

Como atualizar o modelo de interação para o HoloLens 2Updating your interaction model for HoloLens 2

Cuidado

Se o seu projeto está usando uma das APIs do XR.WSA, elas estão sendo desativadas em favor das novas APIs de entrada de XR do Unity nas versões futuras do 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. Encontre mais informações sobre as APIs de entrada de XR aqui.You can find more information about the XR input APIs here.

Depois que o aplicativo for portado e preparado para o HoloLens 2, você estará pronto para considerar a atualização do modelo de interação e dos posicionamentos de design dos hologramas.Once your application is ported and prepped for HoloLens 2, you're ready to consider updating your interaction model and hologram design placements. No HoloLens (1ª geração), o aplicativo provavelmente tem um modelo de interação de foco e confirmação com hologramas relativamente distantes para se ajustarem ao campo de visão.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.

Etapas para atualizar o design de seu aplicativo a fim de torná-lo mais adequado para o HoloLens 2:Steps to update your application design to be best suited for HoloLens 2:

  1. Componentes do MRTK: De acordo com o trabalho prévio, se você tiver adicionado o MRTK v2, haverá vários componentes/scripts a serem aproveitados que foram projetados e otimizados para o 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 interação: Considere a atualização do modelo de interação.Interaction model: Consider updating your interaction model. Para a maioria dos cenários, recomendamos a alternância do foco e da confirmação com as mãos.For most scenarios, we recommend switching from gaze and commit to hands. Com os hologramas normalmente ficando fora do alcance dos braços, a alternância para as mãos resulta em raios de apontador de interação e gestos de segurar distantes.With your holograms typically being out of arms-reach, switching to hands results in far interaction pointing rays and grab gestures.

  3. Posicionamento de hologramas: Depois de alternar para um modelo de interação com as mãos, considere a aproximação de alguns hologramas, a fim de interagir diretamente com eles usando gestos de segurar com interação próxima com as mãos.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. Os tipos de hologramas recomendados para aproximação a fim de segurar ou interagir diretamente são menus de destino menores, controles, botões e hologramas menores que se ajustam ao campo de visão do HoloLens 2 ao segurar e inspecionar o 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 aplicativo e cenário é diferente. Continuaremos refinando e postando diretrizes de design com base nos comentários e em aprendizados contínuos.Every application and scenario are different, and we’ll continue to refine and post design guidance based on feedback and continued learnings.

Advertências e aprendizados adicionais sobre como mover aplicativos do x86 para o ARMAdditional caveats and learnings about moving applications from x86 to ARM

  • Os aplicativos diretos do Unity são simples porque você pode criar um pacote de aplicativo ARM ou implantá-lo diretamente no dispositivo para que o pacote seja executado.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. Alguns plug-ins nativos do Unity podem apresentar certos desafios de desenvolvimento.Some Unity native plugins can present certain development challenges. Por isso, você deve atualizar todos os plug-ins nativos do Unity para o Visual Studio 2019 e, em seguida, recompilar para o ARM.Because of this, you must upgrade all Unity native plugins to Visual Studio 2019 and then rebuild for ARM.

  • Um aplicativo usou o plug-in AudioKinetic Wwise para Unity, e essa versão do Unity não tinha um plug-in do ARM para UWP. Como resultado, houve um esforço considerável para recriar as funcionalidades de som no aplicativo em questão para execução no 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. Verifique se todos os plug-ins necessários para os planos de desenvolvimento estão instalados e disponíveis no Unity.Ensure that all required plugins for your development plans are installed and available in Unity.

  • Em alguns casos, um plug-in do UWP/ARM pode não existir para os plug-ins requeridos pelo aplicativo, o que bloqueia a capacidade de portar o aplicativo e executá-lo no 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. Entre em contato com seu provedor de plug-in para resolver o problema e fornecer suporte para o ARM.Contact your plugin provider to resolve the issue and provide support for ARM.

  • O minfloat (e variantes como min16float, minint e assim por diante) em sombreadores pode se comportar de modo diferente no HoloLens 2 comparado ao HoloLens (1ª geração).The minfloat (and variants such as min16float, minint, and so on) in shaders might behave differently on HoloLens 2 than on HoloLens (1st gen). Especificamente, eles garantem que pelo menos o número especificado de bits seja usado.Specifically, these guarantee that at least the specified number of bits will be used. Em GPUs da Intel/da NVIDIA, os minfloats são basicamente tratados como 32 bits.On Intel/Nvidia GPUs, minfloats are largely treated as 32 bits. No ARM, o número de bits especificado é realmente respeitado.On ARM, the number of bits specified is actually adhered to. Isso significa que, na prática, esses números podem ter menos precisão ou alcance no HoloLens 2 do que tinham no HoloLens (1ª geração).That means in practice, these numbers might have less precision or range on HoloLens 2 than they did on HoloLens (1st gen).

  • As instruções de _asm não parecem funcionar no ARM, o que significa que qualquer código que use as instruções de _asm precisa ser reescrito.The _asm instructions don’t appear to work on ARM, meaning any code using _asm instructions must be rewritten.

  • O ARM não dá suporte à instrução SIMD definida porque vários cabeçalhos, como xmmintrin.h, emmintrin.h, tmmintrin.h e immintrin.h, não estão disponíveis no 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.

  • O compilador de sombreador no ARM é executado durante a primeira chamada de desenho depois que o sombreador é carregado ou algo do qual o sombreador depende é alterado, não no tempo de carregamento do 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. O impacto na taxa de quadros pode ser perceptível, dependendo de quantos sombreadores precisam ser compilados, com implicações de como os sombreadores devem ser tratados, empacotados e atualizados de maneira diferente no HoloLens 2 versus HoloLens (1ª geração).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).

Veja tambémSee also