HoloLens (第 1 世代) アプリを HoloLens 2 に移植するPorting HoloLens (1st Gen) apps to HoloLens 2

このガイドは、HoloLens (第 1 世代) 用の既存の Unity アプリケーションを持つ開発者が、アプリケーションを 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. HoloLens (第 1 世代) の Unity アプリケーションを HoloLens 2 に移植する主な手順は 4 つあります。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 のアイコン MRTK のロゴ
最新のツールのダウンロードDownload latest tools Unity プロジェクトの更新Update Unity Project ARM 用にコンパイルCompile for ARM MRTK v2 に移行Migrate 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 への更新と適切な Windows SDK のインストールを行うことになります。For most existing HoloLens developers, this involves updating to the latest version of Visual Studio 2019 and installing the appropriate Windows SDK. 以下の内容では、Unity のさまざまなバージョンと Mixed Reality Toolkit (MRTK) バージョン 2 についてさらに詳しく説明します。The content that follows dives further into different Unity versions and the Mixed Reality Toolkit (MRTK) Version 2.

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

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

MRTK v2 を使用している場合、Unity または MRTK で破壊的変更が発生しない最適な長期サポート パスは Unity 2019 LTS になります。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.

Unity でシーンまたはプロジェクト設定を更新するUpdate 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. このプロセスが 1 回実行されると、キャッシュ サーバーに保存され、すべての開発者と共有されます。すべての開発者がローカルで新しい変更の再インポート処理を行う必要がなくなるので、時間を節約できます。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.

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

HoloLens (第 1 世代) は、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. 必要な残りのプラグインについて、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 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 v1 を使用するアプリケーションは、ビルド ターゲットを ARM に変更すると、HoloLens 2 で実行できるようになります。ただし、他のすべての要件が満たされていることが必要です。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 v1 と MRTK v2 とでは名前空間が異なるため、両方のバージョンを同一のプロジェクトに含めることができます。これは、一方からもう一方に移行するのに役立ちます。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 バージョン 2 に更新するUpdate to MRTK version 2

MRTK バージョン 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

新しい MRTK v2 用の *.unitypackage ファイルを取り込む前に、1) MRTK v1 を組み込んだ任意のカスタム ビルド コード と、2) 入力操作や UX コンポーネント用のカスタム ビルド コード のインベントリを取得することをお勧めします。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. Mixed Reality 開発者が MRTK v2 を取り込む際に最も競合が起きやすいのは、入力と操作に関係する部分です。The most common and prevalent conflict for a mixed reality developer ingesting MRTK v2 involves input and interactions. MRTK v2 入力モデルを読んで理解しておくことをお勧めします。It's 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 ツールキット構成ガイドを参照してください。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 v2 をインポートすると、高い確率で、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.

HTK/MRTK と MRTK v2 の具体的な API の相違点については、MRTK バージョン 2 wiki の移植ガイドをご覧ください。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.
  • 互換性に影響する種類の変更には 1 つずつ対応する (例:IFocusable を IMixedRealityFocusHandler に)。Work on one breaking change type at a time (ex: IFocusable to IMixedRealityFocusHandler).
  • 変更のたびにテストし、ソース管理を使用する。Test after every change and use source control.
  • 可能な場合は既定の MRTK UX (ボタン、スレートなど) を使用する。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.
  • キャンバス ベースの UI を四角形、コライダー、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.
  • MRTK 用の HoloLens 2 構成プロファイルを使用する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 v2 は 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 2 向けの操作モデルの更新Updating your interaction model for HoloLens 2

注意事項

プロジェクトでいずれかの XR.WSA API を使用している場合、今後の Unity のリリースでは Unity の新しい XR 入力 API が優先されるため、それらは段階的に廃止されています。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. XR 入力 API の詳細についてはこちらを参照してください。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 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 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.

X86 から ARM へのアプリケーションの移行に関するその他の注意事項と確認事項Additional 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.

  • 1 つのアプリケーションで Unity 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 の GPU では、minfloat は主に 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).

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

  • ARM では xmmintrin.h、emmintrin.h、tmmintrin.h、immintrin.h などの各種ヘッダーを使用できないため、ARM では SIMD 命令セットはサポートされません。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