使用 HolographicSpace API 编写全息远程处理远程应用

如果你刚接触全息远程处理,可能需要阅读我们的概述

重要

本文档介绍如何使用 HolographicSpace API 创建适用于 HoloLens 2 远程应用程序。 适用于 “HoloLens(第一代)”的远程应用程序必须使用 NuGet 包版本 “1.xx”。这意味着,为 HoloLens 2 编写的远程应用程序与 HoloLens 1 不兼容,反之亦然。 可在此处找到关于 HoloLens 1 的文档。

全息远程处理应用可将远程呈现的内容流式传输到 HoloLens 2 和 Windows Mixed Reality 沉浸式头戴显示设备。 你还可以访问更多系统资源,并将远程沉浸式视图集成到现有的台式电脑软件中。 远程应用从 HoloLens 2 接收输入数据流,在虚拟沉浸式视图中呈现内容,并将内容帧流式传输回 HoloLens 2。 连接是使用标准的 Wi-Fi 建立的。 全息远程处理通过 NuGet 包添加到桌面或 UWP 应用。 需要使用额外的代码来处理连接,并在沉浸式视图中进行呈现。 典型的远程连接会有低至 50 毫秒的延迟。 播放器应用可以实时报告延迟。

本页上的所有代码和工作项目都可以在全息远程处理示例 github 存储库中找到。

先决条件

一个很好的起点是面向 Windows Mixed Reality API 的基于 DirectX 的桌面或 UWP 应用。 有关详细信息,请参阅 DirectX 开发概述C++ 全息项目模板是一个很好的起点。

重要

应将任何使用全息远程处理的应用编写成使用多线程单元。 支持使用单线程单元,但这会导致性能欠佳,并可能在播放过程中出现卡顿。 使用 C++/WinRT winrt::init_apartment 时,多线程单元是默认设置。

获取全息远程处理 NuGet 包

若要在 Visual Studio 中将 NuGet 包添加到某个项目,需要执行以下步骤。

  1. 在 Visual Studio 中打开项目。
  2. 右键单击项目节点,然后选择“管理 NuGet 包...”
  3. 在出现的面板中选择“浏览”,然后搜索“全息远程处理”。
  4. 选择“Microsoft.Holographic.Remoting”,确保选择最新的 2.x.x 版本,然后选择“安装”。
  5. 如果出现了“预览”对话框,请选择“确定”。
  6. 弹出许可协议对话框时,请选择“我接受”。

注意

1.xx 版本的 NuGet 包仍然可供要将 HoloLens 1 作为目标的开发人员使用。 有关详细信息,请参阅添加 Holographic Remoting(HoloLens(第一代))

创建远程上下文

首先,应用程序应创建一个远程上下文。

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

...

private:
    // RemoteContext used to connect with a Holographic Remoting player and display rendered frames
    winrt::Microsoft::Holographic::AppRemoting::RemoteContext m_remoteContext = nullptr;
// class implementation
#include <HolographicAppRemoting\Streamer.h>

...

CreateRemoteContext(m_remoteContext, 20000, false, PreferredVideoCodec::Default);

警告

Holographic Remoting 的工作原理是将用作 Windows 一部分的 Windows Mixed Reality 运行时替换为远程处理特定的运行时。 此操作是在创建远程上下文期间完成的。 因此,在创建远程上下文之前对任何 Windows Mixed Reality API 进行任何调用都可能导致意外行为。 建议的方法是在与任何混合现实 API 交互之前尽早创建远程上下文。 切勿将在调用 CreateRemoteContext 之前通过任何 Windows Mixed Reality API 创建或检索的对象与之后创建或检索的对象混合使用。

接下来需要创建全息空间。 不需要指定 CoreWindow。 没有 CoreWindow 的桌面应用只能传递 nullptr

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

连接到设备

当远程应用准备好呈现内容时,可与播放器设备建立连接。

可通过以下两种方式之一进行连接。

  1. 远程应用连接到设备上运行的播放器。
  2. 在设备上运行的播放器连接到远程应用。

若要建立从远程应用到播放器设备的连接,请在指定主机名和端口的远程上下文中调用 Connect 方法。 Holographic Remoting 播放器使用的端口是 8265。

try
{
    m_remoteContext.Connect(m_hostname, m_port);
}
catch(winrt::hresult_error& e)
{
    DebugLog(L"Connect failed with hr = 0x%08X", e.code());
}

重要

与任何 C++/WinRT API 一样,Connect 可能会引发需要处理的 winrt::hresult_error。

提示

若要避免使用 C++/WinRT 语言投影,可以包含位于 Holographic Remoting NuGet 包中的文件 build\native\include\<windows sdk version>\abi\Microsoft.Holographic.AppRemoting.h。 该文件包含底层 COM 接口的声明。 不过,建议使用 C++/WinRT。

可以通过调用 Listen 方法来侦听远程应用上的传入连接。 在进行这种调用期间,可以指定握手端口和传输端口。 握手端口用于初始握手。 然后,数据将通过传输端口发送。 默认使用 “8265” 和 “8266”。

try
{
    m_remoteContext.Listen(L"0.0.0.0", m_port, m_port + 1);
}
catch(winrt::hresult_error& e)
{
    DebugLog(L"Listen failed with hr = 0x%08X", e.code());
}

重要

NuGet 包中的 build\native\include\HolographicAppRemoting\Microsoft.Holographic.AppRemoting.idl 包含 Holographic Remoting 公开的 API 的详细文档。

处理远程处理特定的事件

远程上下文公开三个事件,这些事件对于监视连接状态非常重要。

  1. OnConnected:与设备成功建立连接时触发。
winrt::weak_ref<winrt::Microsoft::Holographic::AppRemoting::IRemoteContext> remoteContextWeakRef = m_remoteContext;

m_onConnectedEventRevoker = m_remoteContext.OnConnected(winrt::auto_revoke, [this, remoteContextWeakRef]() {
    if (auto remoteContext = remoteContextWeakRef.get())
    {
        // Update UI state
    }
});
  1. OnDisconnected:建立的连接关闭或无法建立连接时触发。
m_onDisconnectedEventRevoker =
    m_remoteContext.OnDisconnected(winrt::auto_revoke, [this, remoteContextWeakRef](ConnectionFailureReason failureReason) {
        if (auto remoteContext = remoteContextWeakRef.get())
        {
            DebugLog(L"Disconnected with reason %d", failureReason);
            // Update UI

            // Reconnect if this is a transient failure.
            if (failureReason == ConnectionFailureReason::HandshakeUnreachable ||
                failureReason == ConnectionFailureReason::TransportUnreachable ||
                failureReason == ConnectionFailureReason::ConnectionLost)
            {
                DebugLog(L"Reconnecting...");

                ConnectOrListen();
            }
            // Failure reason None indicates a normal disconnect.
            else if (failureReason != ConnectionFailureReason::None)
            {
                DebugLog(L"Disconnected with unrecoverable error, not attempting to reconnect.");
            }
        }
    });
  1. OnListening:开始侦听传入连接时触发。
m_onListeningEventRevoker = m_remoteContext.OnListening(winrt::auto_revoke, [this, remoteContextWeakRef]() {
    if (auto remoteContext = remoteContextWeakRef.get())
    {
        // Update UI state
    }
});

此外,可以使用远程上下文中的 ConnectionState 属性查询连接状态。

auto connectionState = m_remoteContext.ConnectionState();

处理语音事件

借助远程语音接口,可以使用 HoloLens 2 注册语音触发器并将其远程处理到远程应用程序。

跟踪远程语音的状态需要以下额外成员:

winrt::Microsoft::Holographic::AppRemoting::IRemoteSpeech::OnRecognizedSpeech_revoker m_onRecognizedSpeechRevoker;

首先检索远程语音接口。

if (auto remoteSpeech = m_remoteContext.GetRemoteSpeech())
{
    InitializeSpeechAsync(remoteSpeech, m_onRecognizedSpeechRevoker, weak_from_this());
}

然后可以使用异步帮助器方法初始化远程语音。 应以异步方式完成此操作,因为初始化可能需要相当长的时间。 使用 C++/WinRT 执行并发和异步操作介绍了如何使用 C++/WinRT 编写异步函数。

winrt::Windows::Foundation::IAsyncOperation<winrt::Windows::Storage::StorageFile> LoadGrammarFileAsync()
{
    const wchar_t* speechGrammarFile = L"SpeechGrammar.xml";
    auto rootFolder = winrt::Windows::ApplicationModel::Package::Current().InstalledLocation();
    return rootFolder.GetFileAsync(speechGrammarFile);
}

winrt::fire_and_forget InitializeSpeechAsync(
    winrt::Microsoft::Holographic::AppRemoting::IRemoteSpeech remoteSpeech,
    winrt::Microsoft::Holographic::AppRemoting::IRemoteSpeech::OnRecognizedSpeech_revoker& onRecognizedSpeechRevoker,
    std::weak_ptr<SampleRemoteMain> sampleRemoteMainWeak)
{
    onRecognizedSpeechRevoker = remoteSpeech.OnRecognizedSpeech(
        winrt::auto_revoke, [sampleRemoteMainWeak](const winrt::Microsoft::Holographic::AppRemoting::RecognizedSpeech& recognizedSpeech) {
            if (auto sampleRemoteMain = sampleRemoteMainWeak.lock())
            {
                sampleRemoteMain->OnRecognizedSpeech(recognizedSpeech.RecognizedText);
            }
        });

    auto grammarFile = co_await LoadGrammarFileAsync();

    std::vector<winrt::hstring> dictionary;
    dictionary.push_back(L"Red");
    dictionary.push_back(L"Blue");
    dictionary.push_back(L"Green");
    dictionary.push_back(L"Default");
    dictionary.push_back(L"Aquamarine");

    remoteSpeech.ApplyParameters(L"", grammarFile, dictionary);
}

可通过两种方式指定要识别的短语。

  1. 语音语法 xml 文件中的规范。 有关详细信息,请参阅如何创建基本的 XML 语法
  2. 通过在字典向量中将其传递给 ApplyParameters 来指定。

在 OnRecognizedSpeech 回调中可以处理语音事件:

void SampleRemoteMain::OnRecognizedSpeech(const winrt::hstring& recognizedText)
{
    bool changedColor = false;
    DirectX::XMFLOAT4 color = {1, 1, 1, 1};

    if (recognizedText == L"Red")
    {
        color = {1, 0, 0, 1};
        changedColor = true;
    }
    else if (recognizedText == L"Blue")
    {
        color = {0, 0, 1, 1};
        changedColor = true;
    }
    else if (recognizedText == L"Green")
    {
        ...
    }

    ...
}

在本地预览流式传输内容

若要在远程应用中显示发送到设备的相同内容,可以使用远程上下文的 OnSendFrame 事件。 每当 Holographic Remoting 库将当前帧发送到远程设备时,都会触发 OnSendFrame 事件。 这是提取内容并将其位块传送 (blit) 到桌面或 UWP 窗口的理想时间。

#include <windows.graphics.directx.direct3d11.interop.h>

...

m_onSendFrameEventRevoker = m_remoteContext.OnSendFrame(
    winrt::auto_revoke, [this](const winrt::Windows::Graphics::DirectX::Direct3D11::IDirect3DSurface& texture) {
        winrt::com_ptr<ID3D11Texture2D> texturePtr;
        {
            winrt::com_ptr<ID3D11Resource> resource;
            winrt::com_ptr<::IInspectable> inspectable = texture.as<::IInspectable>();
            winrt::com_ptr<Windows::Graphics::DirectX::Direct3D11::IDirect3DDxgiInterfaceAccess> dxgiInterfaceAccess;
            winrt::check_hresult(inspectable->QueryInterface(__uuidof(dxgiInterfaceAccess), dxgiInterfaceAccess.put_void()));
            winrt::check_hresult(dxgiInterfaceAccess->GetInterface(__uuidof(resource), resource.put_void()));
            resource.as(texturePtr);
        }

        // Copy / blit texturePtr into the back buffer here.
    });

深度重新投影

从版本 2.1.0 开始,Holographic Remoting 支持深度重新投影。 这需要将颜色缓冲区和深度缓冲区从远程应用程序流式传输到 HoloLens 2。 默认情况下,深度缓冲区流式传输已启用,并配置为使用颜色缓冲区的一半分辨率。 可按如下所示更改此配置:

// class implementation
#include <HolographicAppRemoting\Streamer.h>

...

CreateRemoteContext(m_remoteContext, 20000, false, PreferredVideoCodec::Default);

// Configure for half-resolution depth.
m_remoteContext.ConfigureDepthVideoStream(DepthBufferStreamResolution::Half_Resolution);

请注意,如果不应使用默认值,则必须在与 HoloLens 2 建立连接之前调用 ConfigureDepthVideoStream。 最佳时机是在创建远程上下文之后。 DepthBufferStreamResolution 的可能值为:

  • Full_Resolution
  • Half_Resolution
  • Quarter_Resolution
  • Disabled(已在版本 2.1.3 中添加,如果使用此值,则不会创建额外的深度视频流)

请记住,使用全分辨率深度缓冲区也会影响带宽要求,需要考虑到提供给 CreateRemoteContext 的最大带宽值。

除了配置分辨率之外,还必须通过 HolographicCameraRenderingParameters.CommitDirect3D11DepthBuffer 提交深度缓冲区。


void SampleRemoteMain::Render(HolographicFrame holographicFrame)
{
    ...

    m_deviceResources->UseHolographicCameraResources([this, holographicFrame](auto& cameraResourceMap) {
        
        ...

        for (auto cameraPose : prediction.CameraPoses())
        {
            DXHelper::CameraResources* pCameraResources = cameraResourceMap[cameraPose.HolographicCamera().Id()].get();

            ...

            m_deviceResources->UseD3DDeviceContext([&](ID3D11DeviceContext3* context) {
                
                ...

                // Commit depth buffer if available and enabled.
                if (m_canCommitDirect3D11DepthBuffer && m_commitDirect3D11DepthBuffer)
                {
                    auto interopSurface = pCameraResources->GetDepthStencilTextureInteropObject();
                    HolographicCameraRenderingParameters renderingParameters = holographicFrame.GetRenderingParameters(cameraPose);
                    renderingParameters.CommitDirect3D11DepthBuffer(interopSurface);
                }
            });
        }
    });
}

若要验证深度重新投影是否在 HoloLens 2 上正常工作,可以通过设备门户启用深度可视化工具。 有关详细信息,请参阅验证是否正确设置了深度

可选:自定义数据通道

使用自定义数据通道可以通过已建立的远程连接发送用户数据。 有关详细信息,请参阅自定义数据通道

可选:坐标系同步

从版本 2.7.0 开始,坐标系同步可用于对齐播放器与远程应用程序之间的空间数据。 有关详细信息,请参阅 Holographic Remoting 概述中的“坐标系同步”

另请参阅