既存のアプリを HoloLens 2 で利用できるようにするGetting your existing app ready for HoloLens 2

このガイドは、HoloLens (第 1 世代) 用の既存 Unity アプリがある開発者が新しい HoloLens 2 デバイス用のアプリケーションに移植する際に特に役立ちます。This guide is specifically tailored to help developers who have an existing Unity app for HoloLens (1st gen) to port their application for the new HoloLens 2 device. 4 つの主要手順で、HoloLens (第 1 世代) の Unity アプリを HoloLens 2 に移植することができます。There are four key steps to porting a HoloLens (1st gen) Unity app to HoloLens 2. 以下のセクションでは、各ステージについて詳しく説明します。The sections below will detail information for each stage.

手順 1Step 1 手順 2Step 2 手順 3Step 3 手順 4Step 4
Visual Studio のロゴ Unity のロゴ Unity のアイコン MRTK のロゴ
最新のツールのダウンロードDownload latest tools Unity プロジェクトの更新Update Unity Project ARM 用にコンパイルCompile for ARM MRTK v2 に移行Migrate to MRTK v2

移植プロセスを開始する前に、開発者がソース管理を利用してアプリの元の状態のスナップショットを保存しておくことを強くお勧めしますIt is highly recommended that, before beginning the porting process, developers utilize source control to save a snapshot of the original state of their app. さらに、プロセス中のさまざまな時点でチェックポイントの状態を保存することを推奨します。Additionally, it is recommended to save checkpoint states at various points during the process. 移植プロセスの中で、元のアプリの別の Unity インスタンスを並べて比較できるようにするのも非常に便利です。It can also be very helpful to have another Unity instance of the original app to allow for side-by-side comparison during the port process.

注意

移植の前に、Windows Mixed Reality の開発用に最新のツールがインストールされていることを確認します。Before porting, ensure you have the latest tools installed for Windows Mixed Reality development. ほとんどの既存 HoloLens 開発者は、主に最新の Visual Studio 2017 への更新と適切な Windows SDK のインストールを行うことになります。For most existing HoloLens developers, this will primarily involve updating to the latest Visual Studio 2017 and installing the appropriate Windows SDK. 以下の内容では、Unity のさまざまなバージョンと Mixed Reality Toolkit バージョン 2 についてさらに詳しく説明します。The content below will dive further into different Unity versions and the Mixed Reality Toolkit version 2.

詳しくは、ツールのインストールに関するページをご覧ください。For more information, please see Install the tools.

プロジェクトを最新バージョンの Unity に移行するMigrate project to latest version of Unity

MRTK v2 を使用している場合、Unity または MRTK で互換性に影響する変更が発生しない最適な長期サポート パスは Unity 2018 LTS になります。If using the MRTK v2, then Unity 2018 LTS will be the best long-term support path with no breaking changes in Unity or in MRTK. 上記のツールのインストールに関するページでは、推奨される Unity ビルドは Unity 2018.3 です。今後これが Unity 2018 の LTS リリースになります。The recommended Unity build, per the above "install the tools" is Unity 2018.3, which will become the LTS release for Unity 2018. また、MRTK v2 は Unity 2018 LTS のサポートを常に保証していますが、必ずしも Unity 2019.x のすべてのイテレーションのサポートが保証されるわけではありません。Further, the MRTK v2 will always guarantee support for Unity 2018 LTS but not necessarily guarantee support for every iteration of Unity 2019.x.

Unity 2018.3.x または Unity 2019.1.x との間の他の相違点を明らかにするために、以下では、これら 2 つのバージョン間でのトレードオフについて説明します。主な違いは、Unity 2019 で ARM64 用にコンパイルする機能です。To help clarify additional differences between Unity 2018.3.x or Unity 2019.1.x, below outlines the trade-offs between these two versions, with the primary difference of significance being the ability to compile for ARM64 in Unity 2019.

開発者は、現在プロジェクトに存在するすべてのプラグインの依存関係と、DLL が ARM64 でビルドできるかどうかを評価する必要があります。Developers should assess any plugin dependencies that currently exist in their project and whether or not these DLLs can be built for ARM64. ARM64 でハードに依存するプラグインをビルドできない場合は、Unity 2018 LTS を使用しなければなりません。If a hard dependency plugin cannot be built for ARM64, then one will have to utilize Unity 2018 LTS.

Unity 2018.3.xUnity 2018.3.x Unity 2019.1+Unity 2019.1+
ARM32 ビルドのサポートARM32 build support ARM32 および ARM64 ビルドのサポートARM32 and ARM64 build support
安定版の LTS ビルド リリースStable LTS build release ベータ版の安定性Beta stability
.NET スクリプト バックエンド 非推奨.NET Scripting back-end deprecated .NET スクリプト バックエンド 削除済み.NET Scripting back-end removed
UNET Networking 非推奨UNET Networking deprecated UNET Networking 削除済みUNET Networking removed

Unity でシーンまたはプロジェクト設定を更新するUpdate scene/project settings in Unity

デバイスで最適な結果を得るために、Unity 2018.3.x または Unity 2019 以降に更新した後、Unity を特定の設定に更新すること をお勧めします。After updating to Unity 2018.3.x or Unity 2019+, it is recommended to update particular settings in Unity for optimal results on device. この設定については、 Unity の推奨設定 で詳しく説明しています。These settings are outlined in detail under Recommended settings for Unity.

もう一度お伝えしますが、.NET スクリプト バックエンドは、Unity 2018 で非推奨となり、Unity 2019 で削除されているため、開発者はプロジェクトを IL2CPP に切り替えることを検討する必要があります。It should be re-iterated that the .NET Scripting back-end is being deprecated in Unity 2018 and removed in Unity 2019 and thus, developers should strongly consider switching their project over to IL2CPP.

注意

IL2CPP スクリプト バックエンドを使用すると、Unity から Visual Studio へのビルド時間が長くなる場合があります。そのため、開発者はコンピューターをセットアップするためIL2CPP ビルド時間の最適化を行う必要があります。IL2CPP scripting back-end can cause longer build times from Unity to Visual Studio and thus developers should setup their developer machine for optimizing IL2CPP build times. 特に、大きなアセット (スクリプト ファイルを除く) がある場合や、常にシーンやアセットを変更する Unity プロジェクトの場合は、キャッシュ サーバーをセットアップするとよいでしょう。Furthermore, it may be beneficial to setup a Cache Server, especially for Unity projects with a large amount of assets (excluding script files) or constantly changing scenes/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 thus re-processed when modified. このプロセスが 1 回実行されると、キャッシュ サーバーに保存され、すべての開発者に共有されます。すべての開発者がローカルで新しい変更の再インポート処理を行う必要がなくなるので、時間を節約できます。This process can be done once and saved in a Cache Server and consequently shared with other developers to save time, instead of every developer processing the re-import of new changes locally.

開発者は、更新した Unity のバージョンに移行し、互換性のない変更に対処した後、HoloLens (第 1 世代) で現在のアプリをビルドしてテストする必要があります。After addressing any breaking changes after moving to the updated Unity version, developers should build and test their current apps on HoloLens (1st gen). また、この時点でソース管理にコミットを作成し、保存しておくとよいでしょう。Further, this is a good point to create and save a commit for source control.

ARM プロセッサ用の依存関係およびプラグインのコンパイルCompile dependencies/plugins for ARM processor

HoloLens (第 1 世代) は、x86 プロセッサ上でアプリケーションを実行しますが、新しい HoloLens 2 デバイスは、ARM プロセッサを利用します。HoloLens (1st gen) executed applications on an x86 processor while the new HoloLens 2 device utilizes an ARM processor. したがって、既存のアプリケーションは、ARM をサポートするように移植する必要があります。Thus, existing applications need to be ported over to support ARM. 前述のように、Unity 2018 は ARM32 アプリのコンパイルをサポートしますが、Unity 2019 以降は ARM64 アプリのコンパイルをサポートします。As noted earlier, Unity 2018 supports compiling for ARM32 apps while Unity 2019+ supports compiling for ARM64 apps. 一般的に、パフォーマンスに重要な相違があるため、ARM64 アプリケーションでの開発が推奨されます。Developing for ARM64 applications is generally preferred as there is 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 currently. 依存関係が不要になった場合は、プロジェクトから削除することをお勧めします。If a dependency is no longer needed, it is advisable to remove it from your project. 必要な残りのプラグインについて、Unity プロジェクトにそれぞれ ARM32 または ARM64 バイナリを取り込みます。For remaining plugins that are required, ingest the respective ARM32 or ARM64 binaries into your Unity project.

関連する DLL を取り込んだ後、Unity から Visual Studio ソリューションをビルドし、アプリケーションが ARM プロセッサでビルドできるかどうかを試すために、Visual Studio で AppX を ARM 向けにコンパイルします。After ingesting the relevant DLLs, build a Visual Studio solution from Unity and then compile an AppX for ARM in Visual Studio to test that your application can be built for ARM processors. ここが、ソース管理ソリューションでコミットを保存することが推奨されるもう 1 つのポイントです。This another point where it is advised to save a commit in your source control solution.

MRTK バージョン 2 に更新するUpdate to MRTK version 2

MRTK バージョン 2 は、Unity をベースにした新しいツールキットで、HoloLens (第 1 世代) と HoloLens 2 の両方をサポートしています。また、手による操作や視線追跡など、すべての HoloLens 2 の新機能が追加されています。MRTK version 2 is the new toolkit on top of Unity supporting both HoloLens (1st gen) and HoloLens 2, and where all of the new HoloLens 2 capabilities have been added, such as hand interactions and eye tracking.

移行を準備するPrepare for the migration

新しい MRTK v2 用の *.unitypackage ファイルを取り込む前に、1) MRTK v1 を組み込んだ任意のカスタム ビルド コードと、2) 入力操作や UX コンポーネントのカスタム ビルド コードのインベントリを取得することを推奨します。Before ingesting the new *.unitypackage files for MRTK v2, it is 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. Mixed Reality 開発者が新しい MRTK v2 を取り込む際に最も競合が起きやすいのは、入力と操作に関係する部分です。The most common and prevalent conflict for a Mixed Reality developer ingesting the new MRTK v2 will involve input and interactions. そのため、MRTK v2 入力モデルを読んで理解しておくことをお勧めします。Thus, it is advised to begin reading and understanding the MRTK v2 input model.

最後に、新しい MRTK v2 は、スクリプトのモデルおよびシーン内マネージャー オブジェクトから、構成およびサービス プロバイダー アーキテクチャに移行されています。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. したがって、重要な設定やプロファイルについて理解し、アプリケーションのニーズに合わせて調整することができるように、Mixed Reality ツールキット構成ガイドを参照してください。Thus, please 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.

移行するPerform the migration

MRTK v2 をインポートすると、Unity プロジェクトでたくさんのコンパイラ関連エラーが発生します。After importing MRTK v2, your Unity project will likely have many compiler related errors. 多くの場合、これらの原因は新しい名前空間の構造と新しいコンポーネント名です。These are most commonly due to the new namespace structure and new component names. スクリプトの名前空間とコンポーネントを新しいものに変更し、これらのエラーを解決します。Proceed to resolve these errors by modifying your scripts to the new namespaces and components.

HTK/MRTK と MRTK バージョン 2 の具体的な API の相違点の詳細については、 MRTK バージョン 2 wiki の移植ガイドをご覧ください。For more information on specific API differences between HTK/MRTK and MRTK version 2, see the porting guide on the MRTK Version 2 wiki.

ベスト プラクティスBest practices

  • MRTK 標準シェーダーの使用を優先するPrefer use of the MRTK Standard shader
  • 互換性に影響する種類の変更には 1 つずつ対応する (例:IFocusable を IMixedRealityFocusHandler に)Work on one breaking change type at a time (ex: IFocusable to IMixedRealityFocusHandler)
  • 変更のたびにテストし、ソース管理を利用するTest after every change and utilize source control
  • 可能な場合は既定の MRTK UX (ボタン、スレートなど) を使用するUse default MRTK UX (buttons, slates, etc) when possible
  • MRTK ファイルを直接変更するのは避け、MRTK コンポーネントのラッパーを作成するTry to refrain from modifying MRTK files directly, instead create wrappers around MRTK components
    • 将来の MRTK の取り込みや更新プログラムの影響を受けなくなるThis will protect against future MRTK ingestions and updates
  • MRTK で提供されているサンプルのシーンを確認する (特に HandInteractionExamples.scene)Review & explore sample scenes provided in MRTK (especially HandInteractionExamples.scene)
  • キャンバス ベースの UI を四角形、コライダー、TextMeshPro テキストで再構築するRebuild canvas-based UI with quads, colliders and TextMeshPro text instead

アプリケーションのテストTesting your application

RC1 時点で、HoloLens 2 のコンポーネントおよび機能が MRTK バージョン 2 で使用できるようになっています。そのため、手による操作を直接 Unity でシミュレートし、手による操作と視線追跡の新しい API を使って開発を行うことができます。Now that HoloLens 2 components and capabilities are available in MRTK version 2, as of RC1, you can simulate the hand interactions directly in Unity, and develop against the new APIs for hand interactions and eye tracking. 優れたエクスペリエンスを作成するには HoloLens 2 デバイスが必要ですが、少なくとも、ツールと説明書の学習を始めることはできます。The HoloLens 2 device is required to create a great experience, but at least one could start learning in the tools and documentation. また、MRTK v2 は HoloLens (第 1 世代) の開発をサポートしています。そのため、エア タップによる選択などの従来の入力モデルは、引き続き HoloLens (第 1 世代) デバイスでテストできます。Further, MRTK v2 supports development on HoloLens (1st gen) and thus, traditional input models such as select via air-tap can still be tested on HoloLens (1st gen) devices.

HoloLens 2 の操作モデルの更新Updating interaction model for HoloLens 2

アプリを移植して HoloLens 2 に対応できたら、操作モデルやホログラムの設計および配置の更新を検討する準備が整います。Once you have your app ported and prepped for HoloLens 2, you are ready to consider updating your interaction model and hologram designs/placement. もともと HoloLens (第 1 世代) のアプリだったため、視線入力とコミットによる操作モデルが使われており、視野に収まるようにホログラムがかなり遠くにある可能性が高いはずです。Coming from HoloLens (1st gen), your app 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 app design to be best for HoloLens 2:

  1. MRTK コンポーネント:事前の作業で MRTK v2 を追加した場合は、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 will result in far interaction pointing rays and grab gestures. 注: ツールを持っているタスク ワーカーなど、手を使わない操作モデルが必要なシナリオもあります。このような場合に向けた特別な設計ガイダンスが存在します。Note: there are scenarios where a hands-free interaction model is required, such as a task worker holding tools, and there is specific design guidance for such cases.

  3. ホログラムの配置:手による操作モデルに切り替えた後は、直接手で近接インタラクションのグラブ ジェスチャを使用した操作を行えるように、ホログラムを近くに移動することを検討します。Hologram placement: After switching to a hands interaction model, consider moving some holograms closer to directly interact with the holograms with your hands, using near interaction grab gestures. 直接つかんだり操作を行ったりするために近くに移動させることが推奨されるホログラムの種類は、小さなターゲット メニュー、コントロール、ボタン、およびグラブしたり調べたりしても 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 app and scenario is different, and we’ll continue to refine and post design guidance based on feedback and continued learnings.

x86 から ARM へのアプリを移植するにあたっての追加情報Additional learnings from moving apps from x86 to ARM

  • 単純な Unity アプリは、ARM appx バンドルをビルドしてデバイスに直接配置すれば実行できるので、簡単です。Straight Unity apps are simple as you can build an ARM appx bundle or deploy directly to the device and it runs. 問題は、Unity アプリがネイティブ プラグインを使用する場合です。The challenge comes when the Unity app uses native plugins. すべてのネイティブ プラグインは、VS2017 にアップグレードして ARM 用にビルドしなおす必要があります。Unity 2019 では、ARM64 用にビルドしなおします。All of the native plugins need to be upgraded to VS2017 and rebuilt for ARM, and with Unity 2019, ARM64.

  • Unity で AudioKinetic Wwise プラグインを使用しているあるアプリでは、使用されているバージョンに UWP ARM プラグインがありませんでした。One app, used the AudioKinetic Wwise plugin for Unity, and the version used didn’t have a UWP ARM plugin. アプリケーションのサウンドを見直して ARM で動作するようになるまで、数日がかかりました。It took several days to re-work the sound in the application to work on ARM.

  • 他にも、アプリに必要なプラグインの UWP/ARM プラグインが存在しないため、移植して HoloLens 2 で実行することができない場合もあるかもしれません。In other cases, a UWP/ARM plugin may not exist for app-required plugins, blocking the ability to port and run on HoloLens 2. これに対処して ARM をサポートするには、プラグインのプロバイダーによる作業が必要になる可能性もあります。Engagement with the plugin provider may be needed to unblock and support ARM.

  • HoloLen 2 では、シェーダーの minfloat (および min16float、minint などのバリアント) の動作が HoloLens (第 1 世代) と異なる場合があります。The minfloat (and variants such as min16float, minint, etc…) in shaders may behave differently on HoloLen 2 than on HoloLens (1st gen). 具体的には、「少なくとも指定された数のビットが使われる」ことが保証されます。Specifically, these guarantee that “at least the specified number of bits will be used”. ほとんどの Intel/Nvidia の GPU では、単なる 32 ビットとして扱われます。On Intel/Nvidia GPUs, these are largely just treated as 32 bits. ARM では、指定されたビット数が実際に使用されます。On ARM, the number of bits specified is actually respected. 実際には、HoloLens 2 でのこれらの数値の精度や範囲は、HoloLens (第 1 世代) よりも小さくなります。That means that in practice, these numbers may have less precision/range on HoloLens 2 than they did on HoloLens (1st gen).

  • ARM では _asm 命令は動作しないと見られるので、_asm 命令を使っているコードはすべて書き直す必要があります。The _asm instructions don’t appear to work on ARM, meaning any code using _asm instructions will have to be rewritten.

  • ARM では、SIMD 命令セットがサポートされていません。The SIMD instruction set is not supported on ARM. そのため、ARM では xmmintrin.h、emmintrin.h、tmmintrin.h、および immintrin.h などの各種ヘッダーは使用できません。This means various headers, such as xmmintrin.h, emmintrin.h, tmmintrin.h, and immintrin.h are not 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. コンパイルする必要があるシェーダーの数によっては、フレーム レートへの影響が顕著になる場合があります。The impact on framerate can be very noticeable, depending on how many shaders need to be compiled. この点から、HoloLens 2 と HoloLens (第 1 世代) でどのようにシェーダーの処理/パッケージ化/更新の方法を変えるべきかについて、さまざまなことがわかります。This has various implications for how shaders should be handled/packaged/updated differently on HoloLens 2 vs HoloLens (1st gen).

関連項目See also