カスタム Holographic リモート処理プレーヤーアプリの作成Writing a custom Holographic Remoting player app

重要

このドキュメントでは、HoloLens 2 用のカスタムプレーヤーアプリケーションの作成について説明します。This document describes the creation of a custom player application for HoloLens 2. HoloLens 2 向けに作成されたカスタムプレーヤーは、HoloLens 1 用に作成されたリモートアプリケーションと互換性がありません。Custom players written for HoloLens 2 are not compatible with remote applications written for HoloLens 1. これは、両方のアプリケーションが NuGet パッケージバージョン 2.x を使用する必要があることを意味します。This implies that both applications must use NuGet package version 2.x.x.

カスタム Holographic リモート処理プレーヤーアプリを作成することにより、HoloLens 2 のリモートコンピューター上のから イマーシブビュー を表示できるカスタムアプリケーションを作成できます。By creating a custom Holographic Remoting player app you can create a custom application capable of displaying immersive views from on a remote machine on your HoloLens 2. この記事では、これを実現する方法について説明します。This article describes how this can be achieved. このページのすべてのコードと作業中のプロジェクトは、 Holographic リモート処理のサンプル github リポジトリにあります。All code on this page and working projects can be found in the Holographic Remoting samples github repository.

Holographic リモート処理プレーヤーを使用すると、アプリは、デスクトップ PC または、Xbox One などの UWP デバイスで レンダリング された Holographic コンテンツを表示して、より多くのシステムリソースにアクセスできるようになります。A Holographic Remoting player allows your app to display holographic content rendered on a desktop PC or on a UWP device such as the Xbox One, allowing access to more system resources. Holographic Remoting player アプリは、入力データを Holographic リモート処理リモートアプリケーションにストリーミングし、ビデオとオーディオストリームとしてイマーシブビューを受信します。A Holographic Remoting player app streams input data to a Holographic Remoting remote application and receives back an immersive view as video and audio stream. 接続は標準の Wi-fi を使用して行われます。The connection is made using standard Wi-Fi. プレーヤーアプリを作成するには、NuGet パッケージを使用して Holographic Remoting を UWP アプリに追加し、接続を処理し、イマーシブビューを表示するコードを記述します。To create a player app, you will use a NuGet package to add Holographic Remoting to your UWP app, and write code to handle the connection and to display an immersive view.

必須コンポーネントPrerequisites

開始点としては、既に Windows Mixed Reality API を対象としている、動作する DirectX ベースの UWP アプリを使用することをお勧めします。A good starting point is a working DirectX based UWP app that already targets the Windows Mixed Reality API. 詳細については、「 DirectX 開発の概要」を参照してください。For details see DirectX development overview. 既存のアプリがなく、最初から開始する場合は、 C++ holographic プロジェクトテンプレート を開始することをお勧めします。If you do not have an existing app and want to start from scratch the C++ holographic project template is a good starting point.

重要

Holographic リモート処理を使用するすべてのアプリは、 マルチスレッドアパートメントを使用するように作成する必要があります。Any app using Holographic Remoting should be authored to use a multi-threaded apartment. シングルスレッドアパートメントの使用はサポートされていますが、パフォーマンスが低下し、再生中に途切れが生じる可能性があります。The use of a single-threaded apartment is supported but will lead to sub-optimal performance and possibly stuttering during playback. C++ を使用している場合、winrt winrt:: init_apartment 、マルチスレッドアパートメントが既定値です。When using C++/WinRT winrt::init_apartment a multi-threaded apartment is the default.

Holographic リモート処理 NuGet パッケージを取得するGet the Holographic Remoting NuGet package

Visual Studio で NuGet パッケージをプロジェクトに追加するには、次の手順を実行する必要があります。The following steps are required to add the NuGet package to a project in Visual Studio.

  1. Visual Studio でプロジェクトを開きます。Open the project in Visual Studio.
  2. プロジェクトノードを右クリックし、[ NuGet パッケージの管理... ] を選択します。Right-click the project node and select Manage NuGet Packages...
  3. 表示されるパネルで、[ 参照 ] をクリックし、"Holographic Remoting" を検索します。In the panel that appears, click Browse and then search for "Holographic Remoting".
  4. [ Holographic] を選択し 、最新の 2.x バージョンを選択して [ インストール] をクリックします。Select Microsoft.Holographic.Remoting, ensure to pick the latest 2.x.x version and click Install.
  5. [ プレビュー ] ダイアログが表示されたら、[ OK] をクリックします。If the Preview dialog appears, click OK.
  6. 次に表示されるダイアログは、使用許諾契約書です。The next dialog that appears is the license agreement. [ 同意 する] をクリックして、使用許諾契約書に同意します。Click on I Accept to accept the license agreement.

重要

build\native\include\HolographicAppRemoting\Microsoft.Holographic.AppRemoting.idlNuGet パッケージ内には、Holographic Remoting によって公開される API に関する詳細なドキュメントが含まれています。The build\native\include\HolographicAppRemoting\Microsoft.Holographic.AppRemoting.idl inside the NuGet package contains detailed documentation for the API exposed by Holographic Remoting.

アプリケーションの package.appxmanifest を変更するModify the Package.appxmanifest of the application

NuGet パッケージによって追加された Microsoft.Holographic.AppRemoting.dll をアプリケーションが認識できるようにするには、次の手順をプロジェクトで実行する必要があります。To make the application aware of the Microsoft.Holographic.AppRemoting.dll added by the NuGet package, the following steps need to be taken on the project:

  1. ソリューションエクスプローラーで package.appxmanifest ファイルを右クリックし、[プログラムから開く] を選択します。In the Solution Explorer right-click on the Package.appxmanifest file and select Open With...
  2. XML (テキスト) エディター を選択し、[OK] をクリックします。Select XML (Text) Editor and click OK
  3. 次の行をファイルに追加して保存します。Add the following lines to the file and save
  </Capabilities>

  <!--Add lines below -->
  <Extensions>
    <Extension Category="windows.activatableClass.inProcessServer">
      <InProcessServer>
        <Path>Microsoft.Holographic.AppRemoting.dll</Path>
        <ActivatableClass ActivatableClassId="Microsoft.Holographic.AppRemoting.PlayerContext" ThreadingModel="both" />
      </InProcessServer>
    </Extension>
  </Extensions>
  <!--Add lines above -->

</Package>

プレーヤーのコンテキストを作成するCreate the player context

最初の手順として、アプリケーションでプレーヤーコンテキストを作成する必要があります。As a first step the application should create a player context.

// class declaration:

#include <winrt/Microsoft.Holographic.AppRemoting.h>

...

private:
// PlayerContext used to connect with a Holographic Remoting remote app and display remotely rendered frames
winrt::Microsoft::Holographic::AppRemoting::PlayerContext m_playerContext = nullptr;
// class implementation:

// Create the player context
// IMPORTANT: This must be done before creating the HolographicSpace (or any other call to the Holographic API).
m_playerContext = winrt::Microsoft::Holographic::AppRemoting::PlayerContext::Create();

警告

Holographic リモート処理は、Windows の一部である Windows Mixed Reality ランタイムをリモート処理固有のランタイムに置き換えることによって機能します。Holographic Remoting works by replacing the Windows Mixed Reality runtime which is part of Windows with a remoting specific runtime. これは、プレーヤーのコンテキストの作成時に実行されます。This is done during the creation of the player context. そのため、プレーヤーコンテキストを作成する前に Windows Mixed Reality API を呼び出すと、予期しない動作が発生する可能性があります。For that reason any call on any Windows Mixed Reality API before creating the player context can result in unexpected behavior. 推奨される方法は、任意の混合 Reality API と対話する前に、可能な限り早くプレーヤーコンテキストを作成することです。The recommended approach is to create the player context as early as possible before interaction with any Mixed Reality API. Windows Mixed Reality API を使用して作成または取得したオブジェクトを、 PlayerContext::Create 後で作成または取得したオブジェクトで混在させないでください。Never mix objects created or retrieved through any Windows Mixed Reality API before the call to PlayerContext::Create with objects created or retrieved afterwards.

次に、 HolographicSpaceを呼び出して、HolographicSpace を作成します。Next the HolographicSpace can be created, by calling HolographicSpace.CreateForCoreWindow.

m_holographicSpace = winrt::Windows::Graphics::Holographic::HolographicSpace::CreateForCoreWindow(window);

リモートアプリに接続するConnect to the remote app

プレーヤーアプリがコンテンツを表示できる状態になったら、リモートアプリへの接続を確立できます。Once the player app is ready for rendering content a connection to the remote app can be established.

接続は、次のいずれかの方法で確立できます。The connection can be established in one of the following ways:

  1. HoloLens 2 で実行されているプレーヤーアプリは、リモートアプリに接続します。The player app running on HoloLens 2 connects to the remote app.
  2. リモートアプリは、HoloLens 2 で実行されているプレーヤーアプリに接続します。The remote app connects to the player app running on HoloLens 2.

プレーヤーアプリからリモートアプリに接続するには、 Connect ホスト名とポートを指定して、プレーヤーのコンテキストでメソッドを呼び出します。To connect from the player app to the remote app call the Connect method on the player context specifying the hostname and port. 既定のポートは 8265 です。The default port is 8265.

try
{
    m_playerContext.Connect(m_hostname, m_port);
}
catch(winrt::hresult_error& e)
{
    // Failed to connect. Get an error details via e.code() and e.message()
}

重要

C++/WinRT API と同様に、 Connect 処理する必要がある winrt:: hresult_error をスローすることがあります。As with any C++/WinRT API Connect might throw an winrt::hresult_error which needs to be handled.

プレーヤーアプリで着信接続をリッスンするには、メソッドを呼び出し Listen ます。Listening for incoming connections on the player app can be done by calling the Listen method. この呼び出しでは、ハンドシェイクポートとトランスポートポートの両方を指定できます。Both the handshake port and transport port can be specified during this call. ハンドシェイクポートは、初期ハンドシェイクに使用されます。The handshake port is used for the initial handshake. データは、トランスポートポートを介して送信されます。The data is then send over the transport port. 既定では、ポート番号 82658266 が使用されます。By default port number 8265 and 8266 are used.

try
{
    m_playerContext.Listen(L"0.0.0.0", m_port, m_port + 1);
}
catch(winrt::hresult_error& e)
{
    // Failed to listen. Get an error details via e.code() and e.message()
}

は、 PlayerContext 接続の状態を監視するために3つのイベントを公開します。The PlayerContext exposes three events to monitor the state of the connection

  1. OnConnected: リモートアプリへの接続が正常に確立されたときにトリガーされます。OnConnected: Triggered when a connection to the remote app has been successfully established.
m_onConnectedEventToken = m_playerContext.OnConnected([]() 
{
    // Handle connection successfully established
});
  1. OnDisconnected: 確立された接続が終了した場合、または接続を確立できなかった場合にトリガーされます。OnDisconnected: Triggered if an established connection is terminated or a connection could not be established.
m_onDisconnectedEventToken = m_playerContext.OnDisconnected([](ConnectionFailureReason failureReason)
{
    switch (failureReason)
    {
        // Handle connection failed or terminated.
        // See ConnectionFailureReason for possible reasons.
    }
}

注意

指定できる ConnectionFailureReason 値は、ファイルに記載されてい Microsoft.Holographic.AppRemoting.idl fileます。Possible ConnectionFailureReason values are documented in the Microsoft.Holographic.AppRemoting.idl file.

  1. OnListening: 受信接続のリッスンが開始されます。OnListening: When listening for incoming connections starts.
m_onListeningEventToken = m_playerContext.OnListening([]()
{
    // Handle start listening for incoming connections
});

さらに、プレーヤーのコンテキストでプロパティを使用して接続状態を照会することもでき ConnectionState ます。Additionally the connection state can be queried using the ConnectionState property on the player context.

winrt::Microsoft::Holographic::AppRemoting::ConnectionState state = m_playerContext.ConnectionState();

リモートで描画されたフレームを表示するDisplay the remotely rendered frame

リモートでレンダリングされるコンテンツを表示するには、 PlayerContext::BlitRemoteFrame HolographicFrameのレンダリング中にを呼び出します。To display the remotely rendered content, call PlayerContext::BlitRemoteFrame while rendering a HolographicFrame.

BlitRemoteFrame 現在の HolographicFrame のバックバッファーがレンダーターゲットとしてバインドされている必要があります。BlitRemoteFrame requires that the back buffer for the current HolographicFrame is bound as render target. バックバッファーは、 Direct3D11BackBufferプロパティを介してHolographicCameraRenderingParametersから受け取ることができます。The back buffer can be received from the HolographicCameraRenderingParameters via the Direct3D11BackBuffer property.

呼び出されると、 BlitRemoteFrame リモートアプリケーションから最後に受信したフレームを HolographicFrame の BackBuffer にコピーします。When called, BlitRemoteFrame copies the latest received frame from the remote application into the BackBuffer of the HolographicFrame. さらに、リモートアプリケーションがリモートフレームのレンダリング中にフォーカスポイントを指定している場合は、フォーカスポイントが設定されます。Additionally the focus point set is set, if the remote application has specified a focus point during the rendering of the remote frame.

// Blit the remote frame into the backbuffer for the HolographicFrame.
winrt::Microsoft::Holographic::AppRemoting::BlitResult result = m_playerContext.BlitRemoteFrame();

注意

PlayerContext::BlitRemoteFrame 現在のフレームのフォーカスポイントを上書きする可能性があります。PlayerContext::BlitRemoteFrame potentially overwrites the focus point for the current frame.

成功した場合、は BlitRemoteFrame を返し BlitResult::Success_Color ます。On success, BlitRemoteFrame returns BlitResult::Success_Color. それ以外の場合は、エラーの理由を返します。Otherwise it returns the failure reason:

  • BlitResult::Failed_NoRemoteFrameAvailable: 使用可能なリモートフレームがないため、失敗しました。BlitResult::Failed_NoRemoteFrameAvailable: Failed because no remote frame is available.
  • BlitResult::Failed_NoCamera: カメラが存在しないために失敗しました。BlitResult::Failed_NoCamera: Failed because no camera present.
  • BlitResult::Failed_RemoteFrameTooOld: リモートフレームが古すぎるため失敗しました (PlayerContext:: BlitRemoteFrameTimeout プロパティを参照してください)。BlitResult::Failed_RemoteFrameTooOld: Failed because remote frame is too old (see PlayerContext::BlitRemoteFrameTimeout property).

重要

バージョン 2.1.0 以降では、カスタムプレーヤーが Holographic リモート処理を介して深さの再投影を使用できるようになります。Starting with version 2.1.0 it is possible with a custom player to use depth reprojection via Holographic Remoting.

BlitResultBlitResult::Success_Color_Depth 、次の条件下でもを返すことができます。BlitResult can also return BlitResult::Success_Color_Depth under the following conditions:

  • リモートアプリは、HolographicCameraRenderingParameters を使用して深度バッファーをコミットしました。 CommitDirect3D11DepthBufferThe remote app has committed a depth buffer via HolographicCameraRenderingParameters.CommitDirect3D11DepthBuffer.
  • カスタムプレーヤーアプリは、を呼び出す前に有効な深度バッファーをバインドしました BlitRemoteFrameThe custom player app has bound a valid depth buffer before calling BlitRemoteFrame.

これらの条件が満たされる BlitRemoteFrame と、リモートの深さが現在バインドされているローカルの深度バッファーに array.blit ます。If these conditions are met BlitRemoteFrame will blit the remote depth into the currently bound local depth buffer. その後、リモートでレンダリングされるコンテンツとの深さが交差する追加のローカルコンテンツをレンダリングできます。You can then render additional local content which will have depth intersection with the remote rendered content. さらに、カスタムプレーヤーで HolographicCameraRenderingParameters を使用してローカル深度バッファーをコミットし、リモートおよびローカルでレンダリングされるコンテンツの深さを再予測することもできます。Additionally you can commit the local depth buffer via HolographicCameraRenderingParameters.CommitDirect3D11DepthBuffer in your custom player to have depth reprojection for remote and local rendered content. 詳細については、「 深度 Reprojection 」を参照してください。See Depth Reprojection for details.

プロジェクション変換モードProjection Transform Mode

Holographic リモート処理を介して深度再プロジェクションを使用しているときに表示される問題の1つは、カスタムプレーヤーアプリによって直接レンダリングされるローカルコンテンツとは別のプロジェクション変換を使用して、リモートコンテンツをレンダリングできることです。One problem which surfaces when using depth reprojection via Holographic Remoting is that the remote content can be rendered with a different projection transform than local content directly rendered by your custom player app. 一般的なユースケースでは、プレーヤー側とリモート側で ( HolographicCamera:: SetNearPlaneDistanceHolographicCamera:: SetFarPlaneDistanceを使用して) 近距離および遠平面に対して異なる値を指定します。A common use-case is to specify different values for near and far plane (via HolographicCamera::SetNearPlaneDistance and HolographicCamera::SetFarPlaneDistance) on the player side and the remote side. この場合、プレーヤー側の射影変換に、リモートの近距離距離と遠距離の距離またはローカルの距離が反映されている必要があるかどうかは明確ではありません。In this case it's not clear if the projection transform on the player side should reflect the remote near/far plane distances or the local ones.

バージョン 2.1.0 以降では、を使用して投影変換モードを制御でき PlayerContext::ProjectionTransformConfig ます。Starting with version 2.1.0 you can control the projection transform mode via PlayerContext::ProjectionTransformConfig. サポートされる値は次のとおりです。Supported values are:

  • Local - HolographicCameraPose::P rojectiontransform は、HolographicCamera 上のカスタムプレーヤーアプリによって設定された近距離/遠平面距離を反映する射影変換を返します。Local - HolographicCameraPose::ProjectionTransform returns a projection transform which reflects the near/far plane distances set by your custom player app on the HolographicCamera.
  • Remote -射影変換は、リモートアプリによって指定された近距離距離と遠距離を反映します。Remote - Projection transform reflects the near/far plane distances specified by the remote app.
  • Merged -リモートアプリとカスタムプレーヤーアプリとの間の距離が近い場合は、統合されます。Merged - Near/Far plane distances from your remote app and your custom player app are merged. 既定では、これを行うには、近距離距離の最小値と、遠くの平面距離の最大値を取得します。By default this is done by taking the minimum of the near plane distances and the maximum of the far plane distances. リモート側またはローカル側のどちらか一方が反転している場合は、遠く < 近くにあるとしても、遠くと遠くに離れた距離の距離が反転します。In case either the remote or local side are inverted, say far < near, the remote near/far plane distances are flipped.

省略可能: Set BlitRemoteFrameTimeout Optional: Set BlitRemoteFrameTimeout

重要

PlayerContext::BlitRemoteFrameTimeout は、バージョン 2.0.9以降でサポートされています。PlayerContext::BlitRemoteFrameTimeout is supported starting with version 2.0.9.

プロパティは、 PlayerContext::BlitRemoteFrameTimeout 新しいリモートフレームが受信されなかった場合に、リモートフレームが再利用される時間を指定します。The PlayerContext::BlitRemoteFrameTimeout property specifies the amount of time a remote frame is reused if no new remote frame is received.

一般的なユースケースでは、一定の時間、新しいフレームが受信されなかった場合に、BlitRemoteFrame timeout で空の画面が表示されるようにします。A common use-case is to enable the BlitRemoteFrame timeout to display a blank screen if no new frames are received for a certain amount of time. 有効にすると、メソッドの戻り値の型を使用して、 BlitRemoteFrame ローカルに表示されるフォールバックコンテンツに切り替えることもできます。When enabled the return type of the BlitRemoteFrame method can also be used to switch to a locally rendered fallback content.

タイムアウトを有効にするには、プロパティ値を100ミリ秒以上の期間に設定します。To enable the timeout, set the property value to a duration equal or greater than 100ms. タイムアウトを無効にするには、プロパティをゼロ期間に設定します。To disable the timeout, set the property to zero duration. タイムアウトが有効になっていて、set duration のリモートフレームが受信されなかった場合、BlitRemoteFrame は失敗し、 Failed_RemoteFrameTooOld 新しいリモートフレームが受信されるまで戻ります。If the timeout is enabled and no remote frame is received for the set duration, BlitRemoteFrame will fail and return Failed_RemoteFrameTooOld until a new remote frame is received.

using namespace std::chrono_literals;

// Set the BlitRemoteFrame timeout to 0.5s
m_playerContext.BlitRemoteFrameTimeout(500ms);

省略可能: 最後のリモートフレームに関する統計を取得するOptional: Get statistics about the last remote frame

パフォーマンスまたはネットワークの問題を診断するために、プロパティを使用して最後のリモートフレームに関する統計を取得でき PlayerContext::LastFrameStatistics ます。To diagnose performance or network issues, statistics about the last remote frame can be retrieved via the PlayerContext::LastFrameStatistics property. 統計は HolographicFrame::Pの呼び出し中に更新されます。 current予測。Statistics are updated during the call to HolographicFrame::PresentUsingCurrentPrediction.

// Get statistics for the last presented frame.
winrt::Microsoft::Holographic::AppRemoting::PlayerFrameStatistics statistics = m_playerContext.LastFrameStatistics();

詳細については、ファイルのドキュメントを参照してください PlayerFrameStatistics Microsoft.Holographic.AppRemoting.idl fileFor more details, see the PlayerFrameStatistics documentation in the Microsoft.Holographic.AppRemoting.idl file.

省略可能: カスタムデータチャネルOptional: Custom data channels

カスタムデータチャネルは、既に確立されているリモート処理接続を介してユーザーデータを送信するために使用できます。Custom data channels can be used to send user data over the already established remoting connection. 詳細については、「 カスタムデータチャネル 」を参照してください。See custom data channels for more information.

参照See Also