OpenXR API'sini kullanarak Holographic Uzaktan İletişim Uzak uygulaması yazma
Holographic Remoting'i yeni kullanıyorsanız genel bakış bilgilerimizi okumak isteyebilirsiniz.
Önemli
Bu belgede, OpenXR API'sini kullanarak HoloLens 2 ve Windows Mixed Reality kulaklıklar için uzak uygulama oluşturma işlemi açıklanmaktadır. HoloLens (1. nesil) için uzak uygulamalar NuGet paketi sürüm 1.x.x kullanmalıdır. Bu, HoloLens 2 için yazılmış uzak uygulamaların HoloLens 1 ile uyumlu olmadığı anlamına gelir ve bunun tersi de geçerlidir. HoloLens 1 belgelerine buradan ulaşabilirsiniz.
Holografik Uzaktan İletişim uygulamaları, uzaktan işlenen içerikleri HoloLens 2 ve çevreleyici başlıklar Windows Mixed Reality akışla aktarabilir. Ayrıca daha fazla sistem kaynağına erişebilir ve uzak çevreleyici görünümleri mevcut masaüstü bilgisayar yazılımıyla tümleştirebilirsiniz. Uzak uygulama, HoloLens 2 giriş veri akışı alır, içeriği sanal çevreleyici bir görünümde işler ve içerik çerçevelerini HoloLens 2 geri akışla gönderir. Bağlantı, standart Wi-Fi kullanılarak yapılır. Holographic Remoting, nuget paketi aracılığıyla bir masaüstü veya UWP uygulamasına eklenir. Bağlantıyı işleyen ve çevreleyici bir görünümde işleyen ek kod gereklidir. Tipik bir uzaktan iletişim bağlantısının gecikme süresi 50 ms'ye kadar düşer. Oynatıcı uygulaması gecikme süresini gerçek zamanlı olarak bildirebilir.
Bu sayfadaki tüm kodlar ve çalışan projeler Holographic Remoting örnekleri github deposunda bulunabilir.
Ö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
Çok iş parçacıklı bir daire kullanmak için Holographic Remoting kullanan tüm uygulamalar yazılmalıdır. Tek iş parçacıklı bir dairenin kullanımı desteklenir, ancak en uygun performansın altında olmasına ve kayıttan yürütme sırasında takılmaya yol açar. C++/WinRT winrt::init_apartment kullanırken, çok iş parçacıklı bir daire varsayılandır.
Holographic Remoting NuGet paketini edinin
NuGet paketini Visual Studio'daki bir projeye eklemek için aşağıdaki adımlar gereklidir.
- Projeyi Visual Studio'da açın.
- Proje düğümüne sağ tıklayın ve NuGet Paketlerini Yönet... seçeneğini belirleyin.
- Görüntülenen panelde Gözat'ı seçin ve ardından "Holographic Remoting" araması yapın.
- Microsoft.Holographic.Remoting.OpenXr'ı seçin, ardından en son 2.x.x sürümünün seçili olduğundan emin olun ve yükle'yi seçin.
- Önizleme iletişim kutusu görüntülenirse Tamam'ı seçin.
- Lisans sözleşmesi iletişim kutusu açıldığında Kabul Ediyorum'a tıklayın.
- Aşağıdaki NuGet Paketleri için 3 ile 6 arasındaki adımları yineleyin: OpenXR.Headers, OpenXR.Loader
Not
NuGet paketinin 1.x.x sürümü, HoloLens 1'i hedeflemek isteyen geliştiriciler için hala kullanılabilir. Ayrıntılar için bkz. Holographic Remoting (HoloLens (1. nesil)) ekleme.
Holografik Uzaktan İletişim OpenXR çalışma zamanını seçin
Uzak uygulamanızda yapmanız gereken ilk adım, Microsoft.Holographic.Remoting.OpenXr NuGet paketinin bir parçası olan Holographic Remoting OpenXR çalışma zamanını seçmektir. Bunu yapmak için ortam değişkenini XR_RUNTIME_JSON uygulamanızdaki RemotingXR.json dosyasının yoluna ayarlayabilirsiniz. Bu ortam değişkeni, OpenXR yükleyicisi tarafından sistem varsayılan OpenXR çalışma zamanını kullanmak yerine Holographic Remoting OpenXR çalışma zamanına yeniden yönlendirmek 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 Uzaktan İletişim Uzantısı ile XrInstance Oluşturma
Tipik bir OpenXR uygulamasının gerçekleştirmesi gereken ilk eylemler OpenXR uzantılarını seçmek ve XrInstance oluşturmaktır. OpenXR çekirdek belirtimi belirli bir uzaktan iletişim API'sini sağlamaz. Bu nedenle Holographic Remoting adlı XR_MSFT_holographic_remotingkendi OpenXR uzantısını tanıtır. XR_MSFT_HOLOGRAPHIC_REMOTING_EXTENSION_NAME xrCreateInstance çağrısının XrInstanceCreateInfo öğesine eklendiğinden emin olun.
İpucu
Varsayılan olarak, uygulamanızın işlenmiş içeriği yalnızca HoloLens 2 veya Windows Mixed Reality kulaklıklarla çalışan Holographic Remoting oynatıcısına akışla aktarılır. İşlenen içeriği uzak bilgisayarda, örneğin bir pencerenin takas zinciri aracılığıyla görüntülemek için Holographic Remoting adlı XR_MSFT_holographic_remoting_frame_mirroringikinci bir OpenXR uzantısı sağlar. Bu işlevi kullanmak istemeniz durumunda bu uzantıyı kullanarak XR_MSFT_HOLOGRAPHIC_REMOTING_FRAME_MIRRORING_EXTENSION_NAME da etkinleştirdiğinizden emin olun.
Önemli
Holographic Remoting OpenXR uzantısı API'sini öğrenmek için Holographic Remoting örnekleri github deposunda bulunan belirtime göz atın.
Cihaza bağlanma
Uzak uygulamanız XrInstance'ı oluşturduktan ve xrGetSystem aracılığıyla XrSystemId değerini sorguladıktan sonra oynatıcı cihazla bağlantı kurulabilir.
Uyarı
Holographic Remoting OpenXR çalışma zamanı yalnızca bir bağlantı kurulduktan sonra görüntüleme yapılandırmaları veya ortam karışımı modları gibi cihaza özgü veriler sağlayabilir. xrEnumerateViewConfigurations, xrEnumerateViewConfigurationViews, xrGetViewConfigurationProperties, xrEnumerateEnvironmentBlendModesve xrGetSystemProperties size varsayılan değerler verir ve tam olarak bağlanmadan önce, HoloLens 2 üzerinde çalışan bir oyuncuya bağlanırsanız genellikle elde edeceğiniz değerlerle eşleşecektir.
Bağlantı kurulmadan önce bu yöntemleri çağırmamak kesinlikle önerilir. Öneri, XrSession başarıyla oluşturulduktan ve oturum durumu en az XR_SESSION_STATE_READY olduktan sonra bu yöntemler kullanılır.
Maksimum bit hızı, ses etkin, video codec'i veya derinlik arabelleği akış çözünürlüğü gibi genel özellikler aşağıdaki gibi yapılandırılabilir xrRemotingSetContextPropertiesMSFT .
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 yoldan biriyle yapılabilir.
- Uzak uygulama, cihazda çalışan yürütücüye bağlanır.
- Cihazda çalışan oynatıcı uzak uygulamaya bağlanır.
Uzak uygulamadan yürütücü cihaza bağlantı kurmak için konak adını ve bağlantı noktasını yapı üzerinden belirten yöntemini çağırın xrRemotingConnectMSFTXrRemotingConnectInfoMSFT . 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ı dinlemek, yöntemi çağrılarak xrRemotingListenMSFT yapılabilir. El sıkışma bağlantı noktası ve taşıma bağlantı noktası yapı üzerinden XrRemotingListenInfoMSFT belirtilebilir. El sıkışma bağlantı noktası ilk el sıkışma için kullanılır. Veriler daha sonra aktarım 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 xrRemotingListenMSFTçağrısı xrRemotingConnectMSFT yaptığınızda bağlantı durumunun bağlantısı kesilmelidir. Bağlantı durumunu bir XrInstance oluşturduktan ve aracılığıyla XrSystemId xrRemotingGetConnectionStateMSFTiçin sorguladıktan sonra alabilirsiniz.
XrRemotingConnectionStateMSFT connectionState;
xrRemotingGetConnectionStateMSFT(m_instance.Get(), m_systemId, &connectionState, nullptr);
Kullanılabilir bağlantı durumları şunlardır:
- 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 XrSession oluşturmaya çalışmadan önce çağrılmalıdır. Bağlantı durumu oturum oluşturma işlemi başarılı olur ancak oturum durumu XR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT hemen XR_SESSION_STATE_LOSS_PENDING geçiş yaparken XrSession oluşturmaya çalışırsınız.
Holographic Remoting'in uygulaması xrCreateSession , bağlantı kurulmasını beklemeyi destekler. bir xrRemotingConnectMSFT bağlantının kurulmasını xrCreateSessionengelleyecek ve xrRemotingListenMSFT bekleyecek olan çağrısının hemen ardından veya çağrısıyla gelebilirsiniz. ile xrRemotingConnectMSFT zaman aşımı 10 saniyeye ve ile xrRemotingListenMSFTsınırsız olarak sabittir. Bu süre içinde bir bağlantı kurulabiliyorsa XrSession oluşturma işlemi başarılı olur ve oturum durumu XR_SESSION_STATE_READY geçiş yapacaktır. Bağlantı kurulamıyorsa oturum oluşturma işlemi de başarılı olur ancak hemen XR_SESSION_STATE_LOSS_PENDING geçişler yapılır.
Genel olarak, bağlantı durumu XrSession durumuyla ilişkilidir. Bağlantı durumunda yapılan değişiklikler oturum durumunu da etkiler. Örneğin, bağlantı durumu oturum durumuna geçerse XR_REMOTING_CONNECTION_STATE_CONNECTED_MSFTXR_REMOTING_CONNECTION_STATE_DISCONNECTED_MSFT XR_SESSION_STATE_LOSS_PENDING de geçiş yapar.
Belirli olayları uzaktan izlemeyi işleme
Holographic Remoting OpenXR çalışma zamanı, bir bağlantının durumunu izlemek için önemli olan üç olayı kullanıma sunar.
XR_TYPE_REMOTING_EVENT_DATA_CONNECTED_MSFT: Cihazla bağlantı başarıyla kurulduğunda tetiklendi.XR_TYPE_REMOTING_EVENT_DATA_DISCONNECTED_MSFT: Kurulan bir bağlantı kapatılırsa veya bağlantı kurulamazsa tetikler.XR_TYPE_REMOTING_EVENT_DATA_LISTENING_MSFT: Gelen bağlantıları dinlerken başlar.
Bu olaylar bir kuyruğa yerleştirilir ve uzak uygulamanızın aracılığıyla xrPollEventkuyruktan düzenli olarak okuması 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ışı yapılan içeriği yerel olarak önizleme
Cihaza XR_MSFT_holographic_remoting_frame_mirroring gönderilen uzak uygulamada aynı içeriği görüntülemek için uzantı kullanılabilir. Bu uzantıyla, aşağıdaki gibi XrFrameEndInfo'ya zincirlenmemiş olan öğesini XrRemotingFrameMirrorImageInfoMSFT kullanarak xrEndFrame'e 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 DX11 takas zinciri dokusu kullanılır ve xrEndFrame çağrısından hemen sonra pencere gösterilir. Kullanım, zincir dokularını değiştirmekle sınırlı değildir. Ayrıca ek GPU eşitlemesi gerekmez. Kullanım ve kısıtlamalarla ilgili ayrıntılar için uzantı belirtimini gözden geçirin. Uzak uygulamanız DX12 kullanıyorsa XrRemotingFrameMirrorImageD3D12MSFT yerine XrRemotingFrameMirrorImageD3D11MSFT kullanın.
İsteğe bağlı: Özel veri kanalları
Sürüm 2.5.0'dan başlayarak, kullanıcı verilerini önceden oluşturulmuş uzaktan iletişim bağlantısı üzerinden göndermek için OpenXR API'siyle özel veri kanalları kullanılabilir. Daha fazla bilgi için bkz. OpenXR API'siyle Özel Veri Kanalları.
İsteğe bağlı: Konuşma
Sürüm 2.6.0'dan itibaren uzantı, XR_MSFT_holographic_remoting_speech uzak uygulamanın OpenXR API'siyle oynatıcı uygulaması tarafından algılanan konuşma komutlarına tepki vermesine olanak tanır.
[! ÖNEMLİ] Ayrıntılı belirtimHolografik Uzaktan İletişim örnekleri github deposunda bulunabilir.
Yürütücü uygulamasında bir konuşma tanıyıcı başlatmak için uzak uygulama çağrısı xrInitializeRemotingSpeechMSFTyapabilir.
Bu çağrı, bir dil, bir tümcecik sözlüğü ve dil bilgisi dosyasının içeriğinden oluşan konuşma başlatma parametrelerini oynatıcı uygulamasına iletir.
Not
2.6.1 sürümünden önce, konuşma tanıyıcısı başına XrSessionyalnızca bir kez başlatılmalıdır.
Olayda XR_TYPE_EVENT_DATA_REMOTING_SPEECH_RECOGNIZER_STATE_CHANGED_MSFT belirtildiği gibi konuşma tanıyıcısının oluşturulması başarılı olursa, yürütücü uygulamasında bir konuşma tanıma sonucu oluşturulduğunda uzak uygulamaya bildirim gönderilir.
Olay XrEventDataRemotingSpeechRecognizerStateChangedMSFT yapısı, yürütücü tarafındaki konuşma tanımanın durumu değiştiğinde olay kuyruğuna yerleştirilir.
XrRemotingSpeechRecognizerStateMSFT oyuncu tarafında konuşma tanıyıcısının tüm olası durumlarını tanımlar ve XrEventDataRemotingSpeechRecognizedMSFT oynatıcı tarafındaki konuşma tanıyıcının tanınan bir tümceciği varsa olay yapısı olay kuyruğuna yerleştirilir.
Uzak uygulamaya tanınan bir tümcecik hakkında bildirim verildikten sonra çağrılarak xrRetrieveRemotingSpeechRecognizedTextMSFTtanınan tümceciği alabilir.
Not
, XrRemotingSpeechRecognitionConfidenceMSFT Windows Konuşma Tanıma API'sinin konuşma tanıma sonucuyla döndürülen SpeechRecognitionConfidence numaralandırmasının doğrudan eşlemesidir.
İsteğe bağlı: Koordinat Sistemi Eşitleme
Sürüm 2.7.0'dan başlayarak, uzamsal verileri yürütücü ve uzak uygulama arasında hizalamak için koordinat sistemi eşitlemesi kullanılabilir. Daha fazla bilgi için bkz. Holografik Uzaktan İletişime Genel Bakış ile Sistem Eşitlemesini Koordine Etme.