OpenXR API'sini kullanarak Holographic Remoting uzak uygulaması yazma

Holographic Remoting'i yeni kullandıysanız, genel bakış sayfamızı okumak istiyor olabiliriz.

Önemli

Bu belgede, OpenXR API'sini kullanarak HoloLens 2 ve Windows Mixed Reality için uzak uygulamanın oluşturulması açıkmektedir. HoloLens (1. nesil) için uzak uygulamalar, NuGet 1.x.xsürümünü kullan gerekir. Bu, HoloLens 2 için yazılan uzak uygulamaların HoloLens 1 ile uyumlu olmadığını gösterir. 1. HoloLens belgeleri burada bulunabilir.

Holographic Remoting uygulamaları, uzaktan işlenen içeriklerin akışını HoloLens 2'ye Windows Mixed Reality ve çevreleyici başlığın içine sızabilir. Ayrıca daha fazla sistem kaynağına erişebilirsiniz ve uzak çevreleyici görünümleri mevcut masaüstü bilgisayar yazılımıyla tümleştirebilirsiniz. Uzak uygulama, HoloLens 2'den bir giriş veri akışı alır, içeriği sanal çevreleyici bir görünümde işler ve içerik çerçevelerini HoloLens 2'ye akışla alır. Bağlantı standart Wi-Fi kullanılarak yapılır. Holographic Remoting, bir masaüstü uygulamasına veya UWP uygulamasına bir NuGet eklenir. Bağlantıyı işleyici ve çevreleyici bir görünümde işleyici ek kod gerekir. Tipik bir iletişim bağlantısı 50 ms'ye kadar düşük gecikme süresine sahip olur. Oynatıcı uygulaması gecikme süresini gerçek zamanlı olarak bildirebilirsiniz.

Bu sayfada ve çalışan projelerde yer alan tüm kodlara Holographic Remoting örnekleri github deposundan bulabilirsiniz.

Önkoşullar

İyi bir başlangıç noktası, çalışan bir OpenXR tabanlı Masaüstü veya UWP uygulamasıdır. Ayrıntılar için bkz. OpenXR ile çalışmaya başlama.

Önemli

Holographic Remoting kullanan herhangi bir uygulama, çok iş parçacıklı bir ev kullanmak üzere yazıldır. Tek iş parçacıklı bir dairenin kullanımı desteklene, ancak en iyi performansın altında performansa ve büyük olasılıkla kayıttan yürütme sırasında kekemeliklere neden olur. C++/WinRT winrt::init_apartment çok iş parçacıklı bir kanal kullanılırken varsayılan değerdir.

Holographic Remoting NuGet paketini al

Aşağıdaki adımlar, NuGet paketini Visual Studio.

  1. Projeyi Visual Studio'da açın.
  2. Proje düğümüne sağ tıklayın ve Paketleri Yönet... NuGet seçin
  3. Görüntülenen panelde Gözat'ı seçin ve ardından "Holographic Remoting" (Holographic Remoting) ifadesini arayın.
  4. Microsoft.Holographic.Remoting.OpenXr'ıseçin, ardından en son 2.x.x sürümünün seçildiğinden emin olun ve yükle'yi seçin.
  5. Önizleme iletişim kutusu görüntülenirse Tamam'ı seçin.
  6. Lisans sözleşmesi iletişim kutusu açılırken Kabul Ediyorum'a seçin.
  7. 3 ile 6 arasında adımları şu NuGet tekrarlayın: OpenXR.Headers, OpenXR.Loader

Not

NuGet paketinin 1.x.x sürümü, HoloLens 1'i hedeflemek isteyen geliştiriciler tarafından kullanılabilir. Ayrıntılar için bkz. Holographic Remoting ekleme (HoloLens (1. nesil)).

Holographic Remoting OpenXR çalışma zamanı seçin

Uzak uygulamanıza ilk olarak Microsoft.Holographic.Remoting.OpenXr depolama paketinin bir parçası olan Holographic Remoting OpenXR çalışma NuGet gerekir. Bunu yapmak için ortam değişkenini XR_RUNTIME_JSON uygulama içindeki RemotingXR.json dosyasının yoluna ayarlarsınız. Bu ortam değişkeni OpenXR yükleyicisi tarafından sistem varsayılan OpenXR çalışma zamanının kullanılmayacağı, bunun yerine Holographic Remoting OpenXR çalışma zamanının yeniden yönlendirilmesi için kullanılır. Microsoft.Holographic.Remoting.OpenXr NuGet paketini kullanırken RemotingXR.json dosyası derleme sırasında çıkış klasörüne otomatik olarak kopyalanır; OpenXR çalışma zamanı seçimi genellikle aşağıdaki gibi görünür.

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

Holographic Remoting Uzantısı ile XrInstance oluşturma

Tipik bir OpenXR uygulamasının ilk olarak OpenXR uzantılarını seçmesi ve bir XrInstance oluşturması gerekir. OpenXR çekirdek belirtimi, herhangi bir özel API'ye yönelik bir ifade sağlamaz. Bu nedenle Holographic Remoting, adlı kendi OpenXR uzantısını XR_MSFT_holographic_remoting tanıtıyor. XR_MSFT_HOLOGRAPHIC_REMOTING_EXTENSION_NAMExrCreateInstance çağrısının XrInstanceCreateInfo dosyasına dahil olduğundan emin olur.

İpucu

Varsayılan olarak, uygulamanın işlenmiş içeriği yalnızca bir HoloLens 2'de veya Windows Mixed Reality başlığında çalışan Holographic Remoting oynatıcıya akışla Windows Mixed Reality olur. İşlenmiş içeriği uzak bilgisayarda, örneğin bir pencerenin takas zinciri aracılığıyla görüntülemek için Holographic Remoting adlı ikinci bir OpenXR uzantısı XR_MSFT_holographic_remoting_frame_mirroring sağlar. Bu işlevi kullanmak istemeniz durumunda bu uzantıyı kullanarak XR_MSFT_HOLOGRAPHIC_REMOTING_FRAME_MIRRORING_EXTENSION_NAME da etkinleştirin.

Önemli

Holographic Remoting OpenXR uzantısı API'si hakkında bilgi edinmek için Holographic Remotingörnekleri github deposunda bulunan belirtime göz atın.

Bağlan için

Uzak uygulamanız XrInstance'ı oluşturduktan ve xrGetSystem aracılığıyla XrSystemId'i sorguladikten sonra oynatıcı cihazına bir bağlantı oluşturulabilir.

Uyarı

Holographic Remoting OpenXR çalışma zamanı, bağlantı kurulduktan sonra yalnızca yapılandırmaları görüntüleme veya ortam karışımı modları gibi cihaza özgü verileri sağlayabiliyor. xrEnumerateViewConfigurations, , , ve size, tam olarak bağlanmadan önce HoloLens 2'de çalışan bir oynatıcıya bağlanırsanız normalde elde edersiniz varsayılan xrEnumerateViewConfigurationViewsxrGetViewConfigurationProperties değerleri xrEnumerateEnvironmentBlendModesxrGetSystemProperties verir. Bağlantı kurulmadan önce bu yöntemleri çağırmamanız önemle önerilir. Öneri, XrSession başarıyla oluşturulduktan ve oturum durumu en azından XR_SESSION_STATE_READY.

Maksimum bit hızı, ses etkin, video codec'i veya derinlik arabellek akışı çözünürlüğü gibi genel özellikler aşağıdaki gibi xrRemotingSetContextPropertiesMSFT yalıtabilirsiniz.

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

Bağlantı iki şekilde yapılabilir.

  1. Uzak uygulama, cihazda çalışan oynatıcıya bağlanır.
  2. Cihazda çalışan oynatıcı uzak uygulamaya bağlanır.

Uzak uygulama ile oynatıcı cihazı arasında bağlantı kurmak için yapı aracılığıyla konak adını ve bağlantı noktasını xrRemotingConnectMSFT belirten yöntemini XrRemotingConnectInfoMSFT arayın. Holographic Remoting Player tarafından kullanılan bağlantı noktası 8265'tir.

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

Uzak uygulamada gelen bağlantıları dinleme yöntemi çağrılarak xrRemotingListenMSFT yapılabilir. Hem el sıkışma bağlantı noktası hem de taşıma bağlantı noktası yapı aracılığıyla XrRemotingListenInfoMSFT belirtilebilir. İlk el sıkışma için el sıkışma bağlantı noktası kullanılır. Veriler daha sonra taşıma bağlantı noktası üzerinden gönderilir. Varsayılan olarak 8265 ve 8266 kullanılır.

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

veya çağrısı sırasında bağlantı durumunun bağlantısının kesilmiş xrRemotingConnectMSFT olması xrRemotingListenMSFT gerekir. Bir XrInstance oluşturduktan ve aracılığıyla XrSystemId için sorgu kullandıktan sonra herhangi bir noktada bağlantı durumunu elde xrRemotingGetConnectionStateMSFT edin.

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

Kullanılabilir bağlantı durumları:

  • XR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT
  • XR_REMOTING_CONNECTION_STATE_CONNECTING_MSFT
  • XR_REMOTING_CONNECTION_STATE_CONNECTED_MSFT

Önemli

xrRemotingConnectMSFT veya xrRemotingListenMSFT xrCreateSession aracılığıyla bir XrSession oluşturmadan önce çağrılmalı. Bağlantı durumu oturum oluşturma işlemi başarılı olurken XrSession oluşturma işlemi yapmaya çalışsanız da oturum durumu hemen XR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT XR_SESSION_STATE_LOSS_PENDING.

Holographic Remoting'in xrCreateSession uygulaması, bağlantının kurulmasını beklemeyi destekler. çağrısı veya hemen ardından çağrısı abilirsiniz. Bu çağrı, bağlantıyı xrRemotingConnectMSFTxrRemotingListenMSFT engeller ve bağlantı kurulmasını bekler. Zaman aşımı 10 saniyeye sabittir. Bu süre içinde bir bağlantı kurulacaksa XrSession oluşturma işlemi başarılı olur ve oturum durumu XR_SESSION_STATE_READY. Bağlantı kurulamayabilirsiniz, ancak oturum oluşturma işlemi de başarılı olur ancak hemen XR_SESSION_STATE_LOSS_PENDING.

Genel olarak, bağlantı durumu XrSession durumuyla bir çifttir. Bağlantı durumuna yapılan tüm değişiklikler oturum durumunu da etkiler. Örneğin, bağlantı durumu oturum durumuna geçiş olursa, bağlantı durumu da XR_REMOTING_CONNECTION_STATE_CONNECTED_MSFTXR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT XR_SESSION_STATE_LOSS_PENDING olur.

Belirli olaylarımoting ile işleme

Holographic Remoting OpenXR çalışma zamanı, bağlantının durumunu izlemek için önemli olan üç olay gösterir.

  1. XR_TYPE_REMOTING_EVENT_DATA_CONNECTED_MSFT: Cihazla bağlantı başarıyla kuruldu mu tetiklenir.
  2. XR_TYPE_REMOTING_EVENT_DATA_DISCONNECTED_MSFT: Kurulan bir bağlantı kapatılırsa veya bağlantı kurulamasa tetiklenir.
  3. XR_TYPE_REMOTING_EVENT_DATA_LISTENING_MSFT: Gelen bağlantıları dinlerken başlar.

Bu olaylar bir kuyruğa yerleştirilir ve uzak uygulamanın aracılığıyla düzenli olarak kuyruktan okuması xrPollEvent gerekir.

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

Akışlı içeriği yerel olarak önizleme

Uzak uygulamada cihaza gönderilen içeriğin aynısını görüntülemek için XR_MSFT_holographic_remoting_frame_mirroring uzantı kullanılabilir. Bu uzantıyla, XrFrameEndInfo'ya zincirlenmiş olmayan dokuyu kullanarak XrRemotingFrameMirrorImageInfoMSFT xrEndFrame'e aşağıdaki gibi doku gönderebilirsiniz.

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

Yukarıdaki örnekte bir DX11 değiştirme zinciri dokusu kullanılır ve xrEndFrame çağrısının hemen ardından pencereyi gösterir. Kullanım, zincir dokularını değiştirmekle kısıtlanmamıştır. Ayrıca ek GPU eşitlemesi gerekmez. Kullanım ve kısıtlamalar hakkında ayrıntılı bilgi için uzantı belirtimlerini kontrol edin. Uzak uygulamanız DX12 kullanıyorsa XrRemotingFrameMirrorImageD3D12MSFT yerine XrRemotingFrameMirrorImageD3D11MSFT kullanın.

İsteğe bağlı: Özel veri kanalları

sürüm 2.5.0'danbaşlayarak, önceden kurulmuş bir iletişim bağlantısı üzerinden kullanıcı verilerini göndermek için OpenXR API'si ile özel veri kanalları kullanılabilir. Daha fazla bilgi için bkz. OpenXR API ile Özel Veri Kanalları.

İsteğe bağlı: Konuşma

sürüm 2.6.0'danbaşlayarak uzantı, uzak uygulamanın OpenXR API ile oynatıcı uygulaması tarafından algılanan konuşma komutlarına tepki vermesini sağlar.

[! ÖNEMLİ] Ayrıntılı belirtim, Holographic Remoting örnekleri github deposunda bulunabilir.

Oynatıcı uygulamasında bir konuşma tanıyıcı başlatmak için uzak uygulama çağrısında xrInitializeRemotingSpeechMSFT olabilir. Bu çağrı, dil, tümcecik sözlüğü ve dil bilgisi dosyasının içeriklerinden oluşan konuşma başlatma parametrelerini oynatıcı uygulamasına iletir.

Not

Sürüm 2.6.1'den önce konuşma tanıyıcının başına yalnızca bir kez başlatılması gerekir.

Olayda da olduğu gibi konuşma tanıyıcının oluşturulması başarılı olursa, oynatıcı uygulamasında bir konuşma tanıma sonucu üretmesi durumunda uzak uygulama XR_TYPE_EVENT_DATA_REMOTING_SPEECH_RECOGNIZER_STATE_CHANGED_MSFT size bildirilecek. Oynatıcı tarafındaki konuşma tanıyıcının durumu değişirse olay XrEventDataRemotingSpeechRecognizerStateChangedMSFT yapısı olay kuyruğuna yerleştirilir.

XrRemotingSpeechRecognizerStateMSFT , oynatıcı tarafında konuşma tanıyıcının tüm olası durumları tanımlar ve oynatıcı tarafındaki konuşma tanıyıcı tanınan bir tümcecik varsa olay yapısı XrEventDataRemotingSpeechRecognizedMSFT olay kuyruğuna yerleştirilir. Uzak uygulama tanınan bir tümcecik hakkında bilgi edindikten sonra çağrısıyla tanınan tümceciği xrRetrieveRemotingSpeechRecognizedTextMSFT alabilir.

Not

, Konuşma Tanıma API'si tarafından konuşma tanıma sonucuyla döndürülen XrRemotingSpeechRecognitionConfidenceMSFTXrRemotingSpeechRecognitionConfidenceMSFT enum'un Windows eşlemedir.

İsteğe bağlı: Sistem Eşitlemesini Koordine Etmek

sürüm 2.7.0'danbaşlayarak, oynatıcı ile uzak uygulama arasındaki uzamsal verileri hizalamak için koordinat sistemi eşitlemesi kullanılabilir. Daha fazla bilgi için bkz. Holographic Remoting ile Sistem Eşitlemesini Koordine Etmek için Genel Bakış.

Ayrıca Bkz.