Holographic Remoting Remote alkalmazás írása az OpenXR API használatával

  • Cikk

Ha még nem ismerkedik a Holographic Remoting használatával, érdemes elolvasnia az áttekintést.

Fontos

Ez a dokumentum egy távoli alkalmazás létrehozását ismerteti HoloLens 2 és Windows Mixed Reality headsetekhez az OpenXR API használatával. A HoloLens távoli alkalmazásainak (1. generációs)NuGet-csomag 1.x.x-es verzióját kell használniuk. Ez azt jelenti, hogy a HoloLens 2 írt távoli alkalmazások nem kompatibilisek a HoloLens 1-zel, és fordítva. A HoloLens 1 dokumentációja itt található.

A Holographic Remoting-alkalmazások távolról renderelt tartalmakat streamelhetnek HoloLens 2 és Windows Mixed Reality magával ragadó fejhallgatókba. Emellett több rendszererőforrást is elérhet, és távoli , modern nézeteket integrálhat a meglévő asztali pc-szoftverekbe. A távoli alkalmazások bemeneti adatstreamet kapnak HoloLens 2, virtuális, modern nézetben renderelik a tartalmat, és a tartalomkereteket visszaküldik HoloLens 2. A kapcsolat standard Wi-Fi-vel jön létre. A holografikus remoting nuGet-csomagon keresztül kerül egy asztali vagy UWP-alkalmazásba. További kódra van szükség, amely kezeli a kapcsolatot, és magával ragadó nézetben jelenik meg. Egy tipikus újraegyenlítési kapcsolat 50 ms késéssel fog rendelkezni. A lejátszóalkalmazás valós időben jelentheti a késést.

Ezen a lapon és a munkaprojektekben található összes kód megtalálható a Holographic Remoting samples github-adattárban.

Előfeltételek

Jó kiindulópont egy működő OpenXR-alapú asztali vagy UWP-alkalmazás. További információ: Az OpenXR használatának első lépései.

Fontos

A Holographic Remotingot használó alkalmazásokat többszálú lakás használatához kell létrehozni. Az egyszálas lakás használata támogatott, de a lejátszás során az optimálisnál rosszabb teljesítményhez és esetleg akadozáshoz vezet. A C++/WinRT winrt::init_apartment használata esetén a többszálas apartman az alapértelmezett.

A Holographic Remoting NuGet-csomag lekérése

A NuGet-csomag Visual Studióban való hozzáadásához a következő lépések szükségesek.

  1. Nyissa meg a projektet a Visual Studióban.
  2. Kattintson a jobb gombbal a projektcsomópontra, és válassza a NuGet-csomagok kezelése... lehetőséget.
  3. A megjelenő panelen válassza a Tallózás lehetőséget, majd keressen rá a "Holographic Remoting" kifejezésre.
  4. Válassza a Microsoft.Holographic.Remoting.OpenXr lehetőséget, majd győződjön meg arról, hogy a legújabb 2.x.x verzió van kiválasztva, majd válassza a Telepítés lehetőséget.
  5. Ha megjelenik az Előnézet párbeszédpanel, válassza az OK gombot.
  6. Válassza az Elfogadom lehetőséget, amikor megjelenik a licencszerződés párbeszédpanel.
  7. Ismételje meg a 3–6. lépést a következő NuGet-csomagok esetében: OpenXR.Headers, OpenXR.Loader

Megjegyzés

A NuGet-csomag 1.x.x-es verziója továbbra is elérhető a HoloLens 1-et megcélzó fejlesztők számára. További információ: HoloLens hozzáadása (1. generációs).

Válassza ki a Holographic Remoting OpenXR-futtatókörnyezetet

A távoli alkalmazásban első lépésként válassza ki a Holographic Remoting OpenXR futtatókörnyezetet, amely a Microsoft.Holographic.Remoting.OpenXr NuGet csomag része. Ezt úgy teheti meg, hogy a XR_RUNTIME_JSON környezeti változót az alkalmazásban található RemotingXR.json fájl elérési útjára állítja. Ezt a környezeti változót az OpenXR-betöltő arra használja, hogy ne a rendszer alapértelmezett OpenXR-futtatókörnyezetét használja, hanem irányítsa át a Holographic Remoting OpenXR-futtatókörnyezetre. A Microsoft.Holographic.Remoting.OpenXr NuGet csomag használatakor a Rendszer automatikusan átmásolja a RemotingXR.json fájlt a kimeneti mappába történő fordítás során, az OpenXR-futtatókörnyezet kiválasztása általában a következőképpen néz ki.

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;
}

XrInstance létrehozása Holographic Remoting bővítménysel

Egy tipikus OpenXR-alkalmazás első művelete az OpenXR-bővítmények kiválasztása és egy XrInstance létrehozása. Az OpenXR magspecifikációja nem biztosít semmilyen remoting specifikus API-t. Ezért a Holographic Remoting saját OpenXR-bővítményt vezet be.XR_MSFT_holographic_remoting Győződjön meg arról, hogy XR_MSFT_HOLOGRAPHIC_REMOTING_EXTENSION_NAME szerepel az xrCreateInstance hívás XrInstanceCreateInfo elemében.

Tipp

Alapértelmezés szerint az alkalmazás renderelt tartalma csak a Holographic Remoting lejátszóba kerül, amely HoloLens 2 vagy Windows Mixed Reality headseten fut. A renderelt tartalom távoli pc-n való megjelenítéséhez például egy ablak felcserélési láncán keresztül a Holographic Remoting egy második OpenXR-bővítményt XR_MSFT_holographic_remoting_frame_mirroringis biztosít. Győződjön meg arról, hogy ezt a bővítményt is XR_MSFT_HOLOGRAPHIC_REMOTING_FRAME_MIRRORING_EXTENSION_NAME engedélyezni szeretné arra az esetre, ha használni szeretné ezt a funkciót.

Fontos

A Holographic Remoting OpenXR bővítmény API-val kapcsolatos információkért tekintse meg a Holographic Remoting samples github-adattárban található specifikációt.

Csatlakozás az eszközhöz

Miután a távoli alkalmazás létrehozta az XrInstance-t, és lekérdezte az XrSystemId-et az xrGetSystem-en keresztül, létre lehet hozni egy kapcsolatot a lejátszóeszközrel.

Figyelmeztetés

A Holographic Remoting OpenXR-futtatókörnyezet csak eszközspecifikus adatokat tud megadni, például a konfigurációk megtekintését vagy a környezet keverési módjait a kapcsolat létrejötte után. xrEnumerateViewConfigurations, xrEnumerateViewConfigurationViews, xrGetViewConfigurationProperties, , xrEnumerateEnvironmentBlendModesés xrGetSystemProperties alapértelmezett értékeket ad meg, amelyek megegyeznek azzal, amit általában kap, ha egy HoloLens 2 futó játékoshoz csatlakozik, mielőtt teljesen csatlakozna. Erősen ajánlott, hogy a kapcsolat létrehozása előtt ne hívja meg ezeket a metódusokat. A rendszer ezeket a metódusokat használja az XrSession sikeres létrehozása után, és a munkamenet állapota legalább XR_SESSION_STATE_READY.

Az alábbi módon konfigurálhatók xrRemotingSetContextPropertiesMSFT olyan általános tulajdonságok, mint a maximális sávszélesség, a hangalapú, a videokodek vagy a mélységi puffer streamfeloldása.

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);

A kapcsolat kétféleképpen végezhető el.

  1. A távoli alkalmazás csatlakozik az eszközön futó lejátszóhoz.
  2. Az eszközön futó lejátszó csatlakozik a távoli alkalmazáshoz.

Ha kapcsolatot szeretne létesíteni a távoli alkalmazás és a lejátszóeszköz között, hívja meg a xrRemotingConnectMSFT gazdanevet és a portot a XrRemotingConnectInfoMSFT struktúrán keresztül megadó metódust. A Holographic Remoting Player által használt port 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);

A távoli alkalmazás bejövő kapcsolatainak figyelése a metódus meghívásával xrRemotingListenMSFT végezhető el. A kézfogási port és az átviteli port is megadható a XrRemotingListenInfoMSFT szerkezeten keresztül. A kézfogási port a kezdeti kézfogáshoz használatos. Az adatok ezután az átviteli porton keresztül lesznek elküldve. Alapértelmezés szerint a 8265 és a 8266 van használatban.

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);

A kapcsolati állapotot le kell választani a híváskor vagy xrRemotingListenMSFTa híváskorxrRemotingConnectMSFT. A kapcsolat állapotát bármikor lekérheti, miután létrehozott egy XrInstance-t, és lekérdezte az XrSystemId-et a használatával xrRemotingGetConnectionStateMSFT.

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

A rendelkezésre álló kapcsolati állapotok a következők:

  • XR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT
  • XR_REMOTING_CONNECTION_STATE_CONNECTING_MSFT
  • XR_REMOTING_CONNECTION_STATE_CONNECTED_MSFT

Fontos

xrRemotingConnectMSFT vagy xrRemotingListenMSFT meg kell hívni, mielőtt XrSessiont próbálna létrehozni az xrCreateSession használatával. Ha XrSessiont próbál létrehozni, miközben a kapcsolati állapot XR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT a munkamenet létrehozása sikeres lesz, de a munkamenet állapota azonnal XR_SESSION_STATE_LOSS_PENDING lesz.

A Holographic Remoting implementációja támogatja xrCreateSession a kapcsolat létrehozását. Meghívhatja xrRemotingConnectMSFT vagy xrRemotingListenMSFT azonnal követheti a hívását xrCreateSession, amely letiltja és megvárja a kapcsolat létrejöttét. Az időtúllépés xrRemotingConnectMSFT 10 másodpercre van rögzítve, és korlátlan a használatával xrRemotingListenMSFT. Ha ez idő alatt létre lehet hozni egy kapcsolatot, az XrSession létrehozása sikeres lesz, és a munkamenet állapota XR_SESSION_STATE_READY lesz. Ha nem hozható létre kapcsolat, a munkamenet létrehozása is sikeres lesz, de azonnal áttér XR_SESSION_STATE_LOSS_PENDING.

A kapcsolat állapota általában az XrSession állapottal párosul. A kapcsolati állapot bármilyen módosítása a munkamenet állapotát is befolyásolja. Ha például a kapcsolati állapot a munkamenet állapotára XR_REMOTING_CONNECTION_STATE_CONNECTED_MSFTXR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT vált, akkor a XR_SESSION_STATE_LOSS_PENDING is át fog váltani.

Adott események újraegyenlítésének kezelése

A Holographic Remoting OpenXR-futtatókörnyezet három eseményt tesz elérhetővé, amelyek fontosak a kapcsolat állapotának monitorozásához.

  1. XR_TYPE_REMOTING_EVENT_DATA_CONNECTED_MSFT: Akkor aktiválódik, ha sikerült kapcsolatot létesíteni az eszközzel.
  2. XR_TYPE_REMOTING_EVENT_DATA_DISCONNECTED_MSFT: Akkor aktiválódik, ha egy létrehozott kapcsolat lezárult, vagy nem sikerült kapcsolatot létesíteni.
  3. XR_TYPE_REMOTING_EVENT_DATA_LISTENING_MSFT: Amikor a bejövő kapcsolatokat figyeli, elindul.

Ezek az események egy üzenetsorba kerülnek, és a távoli alkalmazásnak szabályosan kell olvasnia az üzenetsorból a segítségével 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;
	}
}

Streamelt tartalom előzetes verziója helyileg

Ha ugyanazt a tartalmat szeretné megjeleníteni a távoli alkalmazásban, amelyet a rendszer az eszközre küld, használhatja a XR_MSFT_holographic_remoting_frame_mirroring bővítményt. Ezzel a kiterjesztéssel az xrEndFrame-be küldhet textúrát úgy, hogy a XrRemotingFrameMirrorImageInfoMSFT nem az XrFrameEndInfo-hoz láncolt szerkezetet használja az alábbiak szerint.

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();

A fenti példa egy DX11 felcserélési lánc textúráját használja, és közvetlenül az xrEndFrame hívása után jeleníti meg az ablakot. A használat nem korlátozódik a láncok szerkezetének felcserélésére. Továbbá nincs szükség további GPU-szinkronizálásra. A használattal és a korlátozásokkal kapcsolatos részletekért tekintse meg a bővítmény specifikációját. Ha a távoli alkalmazás DX12-t használ, használja az XrRemotingFrameMirrorImageD3D12MSFT függvényt az XrRemotingFrameMirrorImageD3D11MSFT helyett.

Nem kötelező: Egyéni adatcsatornák

A 2.5.0-s verziótól kezdődően az OpenXR API-val egyéni adatcsatornák használhatók felhasználói adatok küldésére a már létrehozott újrakapcsolódási kapcsolaton keresztül. További információ: Egyéni adatcsatornák az OpenXR API-val.

Nem kötelező: Beszédfelismerés

A 2.6.0-s verziótól kezdődően a XR_MSFT_holographic_remoting_speech bővítmény lehetővé teszi, hogy a távoli alkalmazás reagáljon a lejátszóalkalmazás által az OpenXR API-val észlelt beszédparancsra.

[! FONTOS] A részletes specifikáció a Holographic Remoting samples GitHub-adattárban található.

A lejátszóalkalmazás beszédfelismerőjének inicializálásához a távoli alkalmazás meghívhatja a következőt xrInitializeRemotingSpeechMSFT: . Ez a hívás továbbítja a beszéd inicializálási paramétereit, amelyek egy nyelvből, egy kifejezésszótárból és egy nyelvtani fájl tartalmából állnak a lejátszóalkalmazásnak.

Megjegyzés

A 2.6.1-es verzió előtt a beszédfelismerőt csak egyszer kell inicializálni.XrSession

Ha a beszédfelismerő létrehozása sikeres volt az esemény által XR_TYPE_EVENT_DATA_REMOTING_SPEECH_RECOGNIZER_STATE_CHANGED_MSFT jelzett módon, a távoli alkalmazás értesítést kap, amikor beszédfelismerési eredmény jött létre a lejátszóalkalmazásban. Az XrEventDataRemotingSpeechRecognizerStateChangedMSFT eseménystruktúra akkor kerül az eseménysorba, amikor a beszédfelismerő állapota megváltozik a játékos oldalán.

XrRemotingSpeechRecognizerStateMSFT Meghatározza a beszédfelismerő összes lehetséges állapotát a játékos oldalán, és az XrEventDataRemotingSpeechRecognizedMSFT eseménystruktúrát az eseménysorba helyezi, ha a beszédfelismerő a játékos oldalán felismert kifejezéssel rendelkezik. Miután a távoli alkalmazás értesítést kap egy felismert kifejezésről, a meghívásával xrRetrieveRemotingSpeechRecognizedTextMSFTlekérheti a felismert kifejezést.

Megjegyzés

A XrRemotingSpeechRecognitionConfidenceMSFT a SpeechRecognitionConfidence szám közvetlen leképezése, amelyet a Windows Speech Recognition API beszédfelismerési eredményével ad vissza.

Nem kötelező: A rendszerszinkronizálás koordinálása

A 2.7.0-s verziótól kezdve a koordinátarendszer-szinkronizálás használható a térbeli adatok a lejátszó és a távoli alkalmazás közötti igazítására. További információ: A rendszerszinkronizálás koordinálása holografikus újraegyenlítéssel – áttekintés.

Lásd még: