Távoli holografikus távoli alkalmazás írása az OpenXR API használatával

Ha még csak most szeretné elhozni a Holographic Remotingot, olvassa el az áttekintést.

Fontos

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

A holografikus távelérésű alkalmazások távolról renderelt tartalmakat streamelnek HoloLens 2. Windows Mixed Reality modern headsetek segítségével. Emellett több rendszererőforrást is elérheti, és távoli modern nézeteket integrálhat a meglévő asztali PC-szoftverekbe. A távoli alkalmazások bemeneti adatfolyamot kapnak a 2. HoloLens-től, egy virtuális modern nézetben renderelik a tartalmat, és a tartalomkereteket a 2. HoloLens streamelik. A kapcsolat a standard Wi-Fi használatával létesítve. A Holographic Remoting egy NuGet-csomaggal van hozzáadva egy asztali vagy UWP-alkalmazáshoz. További kódra van szükség, amely kezeli a kapcsolatot, és egy modern nézetben jelenik meg. Egy tipikus elotolási kapcsolat akár 50 ms késéssel is rendelkezik. A lejátszóalkalmazás valós időben képes jelenteni a késést.

Az oldalon található összes kód és munkaprojekt megtalálható a Holographic Remoting minta github-adattárában.

Előfeltételek

Jó kiindulási pont lehet egy működő OpenXR-alapú asztali vagy UWP-alkalmazás. Részletekért lásd: Ismerkedés az OpenXR-sel.

Fontos

A Holographic Remotingot használó alkalmazásokat többszálas rendszer használatára kell használni. Az egyszálas tokok használata támogatott, de az optimálisnál nem optimális teljesítményt eredményez, és a lejátszás során akár meg is akad. C++/WinRT winrt::init_apartment az alapértelmezett többszálas rendszer.

A Holographic remoting NuGet-csomag lekért része

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

  1. Nyissa meg a projektet a Visual Studióban.
  2. Kattintson a jobb gombbal a projektcsomópontra, és válassza a Manage NuGet Packages... (NuGet-csomagok kezelése... lehetőséget)
  3. A megjelenő panelen válassza a Tallózás lehetőséget, majd keressen a "Holographic Remoting" kifejezésre.
  4. Válassza a Microsoft.Holographic.Remoting.OpenXrlehetőséget, majd győződjön meg arról, hogy a legújabb 2.x.x verzió van kiválasztva, majd válassza az Install (Telepítés) lehetőséget.
  5. Ha megjelenik az Előnézet párbeszédpanel, kattintson az OK gombra.
  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-csomagokkal: OpenXR.Headers, OpenXR.Loader

Megjegyzés

A NuGet-csomag 1.x.x verziója továbbra is elérhető az 1-es verzióra HoloLens fejlesztők számára. Részletekért lásd: Holographic Remoting (HoloLens (1. generációs)).

Válassza ki a Holographic Remoting OpenXR-runtime-t

A távoli alkalmazásban az első lépés a Holographic Remoting OpenXR-runtime kiválasztása, amely a Microsoft.Holographic.Remoting.OpenXr NuGet-csomag része. Ehhez a környezeti változót az alkalmazásban található XR_RUNTIME_JSON RemotingXR.json fájl elérési útjára kell beírni. Ezt a környezeti változót az OpenXR betöltője arra használja, hogy ne a rendszer alapértelmezett OpenXR-futásidejű környezetét használja, hanem irányítsa át a Holographic Remoting OpenXR-runtime-hoz. A Microsoft.Holographic.Remoting.OpenXr NuGet-csomag használata esetén a Rendszer automatikusan átmásolja a RemotingXR.json fájlt a kimeneti mappába való fordítás során, az OpenXR-futtatás 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ítvekkel

A tipikus OpenXR-alkalmazások első lépései az OpenXR-bővítmények kiválasztása és egy XrInstance létrehozása. Az OpenXR alapspecifikációja nem biztosít lekért API-t. Emiatt a Holographic Remoting bevezeti a saját, nevű OpenXR-bővítményét. XR_MSFT_holographic_remoting Győződjön meg arról, hogy XR_MSFT_HOLOGRAPHIC_REMOTING_EXTENSION_NAME az xrCreateInstance hívás XrInstanceCreateInfo része.

Tipp

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

Fontos

A Holographic Remoting OpenXR extension API-val kapcsolatos további információkért tekintse meg a Holographic Remoting minta github-adattárában található specifikációt.

Csatlakozás az eszközhöz

Miután a távoli alkalmazás létrehozta az XrInstance-et, és lekérdezte az XrSystemId-t az xrGetSystem használatával, létrejön a kapcsolat a lejátszóeszközhöz.

Figyelmeztetés

A Holographic Remoting OpenXR-runtime csak a kapcsolat létrejötte után képes eszközspecifikus adatokat szolgáltatni, például nézetkonfigurációkat vagy környezeti kevert módokat. xrEnumerateViewConfigurationsA , , , és alapértelmezett értékeket ad meg, amelyek megegyezikek a 2. HoloLens-ben futó lejátszóhoz való csatlakozáskor jellemzően használt xrEnumerateViewConfigurationViewsxrGetViewConfigurationPropertiesxrEnumerateEnvironmentBlendModes értékekkel, mielőtt teljesen csatlakoztatva xrGetSystemProperties lenne. Erősen ajánlott, hogy ne hívja meg ezeket a metódusokat a kapcsolat létrejötte előtt. A javaslat ezeket a metódusokat használja az XrSession sikeres létrehozása és a munkamenet-állapot legalább XR_SESSION_STATE_READY.

Az olyan általános tulajdonságok, mint a maximális bitszám, a hang engedélyezése, a videokodek vagy a mélységi pufferstreamfeloldás a következőképpen xrRemotingSetContextPropertiesMSFT konfigurálhatóak.

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 létesíthet kapcsolatot.

  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 létesíteni a távoli alkalmazás és a lejátszóeszköz között, hívja meg a metódust, amely az állomásnevet és a portot adja meg xrRemotingConnectMSFT a XrRemotingConnectInfoMSFT struktúrán keresztül. A Holographic Remoting Player által használt port a 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 hívásával xrRemotingListenMSFT történik. A kézfogási portot és az átviteli portot is meg lehet adni a XrRemotingListenInfoMSFT struktúrával. A kézfogási port a kezdeti kézfogáshoz használatos. Az adatokat ezután a rendszer a szállítási porton keresztül küldi el. Alapértelmezés szerint a rendszer a 8265-ös és a 8266-os értéket használja.

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 vagy a hívása esetén a kapcsolati állapotot le kell xrRemotingConnectMSFTxrRemotingListenMSFT bontani. A kapcsolat állapotát bármikor lekérdezheti, miután létrehozott egy XrInstance-et, és lekérdezte az XrSystemId-ről a következőn xrRemotingGetConnectionStateMSFT keresztül: .

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

Az elérhető kapcsolati államok a következőek:

  • 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ívva, mielőtt XrSession-t próbál létrehozni az xrCreateSession segítségével. Ha XrSession-t próbál létrehozni, miközben a kapcsolati állapot a munkamenet létrehozása, a munkamenet-állapot azonban azonnal átvált XR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT XR_SESSION_STATE_LOSS_PENDING.

A Holographic Remoting implementációja támogatja a kapcsolat xrCreateSession létesítésre való várakozást. A hívását vagy azonnali hívását követően letilthatja a kapcsolatot, és megvárhatja xrRemotingConnectMSFTxrRemotingListenMSFT a kapcsolat létrejöttét. Az időtúllépés 10 másodpercre van rögzítve. Ha a kapcsolat ezen idő alatt létrejön, az XrSession létrehozása sikeres lesz, és a munkamenet-állapot át fog XR_SESSION_STATE_READY. Ha nem lehet kapcsolatot létesíteni, a munkamenet létrehozása szintén sikeres, de azonnal átvált XR_SESSION_STATE_LOSS_PENDING.

A kapcsolat állapota általában az XrSession-állapottal van párban. A kapcsolat állapotának bármilyen módosítása hatással van a munkamenet állapotára is. Ha például a kapcsolat állapota a munkamenet-állapotról a munkamenet-állapotra vált, akkor XR_SESSION_STATE_LOSS_PENDING XR_REMOTING_CONNECTION_STATE_CONNECTED_MSFTXR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT állapotra.

Adott események eltolásának kezelése

A Holographic Remoting OpenXR-runtime három eseményt fed fel, amelyek fontosak a kapcsolat állapotának figyelése során.

  1. XR_TYPE_REMOTING_EVENT_DATA_CONNECTED_MSFT: Akkor aktiválódik, ha sikeresen létrejött a kapcsolat az eszközzel.
  2. XR_TYPE_REMOTING_EVENT_DATA_DISCONNECTED_MSFT: Akkor aktiválódik, ha egy létrehozott kapcsolat be van zárva, vagy nem sikerült létrehozni a kapcsolatot.
  3. XR_TYPE_REMOTING_EVENT_DATA_LISTENING_MSFT: A bejövő kapcsolatok figyelése elindul.

Ezek az események egy üzenetsorba kerülnek, és a távoli alkalmazásnak rendszeresen olvasnia kell az üzenetsorból a xrPollEvent használatával.

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

Streamelési tartalom helyi előnézete

Ha ugyanazt a tartalmat jeleníti meg a távoli alkalmazásban, amely az eszközre van küldve, XR_MSFT_holographic_remoting_frame_mirroring a bővítmény használható. Ezzel a bővítővel egy textúra beküldhet az xrEndFrame-be a használatával, amely nincs az XrRemotingFrameMirrorImageInfoMSFT XrFrameEndInfo-hoz láncolva 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úra alapján mutatja be az ablakot közvetlenül az xrEndFrame hívása után. A használat nem korlátozódik a láncok textúracseréire. Emellett 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, az XrRemotingFrameMirrorImageD3D12MSFT használhatja az XrRemotingFrameMirrorImageD3D11MSFT helyett.

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

A 2.5.0-sverziótól kezdődően az OpenXR API-val egyéni adatcsatornák használhatók a felhasználói adatok a már létrehozott kapcsolaton keresztüli küldhetők. További információ: Egyéni adatcsatornák az OpenXR API-val.

Nem kötelező: Beszéd

A 2.6.0-sverziótól kezdve a 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édparancsokra.

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

A lejátszóalkalmazásban a beszédfelismerő inicializálására a távoli alkalmazás a következőt hívhatja: xrInitializeRemotingSpeechMSFT . Ez a hívás továbbítja a beszéd inicializálási paramétereit, amelyek egy nyelvből, egy kifejezésekből álló szó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 minden alkalommal csak egyszer kell inicializálni.

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

XrRemotingSpeechRecognizerStateMSFT A meghatározza a beszédfelismerő összes lehetséges államát a lejátszó oldalán, és az eseménystruktúra az eseménysorba kerül, ha a lejátszó oldalán lévő beszédfelismerő XrEventDataRemotingSpeechRecognizedMSFT felismert kifejezéssel rendelkezik. Miután a távoli alkalmazás értesítést kap egy felismert kifejezésről, a hívással lekérheti a felismert xrRetrieveRemotingSpeechRecognizedTextMSFT kifejezést.

Megjegyzés

A XrRemotingSpeechRecognitionConfidenceMSFT a XrRemotingSpeechRecognitionConfidenceMSFT enum közvetlen leképezése, amelyet a Windows Speech Recognition API által visszaadott beszédfelismerési eredményekkel ad vissza.

Nem kötelező: Rendszerszinkronizálás koordinálása

A 2.7.0-sverziójától kezdődően a koordinátarendszer-szinkronizálással a térbeli adatok igazíthatóak a lejátszó és a távoli alkalmazás között. További információ: A rendszerszinkronizálás koordinálása holografikus elotolással – áttekintés.

Lásd még: