Перенос приложений HoloLens (1-го поколения) в HoloLens 2Porting HoloLens (1st Gen) apps to HoloLens 2

Это руководство предназначено для разработчиков, которые используют существующее приложение Unity для HoloLens (1-го поколения) и хотят перенести его на устройство 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. Процесс переноса приложения Unity для HoloLens (1-го поколения) на HoloLens 2 состоит из четырех основных шагов.There are four key steps to porting a HoloLens (1st gen) Unity application to HoloLens 2.

Эти шаги подробно описаны в приведенных ниже разделах.The sections below detail information for each stage:

Шаг 1Step 1 Шаг 2Step 2 Шаг 3Step 3 Шаг 4Step 4
Логотип Visual Studio Логотип Unity Значок Unity Логотип МРТК
Скачивание новейших средствDownload latest tools Обновление проекта UnityUpdate Unity Project Компиляция для ARMCompile for ARM Миграция в MRTK версии 2Migrate to MRTK v2

Предварительные требованияPrerequisites

Мы настоятельно рекомендуем использовать систему управления версиями для сохранения моментального снимка первоначального состояния приложения до начала переноса.We highly recommended using source control to save a snapshot your applications original state before starting the porting process. Кроме того, мы рекомендуем сохранить данные состояния контрольных точек в разное время при выполнении процесса.Additionally, we recommend saving checkpoint states at various times during the process. Также удобно создать еще один экземпляр исходного приложения Unity, чтобы обеспечить сравнение версий приложения во время переноса.It can also be helpful to have another Unity instance of the original application to compare side by side during the porting process.

Примечание

Перед переносом убедитесь, что установлены последние версии средств разработки для Windows Mixed Reality.Before porting, ensure you have the latest tools installed for Windows Mixed Reality development. Для большинства разработчиков HoloLens это последняя версия Visual Studio 2019 и соответствующий пакет SDK для Windows.For most existing HoloLens developers, this involves updating to the latest version of Visual Studio 2019 and installing the appropriate Windows SDK. Подробное описание различных версий Unity и набора средств для смешанной реальности (MRTK) версии 2 представлено далее.The content that follows dives further into different Unity versions and the Mixed Reality Toolkit (MRTK) Version 2.

Дополнительные сведения см. в статье Install the tools (Установка средств).For more information, please see Install the tools.

Перенос проекта в последнюю версию UnityMigrate project to the latest version of Unity

Если вы используете MRTK версии 2, Unity 2019 LTS — наилучший вариант долгосрочной поддержки без критических изменений в Unity или 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. Оцените все зависимости от подключаемых модулей, которые существуют в проекте, а также определите возможность сборки этих библиотек DLL для ARM64.Assess any plugin dependencies that currently exist in your project, and determine whether these DLLs can be built for ARM64. Если в проекте есть жесткая зависимость от подключаемого модуля ARM64, возможно придется сохранить для приложения платформу ARM.For projects with a hard ARM64 dependent plugin, you may need to continue building your app for ARM.

Обновление параметров сцены или проектов в UnityUpdate scene/project settings in Unity

После обновления до Unity 2019 LTS рекомендуется изменить определенные параметры в Unity, чтобы получить оптимальные результаты на устройстве.After updating to Unity 2019 LTS, it's recommended that you update particular settings in Unity for optimal results on the device. Подробное описание этих параметров см. в статье Рекомендуемые параметры для Unity.These settings are outlined in detail under recommended settings for Unity.

Еще раз подчеркнем, что серверная часть сценариев .NET помечена как нерекомендуемая в Unity 2018 и удалена в Unity 2019.To reiterate, the .NET scripting back-end is being deprecated in Unity 2018 and removed in Unity 2019. Разработчикам настоятельно рекомендуется перевести проект на IL2CPP.Developers should strongly consider switching their project to IL2CPP.

Примечание

При использовании серверной части для работы со скриптами IL2CPP может увеличиться время сборки из Unity в Visual Studio. Разработчикам следует настроить свои компьютеры для разработки, чтобы оптимизировать время сборки 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. Кроме того, возможно, будет полезно настроить сервер кэширования, особенно для проектов Unity с большим объемом ресурсов (за исключением файлов скриптов) либо постоянно меняющимися сценами или ресурсами.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. Когда открывается проект, Unity сохраняет соответствующие ресурсы в формате для внутреннего кэша на компьютере разработчика.When opening a project, Unity stores qualifying assets into an internal cache format on the developer machine. Измененные элементы нужно повторно импортировать и еще раз обработать.Items must be re-imported and re-processed when modified. Этот процесс можно выполнить однократно и сохранить на сервере кэширования, а значит, и совместно использовать с другими разработчиками для экономии времени. При этом каждому разработчику не придется обрабатывать повторно импортированные измененные элементы локально.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.

Разобравшись с критическими изменениями после перехода на обновленную версию Unity, выполните сборку и тестирование текущих приложений для HoloLens (1-го поколения).After addressing any breaking changes from moving to the updated Unity version, build and test your current applications on HoloLens (1st gen). Кроме того, это подходящий момент для создания и сохранения фиксации в системе управления версиями.This is a good time to create and save a commit into source control.

Компиляция зависимостей или подключаемых модулей для процессора ARMCompile dependencies/plugins for ARM processor

Приложения для HoloLens 1-го поколения выполнялись на 32-разрядных (x86) процессорах. HoloLens 2 использует процессор ARM.HoloLens (1st gen) executes applications on an x86 processor while the HoloLens 2 uses an ARM processor. Существующие приложения HoloLens нужно перенести для поддержки ARM.Existing HoloLens applications need to be ported over to support ARM. Как отмечалось ранее, Unity 2018 LTS поддерживает компиляцию для приложений ARM32, а Unity 2019.x — для приложений ARM32 и ARM64.As noted earlier, Unity 2018 LTS supports compiling ARM32 apps while Unity 2019.x supports compiling ARM32 and ARM64 apps. Рекомендуется разрабатывать приложения ARM64, так как их производительность существенно выше.Developing for ARM64 applications is preferred, as there's a material difference in performance. Но в таком случае все зависимости подключаемого модуля также должны быть созданы для ARM64.However, this requires all plugin dependencies to also be built for ARM64.

Просмотрите все зависимости от библиотеки DLL в приложении.Review all DLL dependencies in your application. Рекомендуется удалить зависимости, которые больше не нужны для проекта.We recommend removing dependencies that are no longer needed for your project. Для остальных необходимых подключаемых модулей примите соответствующие двоичные файлы ARM32 и ARM64 в проекте Unity.For remaining plugins that are required, ingest the respective ARM32 or ARM64 binaries into your Unity project.

Когда будут приняты важные библиотеки DLL, создайте решение Visual Studio на основе Unity и скомпилируйте приложение AppX для ARM в Visual Studio, чтобы подтвердить возможность работы с процессорами 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. Мы рекомендуем сохранить это приложение как фиксацию в системе управления версиями.It's advised to save the application as a commit in your source control solution.

Важно!

Приложения, использующие MRTK версии 1, можно запускать на HoloLens 2 после изменения целевой платформы сборки на ARM при условии соблюдения всех других требований.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. К ним относится наличие ARM-версий для всех ваших подключаемых модулей.This includes making sure you have ARM versions of all your plugins. Но при этом ваше приложение не будет иметь доступа к специальным функциям HoloLens 2, таким как точное отслеживание движений рук и глаз.However, your app won't have access to HoloLens 2 specific functions like articulated hand and eye tracking. MRTK версии 1 и MRTK версии 2 имеют разные пространства имен, что позволяет использовать обе версии в одном проекте. Это может быть полезно при переходе от одной версии к другой.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.

Обновление до MRTK версии 2Update to MRTK version 2

МРТК версии 2 — это новый набор средств на основе Unity, который поддерживает как HoloLens (1-го поколения), так и HoloLens 2.MRTK Version 2 is the new toolkit on top of Unity that supports both HoloLens (1st gen) and HoloLens 2. Именно в него были добавлены все новые возможности HoloLens 2, такие как взаимодействие с помощью рук и отслеживание глаз.It's also where all the new HoloLens 2 capabilities have been added, such as hand interactions and eye tracking.

Дополнительные сведения об использовании MRTK версии 2 см. в следующих ресурсах:Check out the following resources for more information on using MRTK version 2:

Подготовка к миграцииPrepare for the migration

Перед приемом новых файлов *.unitypackage для MRTK версии 2 мы рекомендуем составить список 1) пользовательского кода, который интегрируется с MRTK версии 1 и 2) пользовательского кода для взаимодействия с входными данными или для компонентов интерфейса.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. Наиболее распространенные конфликты при освоении возможностей MRTK версии 2 для разработчиков в сфере смешанной реальности касаются методов ввода и взаимодействия.The most common and prevalent conflict for a mixed reality developer ingesting MRTK v2 involves input and interactions. Рекомендуем начать изучение модели ввода MRTK версии 2.It's advised to begin reading and understanding the MRTK v2 input model.

Наконец, в новом решении MRTK версии 2 реализован переход с модели скриптов и объектов управления в сцене на архитектуру конфигурации и поставщика служб.Finally, the new MRTK v2 has transitioned from a model of scripts and in-scene manager objects to a configuration and services provider architecture. В результате формируется более четкая иерархия и архитектурная модель. Но для этого нужно изучить новые профили конфигурации.This results in a cleaner scene hierarchy and architecture model, but requires a learning curve for understanding the new configuration profiles. Изучите руководство по настройке набора средств для смешанной реальности, чтобы приступить к ознакомлению с важными параметрами и профилями, которые нужно адаптировать к требованиям вашего приложения.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.

Перенос проектаMigrating the project

Есть высокая степень вероятности, что после импорта MRTK версии 2 в вашем проекте Unity возникнет множество ошибок компиляции.After importing MRTK v2, your Unity project most likely has many compiler-related errors. Часто это связано с новой структурой пространства имен и новыми именами компонентов.These are commonly because of the new namespace structure and new component names. Перейдите к устранению этих ошибок, изменяя пространства имен и компоненты во всех скриптах.continue to resolve these errors by modifying your scripts to the new namespaces and components.

Дополнительные сведения об определенных различиях между API для HTK/MRTK и MRTK версии 2 приведены в руководстве по переносу на вики-сайте MRTK версии 2.For information on the specific API differences between HTK/MRTK and MRTK v2, see the porting guide on the MRTK Version 2 wiki.

РекомендацииBest practices

  • Преимущество отдается стандартному построителю текстуры MRTK.Prefer use of the MRTK standard shader.
  • Работайте с типами критических изменений поочередно (например, переход с IFocusable на IMixedRealityFocusHandler).Work on one breaking change type at a time (ex: IFocusable to IMixedRealityFocusHandler).
  • Выполняйте проверку после каждого изменения и используйте систему управления версиями.Test after every change and use source control.
  • По возможности используйте стандартные элементы MRTK для взаимодействия с пользователем (кнопки, баннеры и т. д.).Use default MRTK UX (buttons, slates, and so on), when possible.
  • Не изменяйте файлы MRTK напрямую. Создайте оболочки для компонентов MRTK.Refrain from modifying MRTK files directly; create wrappers around MRTK components.
    • Это упрощает дальнейший прием данных и обновление MRTK.This action eases future MRTK ingestions and updates.
  • Просмотрите и изучите примеры сцен в MRTK, особенно HandInteractionExamples.scene.Review and explore sample scenes provided in the MRTK, especially HandInteractionExamples.scene.
  • Модифицируйте структуру пользовательского интерфейса на основе холста, используя четырехугольники, коллайдеры и текст TextMeshPro.Rebuild canvas-based UI with quads, colliders, and TextMeshPro text.
  • Включите общий доступ к буферу глубины или задайте точку фокусировки. Предпочтительно использовать 16-разрядный буфер глубины, чтобы повысить производительность.Enable Depth Buffer Sharing or set focus point; prefer to use a 16-bit depth buffer for better performance. Убедитесь, что при отрисовке цвета отображается глубина.Ensure when rendering color, to also render depth. Как правило, Unity не изменяет данные глубины для прозрачных и текстовых игровых объектов.Unity generally doesn't write depth for transparent and text gameobjects.
  • Задайте путь однопроходной отрисовки экземпляра.Set Single Pass Instanced Rendering Path.
  • Примените профиль конфигурации HoloLens 2 для MRTK.Use the HoloLens 2 configuration profile for MRTK

Тестирование приложенияTesting your application

В MRTK версии 2 вы можете имитировать взаимодействие с помощью рук непосредственно в Unity, а также выполнять разработку с новыми интерфейсами API для реализации взаимодействия с помощью рук и отслеживания глаз.In MRTK Version 2, you can simulate hand interactions directly in Unity and develop with the new APIs for hand interactions and eye tracking. Для создания оптимального пользовательского интерфейса требуется устройство HoloLens 2.The HoloLens 2 device is required to create a satisfying user experience. Мы рекомендуем ознакомиться с документацией и инструментами, чтобы составить более четкое представление о решении.You're encouraged to start studying the documentation and tools for greater understanding. MRTK версии 2 поддерживает разработку для устройств HoloLens (1-го поколения). Традиционные модели ввода (например, выбор элемента касанием) можно тестировать на HoloLens (1-го поколения).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).

Обновление модели взаимодействия для HoloLens 2Updating your interaction model for HoloLens 2

Внимание!

Если в проекте используются какие-либо API-интерфейсы XR.WSA, в будущих выпусках Unity они будут выведены из эксплуатации и заменены новыми API-интерфейсами ввода XR 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. Дополнительные сведения об API-интерфейсах ввода XR см. здесь.You can find more information about the XR input APIs here.

После переноса приложения и его подготовки к работе с HoloLens 2 можно приступить к обновлению модели взаимодействия и расположения макетов голограмм.Once your application is ported and prepped for HoloLens 2, you're ready to consider updating your interaction model and hologram design placements. В приложении, разработанном для HoloLens (1-го поколения), по всей вероятности, реализована модель взаимодействия с помощью направления взгляда с подтверждением. Она используется при взаимодействии с голограммами, расположенными на удалении, чтобы они могли поместиться в поле зрения.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.

Шаги по обновлению структуры приложения для максимальной адаптации к HoloLens 2:Steps to update your application design to be best suited for HoloLens 2:

  1. Компоненты MRTK. Если вы добавили MRTK версии 2, можно использовать различные компоненты и скрипты, которые разработаны и оптимизированы для 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. Модель взаимодействия. Рекомендуется обновить модель взаимодействия.Interaction model: Consider updating your interaction model. В большинстве случаев мы рекомендуем перейти с модели взаимодействия с помощью взгляда с подтверждением на модель взаимодействия с помощью рук.For most scenarios, we recommend switching from gaze and commit to hands. Например, для голограмм, которые обычно оказываются за пределами досягаемости, используются лучи, указывающие на предмет при удаленном взаимодействии, и жесты захвата.With your holograms typically being out of arms-reach, switching to hands results in far interaction pointing rays and grab gestures.

  3. Расположение голограммы. Когда вы перейдете на модель взаимодействия с помощью рук, переместите некоторые голограммы ближе, используя жесты захвата, чтобы непосредственно взаимодействовать с ними руками.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. Мы рекомендуем переместить ближе такие типы голограмм: небольшие целевые меню, элементы управления, кнопки и небольшие голограммы, которые помещаются в поле зрения HoloLens 2 при захвате и рассмотрении голограммы.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.
    Все приложения и сценарии разные. Мы будем продолжать совершенствовать и публиковать рекомендации по разработке на основе отзывов и полученных знаний.Every application and scenario are different, and we’ll continue to refine and post design guidance based on feedback and continued learnings.

Дополнительные предостережения и сведения о переводе приложений с 32-разрядных процессоров на ARMAdditional caveats and learnings about moving applications from x86 to ARM

  • Базовые приложения Unity просты. Вы можете создать пакет приложений ARM или выполнить развертывание непосредственно на устройстве для запуска пакета.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. Некоторые собственные подключаемые модули Unity могут вызывать определенные проблемы при разработке.Some Unity native plugins can present certain development challenges. Поэтому необходимо обновить все собственные подключаемые модули Unity до версии Visual Studio 2019, а затем повторно выполнить сборку для ARM.Because of this, you must upgrade all Unity native plugins to Visual Studio 2019 and then rebuild for ARM.

  • Предположим, что в приложении используется подключаемый модуль AudioKinetic Wwise и в этой версии Unity нет подключаемого модуля UWP для ARM. В такой ситуации придется потратить много усилий на доработку звуковых возможностей в приложении для запуска на 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. Убедитесь, что все необходимые подключаемые модули для планов разработки установлены и доступны в Unity.Ensure that all required plugins for your development plans are installed and available in Unity.

  • Иногда для подключаемых модулей, требующихся приложению, может не быть подключаемых модулей UWP или ARM. Это препятствует переносу приложения и его запуску на 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. Обратитесь к поставщику подключаемого модуля, чтобы устранить проблему и обеспечить поддержку ARM.Contact your plugin provider to resolve the issue and provide support for ARM.

  • Элементы minfloat (и их разновидности, такие как min16float, minint и т. д.) в шейдерах могут по-разному действовать на HoloLens 2 и HoloLens (1-го поколения).The minfloat (and variants such as min16float, minint, and so on) in shaders might behave differently on HoloLens 2 than on HoloLens (1st gen). Но при этом гарантируется, что по крайней мере будет использоваться указанное количество битов.Specifically, these guarantee that at least the specified number of bits will be used. Графические процессоры Intel и Nvidia преимущественно обрабатывают minifloat как 32-битные.On Intel/Nvidia GPUs, minfloats are largely treated as 32 bits. В ARM будет использоваться фактическое количество битов.On ARM, the number of bits specified is actually adhered to. Это означает, что на практике эти показатели будут менее точными или диапазон на HoloLens 2 будет меньше, чем на HoloLens (1-го поколения).That means in practice, these numbers might have less precision or range on HoloLens 2 than they did on HoloLens (1st gen).

  • Инструкции _asm не будут работать в ARM. Поэтому потребуется переписать все строки кода, где используются инструкции _asm.The _asm instructions don’t appear to work on ARM, meaning any code using _asm instructions must be rewritten.

  • ARM не поддерживает набор инструкций SIMD, потому что в ARM отсутствуют некоторые заголовки, такие как xmmintrin.h, emmintrin.h, tmmintrin.h и immintrin.h.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.

  • Компилятор построителя текстуры запускается в ARM во время первого вызова метода рисования после загрузки построителя текстуры или при изменении объекта, от которого зависит построитель, не во время его загрузки.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. Влияние на частоту кадров может быть заметным в зависимости от того, сколько шейдеров необходимо скомпилировать, и это диктует изменение правил обработки, упаковки и обновления шейдеров для HoloLens 2 по сравнению с HoloLens (1-го поколения).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).

См. также статьюSee also