Psaní vzdálené aplikace Holographic Remoting pomocí rozhraní OpenXR API

Pokud s Holographic Remotingem ještě nejste, možná si budete chtít přečíst náš přehled.

Důležité

Tento dokument popisuje vytvoření vzdálené aplikace pro HoloLens 2 a Windows Mixed Reality náhlavních souprav pomocí rozhraní OpenXR API. Vzdálené aplikace pro HoloLens (1. generace) musí používat NuGet balíček verze 1.x.x. To znamená, že vzdálené aplikace napsané pro HoloLens 2 nejsou kompatibilní s HoloLens 1 a naopak. Dokumentaci pro HoloLens 1 najdete tady.

Aplikace holografické vzdálené komunikace mohou streamovat vzdáleně vykreslený obsah do HoloLens 2 a Windows Mixed Reality imerzivní náhlavní soupravy. Můžete také přistupovat k více systémovým prostředkům a integrovat vzdálená imerzivní zobrazení do stávajícího počítačového softwaru. Vzdálená aplikace přijímá vstupní datový proud z HoloLens 2, vykreslí obsah ve virtuálním imerzivním zobrazení a streamuje snímky obsahu zpět do HoloLens 2. Připojení se provádí pomocí standardní Wi-Fi. Holographic Remoting se přidá do desktopové aplikace nebo aplikace pro UPW prostřednictvím NuGet paketu. Vyžaduje se další kód, který zpracuje připojení a vykreslí se v imerzivním zobrazení. Typické připojení vzdálené komunikace bude mít latenci až 50 ms. Aplikace přehrávače může latenci hlásit v reálném čase.

Veškerý kód na této stránce a pracovních projektech najdete v úložišti Ukázek pro vzdálenou komunikace Holographic na GitHubu.

Požadavky

Dobrým výchozím bodem je funkční desktopová aplikace nebo aplikace pro UPW založená na OpenXR. Podrobnosti najdete v tématu Začínáme s OpenXR.

Důležité

Každá aplikace, která používá Holographic Remoting, by měla být vytvářená tak, aby s více vlákny byla. Použití jedno vláknu je podporované, ale povede k neoptimálnějšímu výkonu a možnému zahltění během přehrávání. Při použití jazyka C++/WinRT winrt::init_apartment výchozím nastavením je vícevřetězínový soubor".

Získání balíčku pro NuGet Holographic Remoting

Následující kroky jsou nutné k přidání balíčku NuGet do projektu v Visual Studio.

  1. Otevřete projekt v sadě Visual Studio.
  2. Klikněte pravým tlačítkem na uzel projektu a vyberte Spravovat NuGet balíčky...
  3. Na panelu, který se zobrazí, vyberte Procházet a vyhledejte Holographic Remoting.
  4. Vyberte Microsoft.Holographic.Remoting.OpenXr,ujistěte se, že je vybraná nejnovější verze 2.x.x, a pak vyberte Nainstalovat.
  5. Pokud se zobrazí dialogové okno Náhled, vyberte OK.
  6. Jakmile se zobrazí dialogové okno licenční smlouvy, vyberte Přijímám.
  7. Opakujte kroky 3 až 6 pro následující balíčky NuGet: OpenXR.Headers, OpenXR.Loader

Poznámka

Verze 1.x.x balíčku NuGet je stále k dispozici pro vývojáře, kteří chtějí cílit na HoloLens 1. Podrobnosti najdete v tématu Přidání holografické vzdálené komunikace (HoloLens (1. generace)).

Výběr modulu runtime OpenXR pro holographic Remoting

Prvním krokem, který musíte ve vzdálené aplikaci udělat, je vybrat modul runtime OpenXR holographic Remoting, který je součástí balíčku Microsoft.Holographic.Remoting.OpenXr NuGet. Můžete to provést nastavením proměnné prostředí na cestu k souboru XR_RUNTIME_JSON RemotingXR.json ve vaší aplikaci. Tuto proměnnou prostředí používá zavaděč OpenXR k tomu, aby nepoužíl výchozí systémový modul runtime OpenXR, ale místo toho ho přesměruje na modul runtime OpenXR pro vzdálenou komunikace Holographic. Při použití balíčku Microsoft.Holographic.Remoting.OpenXr NuGet se soubor RemotingXR.json automaticky zkopíruje během kompilace do výstupní složky, výběr modulu runtime OpenXR obvykle vypadá takto.

bool EnableRemotingXR() {
    wchar_t executablePath[MAX_PATH];
    if (GetModuleFileNameW(NULL, executablePath, ARRAYSIZE(executablePath)) == 0) {
        return false;
    }
    
    std::filesystem::path filename(executablePath);
    filename = filename.replace_filename("RemotingXR.json");

    if (std::filesystem::exists(filename)) {
        SetEnvironmentVariableW(L"XR_RUNTIME_JSON", filename.c_str());
            return true;
        }

    return false;
}

Vytvoření instance XrInstance s rozšířením holografické vzdálené komunikace

První akce, které by typická aplikace OpenXR měla provádět, jsou výběr rozšíření OpenXR a vytvoření instance XrInstance. Základní specifikace OpenXR neposkytuje žádné rozhraní API pro vzdálenou komunikace. Z tohoto důvodu holographic Remoting zavádí vlastní rozšíření OpenXR s názvem XR_MSFT_holographic_remoting . Ujistěte XR_MSFT_HOLOGRAPHIC_REMOTING_EXTENSION_NAME se, že je součástí XrInstanceCreateInfo volání xrCreateInstance.

Tip

Ve výchozím nastavení se vykreslený obsah vaší aplikace streamuje jenom do přehrávače Holographic Remoting, a to buď běží na HoloLens 2 nebo na Windows Mixed Reality náhlavních soupravách. Pokud chcete vykreslený obsah zobrazit také na vzdáleném počítači, prostřednictvím řetězce prohození například okna poskytuje Holographic Remoting druhé rozšíření OpenXR s názvem XR_MSFT_holographic_remoting_frame_mirroring . Pokud chcete tuto funkci používat, ujistěte se také, že toto rozšíření XR_MSFT_HOLOGRAPHIC_REMOTING_FRAME_MIRRORING_EXTENSION_NAME povolíte pomocí .

Důležité

Další informace o rozhraní API rozšíření OpenXR pro vzdálenou komunikace Holographic najdete ve specifikaci, kterou najdete v úložišti ukázek pro vzdálenou komunikace Holographic na GitHubu.

Připojení k zařízení

Po vytvoření instance XrInstance vzdálené aplikace a dotazování XrSystemId prostřednictvím xrGetSystem je možné navázat připojení k zařízení přehrávače.

Upozornění

Modul runtime OpenXR pro vzdálenou komunikace Holographic dokáže poskytovat data specifická pro zařízení, jako jsou konfigurace zobrazení nebo režimy prolnutí prostředí, až po narušení připojení. xrEnumerateViewConfigurations, , , a vám před úplným připojením poskytne výchozí hodnoty odpovídající tomu, co byste obvykle měli získat, pokud se připojíte k přehrávači spuštěnému xrEnumerateViewConfigurationViewsxrGetViewConfigurationProperties na HoloLens xrEnumerateEnvironmentBlendModesxrGetSystemProperties 2. Důrazně doporučujeme tyto metody nevolejte, než se načtou připojení. Návrh se používá tyto metody po úspěšném vytvoření relace XrSession a stav relace je alespoň XR_SESSION_STATE_READY.

Obecné vlastnosti, jako je maximální přenosová rychlost, povolený zvuk, kodek videa nebo rozlišení streamu vyrovnávací paměti hloubky, je možné nakonfigurovat xrRemotingSetContextPropertiesMSFT následujícím způsobem.

XrRemotingRemoteContextPropertiesMSFT contextProperties;
contextProperties = XrRemotingRemoteContextPropertiesMSFT{static_cast<XrStructureType>(XR_TYPE_REMOTING_REMOTE_CONTEXT_PROPERTIES_MSFT)};
contextProperties.enableAudio = false;
contextProperties.maxBitrateKbps = 20000;
contextProperties.videoCodec = XR_REMOTING_VIDEO_CODEC_H265_MSFT;
contextProperties.depthBufferStreamResolution = XR_REMOTING_DEPTH_BUFFER_STREAM_RESOLUTION_HALF_MSFT;
xrRemotingSetContextPropertiesMSFT(m_instance.Get(), m_systemId, &contextProperties);

Připojení je možné provést jedním ze dvou způsobů.

  1. Vzdálená aplikace se připojí k přehrávači spuštěnému na zařízení.
  2. Přehrávač spuštěný na zařízení se připojí ke vzdálené aplikaci.

Pokud chcete navázat připojení ze vzdálené aplikace k zařízení přehrávače, zavolejte metodu určující název hostitele a xrRemotingConnectMSFT port prostřednictvím XrRemotingConnectInfoMSFT struktury. Port, který používá Holographic Remoting Player, je 8265.

XrRemotingConnectInfoMSFT connectInfo{static_cast<XrStructureType>(XR_TYPE_REMOTING_CONNECT_INFO_MSFT)};
connectInfo.remoteHostName = "192.168.x.x";
connectInfo.remotePort = 8265;
connectInfo.secureConnection = false;
xrRemotingConnectMSFT(m_instance.Get(), m_systemId, &connectInfo);

Naslouchání příchozím připojením ve vzdálené aplikaci je možné provést voláním xrRemotingListenMSFT metody . Port handshake i přenosový port je možné zadat prostřednictvím XrRemotingListenInfoMSFT struktury . Port handshake se používá pro počáteční handshake. Data se pak odesílat přes přenosový port. Ve výchozím nastavení se používají 8265 a 8266.

XrRemotingListenInfoMSFT listenInfo{static_cast<XrStructureType>(XR_TYPE_REMOTING_LISTEN_INFO_MSFT)};
listenInfo.listenInterface = "0.0.0.0";
listenInfo.handshakeListenPort = 8265;
listenInfo.transportListenPort = 8266;
listenInfo.secureConnection = false;
xrRemotingListenMSFT(m_instance.Get(), m_systemId, &listenInfo);

Stav připojení musí být odpojen při volání nebo xrRemotingConnectMSFTxrRemotingListenMSFT . Stav připojení můžete získat kdykoli po vytvoření instance XrInstance a dotazování na XrSystemId prostřednictvím xrRemotingGetConnectionStateMSFT .

XrRemotingConnectionStateMSFT connectionState;
xrRemotingGetConnectionStateMSFT(m_instance.Get(), m_systemId, &connectionState, nullptr);

Dostupné stavy připojení jsou:

  • XR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT
  • XR_REMOTING_CONNECTION_STATE_CONNECTING_MSFT
  • XR_REMOTING_CONNECTION_STATE_CONNECTED_MSFT

Důležité

xrRemotingConnectMSFT nebo xrRemotingListenMSFT musí být volána před pokusem o vytvoření relace XrSession prostřednictvím xrCreateSession. Pokud se pokusíte vytvořit relaci XrSession, zatímco stav připojení je vytvoření relace, bude úspěšné, ale stav relace se okamžitě XR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT přechází na XR_SESSION_STATE_LOSS_PENDING.

Implementace služby Holographic Remoting podporuje xrCreateSession čekání napojení připojení. Můžete volat nebo okamžitě sledovat volání , které bude xrRemotingConnectMSFT blokovat a čekat na na potvrzení xrRemotingListenMSFT připojení. Časový limit je pevně nastaven na 10 sekund. Pokud se během této doby může navázat připojení, vytvoření relace XrSession proběhne úspěšně a stav relace se přechází na XR_SESSION_STATE_READY. V případě, že není možné navázat žádné připojení, vytvoření relace je také úspěšné, ale okamžitě se přechází na XR_SESSION_STATE_LOSS_PENDING.

Obecně platí, že stav připojení je v souladu se stavem XrSession. Jakákoli změna stavu připojení má vliv také na stav relace. Pokud se například stav připojení přepne ze stavu relace do stavu relace, přechází XR_REMOTING_CONNECTION_STATE_CONNECTED_MSFTXR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT XR_SESSION_STATE_LOSS_PENDING také.

Zpracování událostí specifických pro vzdálenou komunikace

Modul runtime OpenXR pro vzdálenou komunikace Holographic zveřejňuje tři události, které jsou důležité k monitorování stavu připojení.

  1. XR_TYPE_REMOTING_EVENT_DATA_CONNECTED_MSFT: Aktivuje se, když se úspěšně na navázat připojení k zařízení.
  2. XR_TYPE_REMOTING_EVENT_DATA_DISCONNECTED_MSFT: Aktivuje se, pokud je na navázaté připojení uzavřeno nebo nelze navázat připojení.
  3. XR_TYPE_REMOTING_EVENT_DATA_LISTENING_MSFT: Při naslouchání příchozím připojením se spustí.

Tyto události se umístí do fronty a vaše vzdálená aplikace musí pravidelně číst z fronty prostřednictvím xrPollEvent .

auto pollEvent = [&](XrEventDataBuffer& eventData) -> bool {
	eventData.type = XR_TYPE_EVENT_DATA_BUFFER;
	eventData.next = nullptr;
	return CHECK_XRCMD(xrPollEvent(m_instance.Get(), &eventData)) == XR_SUCCESS;
};

XrEventDataBuffer eventData{};
while (pollEvent(eventData)) {
	switch (eventData.type) {
	
	...
	
	case XR_TYPE_REMOTING_EVENT_DATA_LISTENING_MSFT: {
		DEBUG_PRINT("Holographic Remoting: Listening on port %d",
					reinterpret_cast<const XrRemotingEventDataListeningMSFT*>(&eventData)->listeningPort);
		break;
	}
	case XR_TYPE_REMOTING_EVENT_DATA_CONNECTED_MSFT: {
		DEBUG_PRINT("Holographic Remoting: Connected.");
		break;
	}
	case XR_TYPE_REMOTING_EVENT_DATA_DISCONNECTED_MSFT: {
		DEBUG_PRINT("Holographic Remoting: Disconnected - Reason: %d",
					reinterpret_cast<const XrRemotingEventDataDisconnectedMSFT*>(&eventData)->disconnectReason);
		break;
	}
}

Náhled místně streamovaných obsahu

Pokud chcete ve vzdálené aplikaci zobrazit stejný obsah, který se odesílá do zařízení, XR_MSFT_holographic_remoting_frame_mirroring můžete použít rozšíření. S tímto rozšířením můžete odeslat texturu do xrEndFrame pomocí objektu , který není XrRemotingFrameMirrorImageInfoMSFT zřetězován s XrFrameEndInfo následujícím způsobem.

XrFrameEndInfo frameEndInfo{XR_TYPE_FRAME_END_INFO};
...

XrRemotingFrameMirrorImageD3D11MSFT mirrorImageD3D11{
    static_cast<XrStructureType>(XR_TYPE_REMOTING_FRAME_MIRROR_IMAGE_D3D11_MSFT)};
mirrorImageD3D11.texture = m_window->GetNextSwapchainTexture();

XrRemotingFrameMirrorImageInfoMSFT mirrorImageEndInfo{
    static_cast<XrStructureType>(XR_TYPE_REMOTING_FRAME_MIRROR_IMAGE_INFO_MSFT)};
mirrorImageEndInfo.image = reinterpret_cast<const XrRemotingFrameMirrorImageBaseHeaderMSFT*>(&mirrorImageD3D11);

frameEndInfo.next = &mirrorImageEndInfo;

xrEndFrame(m_session.Get(), &frameEndInfo);

m_window->PresentSwapchain();

Výše uvedený příklad používá texturu řetězce prohození DX11 a zobrazí okno ihned po volání xrEndFrame. Použití není omezené na prohození textur řetězu. Kromě toho není nutná žádná další synchronizace GPU. Podrobnosti o využití a omezeních najdete ve specifikaci rozšíření. Pokud vaše vzdálená aplikace používá DX12, místo XrRemotingFrameMirrorImageD3D12MSFT použijte XrRemotingFrameMirrorImageD3D11MSFT.

Volitelné: Vlastní datové kanály

Od verze 2.5.0je možné s rozhraním OpenXR API používat vlastní datové kanály k odesílání uživatelských dat přes již zavedené připojení vzdálené komunikace. Další informace najdete v tématu Vlastní datové kanály s rozhraním API OpenXR.

Volitelné: Řeč

Počínaje verzí 2.6.0umožňuje rozšíření vzdálené aplikaci reagovat na příkazy řeči detekované aplikací přehrávače pomocí rozhraní OpenXR API.

[! DŮLEŽITÉ] Podrobnou specifikaci najdete v úložišti GitHub s ukázkou pro vzdálenou komunikace Holographic.

Pokud chcete v aplikaci přehrávače inicializovat rozpoznávání řeči, vzdálená aplikace může volat xrInitializeRemotingSpeechMSFT . Toto volání přenese do aplikace přehrávače parametry inicializace řeči, které se skládají z jazyka, slovníku frází a obsahu souboru gramatiky.

Poznámka

Před verzí 2.6.1 se rozpoznávání řeči musí inicializovat pouze jednou pro .

Pokud bylo vytvoření rozpoznávání řeči úspěšné, jak to indikuje událost, vzdálená aplikace bude upozorněna na vygenerování výsledku rozpoznávání řeči v XR_TYPE_EVENT_DATA_REMOTING_SPEECH_RECOGNIZER_STATE_CHANGED_MSFT aplikaci přehrávače. Struktura události se umístí do fronty událostí, když se změní stav rozpoznávání řeči XrEventDataRemotingSpeechRecognizerStateChangedMSFT na straně přehrávače.

XrRemotingSpeechRecognizerStateMSFT definuje všechny možné stavy rozpoznávání řeči na straně přehrávače a struktura událostí se umístí do fronty událostí, pokud rozpoznávání řeči na straně přehrávače obsahuje rozpoznanou XrEventDataRemotingSpeechRecognizedMSFT frázi. Jakmile se vzdálená aplikace upozorní na rozpoznanou frázi, může rozpoznanou frázi načíst voláním xrRetrieveRemotingSpeechRecognizedTextMSFT .

Poznámka

je XrRemotingSpeechRecognitionConfidenceMSFT přímé mapování výčtu XrRemotingSpeechRecognitionConfidenceMSFT vráceného s výsledkem rozpoznávání řeči rozhraním API Windows rozpoznávání řeči.

Volitelné: Synchronizace souřadnic systému

Počínaje verzí 2.7.0je možné pomocí synchronizace souřadnicového systému sladit prostorová data mezi přehrávačem a vzdálenou aplikací. Další informace najdete v tématu Přehled synchronizace souřadnic systému s holografickými vzdálenou komunikacemi.

Viz také