Aggiungere la comunicazione remota olografica (HoloLens (First Gen))Add Holographic Remoting (HoloLens (first gen))

Importante

Questo documento descrive la creazione di un'applicazione host per HoloLens 1.This document describes the creation of a host application for HoloLens 1. L'applicazione host per HoloLens (1st Gen) deve usare il pacchetto NuGet versione 1. x. x.Host application for HoloLens (1st gen) must use NuGet package version 1.x.x. Ciò implica che le applicazioni host scritte per HoloLens 1 non sono compatibili con HoloLens 2 e viceversa.This implies that host applications written for HoloLens 1 are not compatible with HoloLens 2 and vice versa.

HoloLens 2HoloLens 2

Gli sviluppatori HoloLens che usano la comunicazione remota olografica dovranno aggiornare le proprie app per renderle compatibili con HoloLens 2.HoloLens developers using Holographic Remoting will need to update their apps to make them compatible with HoloLens 2. Questa operazione richiede una nuova versione del pacchetto NuGet di comunicazione remota olografica.This requires a new version of the Holographic Remoting NuGet package. Assicurarsi di usare la versione 2.0.0.0 o successiva del pacchetto NuGet per la comunicazione remota olografica quando ci si connette al lettore di comunicazione remota olografica in HoloLens 2. in caso contrario, la connessione non riuscirà.Be sure to use version 2.0.0.0 or above of the Holographic Remoting NuGet package when connecting to the Holographic Remoting Player on HoloLens 2 or the connection will fail.

Nota

Le linee guida specifiche per HoloLens 2 sono disponibili qui.Guidance specific to HoloLens 2 can be found here.

Aggiungere la comunicazione remota olografica all'app desktop o UWPAdd holographic remoting to your desktop or UWP app

Questa pagina descrive come aggiungere la comunicazione remota olografica a un'app desktop o UWP.This page describes how to add Holographic Remoting to a desktop or UWP app.

La comunicazione remota olografica consente all'app di avere come destinazione un HoloLens con contenuto olografico ospitato in un computer desktop o in un dispositivo UWP, ad esempio Xbox One.Holographic remoting lets your app target a HoloLens with holographic content hosted on a desktop PC or on a UWP device such as the Xbox One. È anche possibile accedere a più risorse di sistema, rendendo possibile l'integrazione di visualizzazioni immersive remote in software per PC desktop esistenti.You also have access to more system resources, making it possible to integrate remote immersive views into existing desktop PC software. Un'app host Remoting riceve un flusso di dati di input da un HoloLens, esegue il rendering del contenuto in una visualizzazione immersiva virtuale e trasmette i frame di contenuto a HoloLens.A remoting host app receives an input data stream from a HoloLens, renders content in a virtual immersive view, and streams content frames back to HoloLens. La connessione viene eseguita usando il Wi-Fi standard.The connection is made using standard Wi-Fi. Per usare la comunicazione remota, usare un pacchetto NuGet per aggiungere la comunicazione remota olografica all'app desktop o UWP, quindi scrivere il codice per gestire la connessione ed eseguire il rendering di una visualizzazione immersiva.To use remoting, use a NuGet package to add holographic remoting to your desktop or UWP app, then write code to handle the connection and render an immersive view. Le librerie helper sono incluse nell'esempio di codice che semplificano l'attività di gestione della connessione del dispositivo.Helper libraries are included in the code sample that simplify the task of handling the device connection.

Una tipica connessione remota avrà una bassa di 50 ms di latenza.A typical remoting connection will have as low as 50 ms of latency. L'App Player può segnalare la latenza in tempo reale.The player app can report the latency in real time.

Nota

I frammenti di codice in questo articolo illustrano attualmente l'uso di C++/CX anziché C + 17 conforme a C++/WinRT come usato nel modello di progetto olografico c++.The code snippets in this article currently demonstrate use of C++/CX rather than C++17-compliant C++/WinRT as used in the C++ holographic project template. I concetti sono equivalenti per un progetto C++/WinRT, anche se è necessario tradurre il codice.The concepts are equivalent for a C++/WinRT project, though you'll need to translate the code.

Ottenere i pacchetti NuGet per la comunicazione remotaGet the remoting NuGet packages

Seguire questa procedura per ottenere il pacchetto NuGet per la comunicazione remota olografica e aggiungere un riferimento dal progetto:Follow these steps to get the NuGet package for holographic remoting, and add a reference from your project:

  1. Passare al progetto in Visual Studio.Go to your project in Visual Studio.
  2. Fare clic con il pulsante destro del mouse sul nodo del progetto e scegliere Gestisci pacchetti NuGet...Right-click on the project node and select Manage NuGet Packages...
  3. Nel pannello visualizzato selecct cercare "comunicazione remota olografica".In the panel that appears, selecct Browse and then search for "Holographic Remoting".
  4. Selezionare Microsoft. olografic. Remoting e selecct Install.Select Microsoft.Holographic.Remoting and selecct Install.
  5. Se viene visualizzata la finestra di dialogo Anteprima , fare clic su OK.If the Preview dialog appears, select OK.
  6. Selezionare Accetto quando viene visualizzata la finestra di dialogo contratto di licenza.Select I Accept when the license agreement dialog appears.

Creare il HolographicStreamerHelpersCreate the HolographicStreamerHelpers

Prima di tutto, è necessario aggiungere un'istanza di HolographicStreamerHelpers alla classe che gestirà la comunicazione remota.First, we need to add an instance of HolographicStreamerHelpers to the class that will handle remoting.

#include <HolographicStreamerHelpers.h>

   private:
       Microsoft::Holographic::HolographicStreamerHelpers^ m_streamerHelpers;

Sarà inoltre necessario tenere traccia dello stato della connessione.You'll also need to track connection state. Se si desidera eseguire il rendering dell'anteprima, è necessario disporre di una trama in cui copiarla.If you want to render the preview, you need to have a texture to copy it to. Sono necessari anche alcuni elementi, ad esempio un blocco dello stato della connessione, un modo per archiviare l'indirizzo IP di HoloLens e così via.You also need a few things like a connection state lock, some way of storing the IP address of HoloLens, and so on.

private:
       Microsoft::Holographic::HolographicStreamerHelpers^ m_streamerHelpers;

       Microsoft::WRL::Wrappers::SRWLock                   m_connectionStateLock;

       RemotingHostSample::AppView^                        m_appView;
       Platform::String^                                   m_ipAddress;
       Microsoft::Holographic::HolographicStreamerHelpers^ m_streamerHelpers;

       Microsoft::WRL::Wrappers::CriticalSection           m_deviceLock;
       Microsoft::WRL::ComPtr<IDXGISwapChain1>             m_swapChain;
       Microsoft::WRL::ComPtr<ID3D11Texture2D>             m_spTexture;

Inizializzare HolographicStreamerHelpers e connettersi a HoloLensInitialize HolographicStreamerHelpers and connect to HoloLens

Per connettersi a un dispositivo HoloLens, creare un'istanza di HolographicStreamerHelpers e connettersi all'indirizzo IP di destinazione.To connect to a HoloLens device, create an instance of HolographicStreamerHelpers and connect to the target IP address. È necessario impostare la dimensione del fotogramma video in modo che corrisponda alla larghezza e all'altezza di visualizzazione HoloLens, perché la libreria remota olografica prevede che le risoluzioni del codificatore e del decodificatore corrispondano esattamente.You'll need to set the video frame size to match the HoloLens display width and height, because the Holographic Remoting library expects the encoder and decoder resolutions to match exactly.

m_streamerHelpers = ref new HolographicStreamerHelpers();
       m_streamerHelpers->CreateStreamer(m_d3dDevice);

       // We currently need to stream at 720p because that's the resolution of our remote display.
       // There is a check in the holographic streamer that makes sure the remote and local
       // resolutions match. The default streamer resolution is 1080p.
       m_streamerHelpers->SetVideoFrameSize(1280, 720);

       try
       {
           m_streamerHelpers->Connect(m_ipAddress->Data(), 8001);
       }
       catch (Platform::Exception^ ex)
       {
           DebugLog(L"Connect failed with hr = 0x%08X", ex->HResult);
       }

La connessione del dispositivo è asincrona.The device connection is asynchronous. L'app deve fornire gestori eventi per gli eventi di connessione, disconnessione e invio frame.Your app needs to provide event handlers for connect, disconnect, and frame send events.

L'evento OnConnected può aggiornare l'interfaccia utente, avviare il rendering e così via.The OnConnected event can update the UI, start rendering, and so on. Nell'esempio di codice desktop, viene aggiornato il titolo della finestra con un messaggio "Connected".In our desktop code sample, we update the window title with a "connected" message.

m_streamerHelpers->OnConnected += ref new ConnectedEvent(
           [this]()
           {
               UpdateWindowTitle();
           });

L'evento disconnected può gestire la riconnessione, gli aggiornamenti dell'interfaccia utente e così via.The OnDisconnected event can handle reconnection, UI updates, and so on. In questo esempio viene riconnessa se si verifica un errore temporaneo.In this example, we reconnect if there's a transient failure.

Platform::WeakReference streamerHelpersWeakRef = Platform::WeakReference(m_streamerHelpers);
       m_streamerHelpers->OnDisconnected += ref new DisconnectedEvent(
           [this, streamerHelpersWeakRef](_In_ HolographicStreamerConnectionFailureReason failureReason)
           {
               DebugLog(L"Disconnected with reason %d", failureReason);
               UpdateWindowTitle();

               // Reconnect if this is a transient failure.
               if (failureReason == HolographicStreamerConnectionFailureReason::Unreachable ||
                   failureReason == HolographicStreamerConnectionFailureReason::ConnectionLost)
               {
                   DebugLog(L"Reconnecting...");

                   try
                   {
                       auto helpersResolved = streamerHelpersWeakRef.Resolve<HolographicStreamerHelpers>();
                       if (helpersResolved)
                       {
                           helpersResolved->Connect(m_ipAddress->Data(), 8001);
                       }
                       else
                       {
                           DebugLog(L"Failed to reconnect because a disconnect has already occurred.\n");
                       }
                   }
                   catch (Platform::Exception^ ex)
                   {
                       DebugLog(L"Connect failed with hr = 0x%08X", ex->HResult);
                   }
               }
               else
               {
                   DebugLog(L"Disconnected with unrecoverable error, not attempting to reconnect.");
               }
           });

Quando il componente remoto è pronto per l'invio di un frame, l'app ha la possibilità di crearne una copia nella SendFrameEvent.When the remoting component is ready to send a frame, your app is provided an opportunity to make a copy of it in the SendFrameEvent. Qui viene copiato il frame in una catena di scambio in modo che sia possibile visualizzarlo in una finestra di anteprima.Here, we copy the frame to a swap chain so that we can display it in a preview window.

m_streamerHelpers->OnSendFrame += ref new SendFrameEvent(
           [this](_In_ const ComPtr<ID3D11Texture2D>& spTexture, _In_ FrameMetadata metadata)
           {
               if (m_showPreview)
               {
                   ComPtr<ID3D11Device1> spDevice = m_appView->GetDeviceResources()->GetD3DDevice();
                   ComPtr<ID3D11DeviceContext> spContext = m_appView->GetDeviceResources()->GetD3DDeviceContext();

                   ComPtr<ID3D11Texture2D> spBackBuffer;
                   ThrowIfFailed(m_swapChain->GetBuffer(0, IID_PPV_ARGS(&spBackBuffer)));

                   spContext->CopySubresourceRegion(
                       spBackBuffer.Get(), // dest
                       0,                  // dest subresource
                       0, 0, 0,            // dest x, y, z
                       spTexture.Get(),    // source
                       0,                  // source subresource
                       nullptr);           // source box, null means the entire resource

                   DXGI_PRESENT_PARAMETERS parameters = { 0 };
                   ThrowIfFailed(m_swapChain->Present1(1, 0, &parameters));
               }
           });

Rendering del contenuto olograficoRender holographic content

Per eseguire il rendering del contenuto usando la comunicazione remota, è necessario configurare un IFrameworkView virtuale all'interno dell'app desktop o UWP ed elaborare i frame olografici dalla comunicazione remota.To render content using remoting, you set up a virtual IFrameworkView within your desktop or UWP app and process holographic frames from remoting. Tutte le API olografiche di Windows vengono utilizzate allo stesso modo da questa visualizzazione, ma sono configurate in modo leggermente diverso.All of the Windows Holographic APIs are used the same way by this view, but it's set up slightly differently.

Invece di crearli autonomamente, i componenti di spazio olografico e vocale provengono dalla classe HolographicRemotingHelpers:Instead of creating them yourself, the holographic space and speech components come from your HolographicRemotingHelpers class:

m_appView->Initialize(m_streamerHelpers->HolographicSpace, m_streamerHelpers->RemoteSpeech);

Invece di usare un ciclo di aggiornamento in un metodo Run, è necessario fornire gli aggiornamenti del ciclo principale dell'app desktop o UWP.Instead of using an update loop in a Run method, you provide tick updates from the main loop of your desktop or UWP app. Ciò consente all'app desktop o UWP di rimanere in controllo dell'elaborazione dei messaggi.This allows your desktop or UWP app to remain in control of message processing.

void DesktopWindow::Tick()
   {
       auto lock = m_deviceLock.Lock();
       m_appView->Tick();

       // display preview, etc.
   }

Il metodo di sequenza () del segno di visualizzazione dell'app olografica completa un'iterazione del ciclo di aggiornamento, di estrazione e di presentazione.The holographic app view's Tick() method completes one iteration of the update, draw, present loop.

void AppView::Tick()
   {
       if (m_main)
       {
           // When running on Windows Holographic, we can use the holographic rendering system.
           HolographicFrame^ holographicFrame = m_main->Update();

           if (holographicFrame && m_main->Render(holographicFrame))
           {
               // The holographic frame has an API that presents the swap chain for each
               // holographic camera.
               m_deviceResources->Present(holographicFrame);
           }
       }
   }

Il ciclo di aggiornamento, rendering e presenza dell'app olografica è identico a quello che si verifica quando è in esecuzione in HoloLens, ad eccezione del fatto che è possibile accedere a una quantità molto maggiore di risorse di sistema nel PC desktop.The holographic app view update, render, and present loop are exactly the same as it is when running on HoloLens - except that you have access to a much greater amount of system resources on your desktop PC. È possibile eseguire il rendering di molti più triangoli, avere più passaggi di disegno, eseguire più fisica e usare processi x64 per caricare contenuti che richiedono più di 2 GB di RAM.You can render many more triangles, have more drawing passes, do more physics, and use x64 processes to load content that requires more than 2 GB of RAM.

Disconnetti e termina la sessione remotaDisconnect and end the remote session

Per disconnettersi, ad esempio, quando l'utente fa clic su un pulsante dell'interfaccia utente per disconnettere-chiamare Disconnect () in HolographicStreamerHelpers e quindi rilasciare l'oggetto.To disconnect - for example, when the user clicks a UI button to disconnect - call Disconnect() on the HolographicStreamerHelpers, and then release the object.

void DesktopWindow::DisconnectFromRemoteDevice()
   {
       // Disconnecting from the remote device can change the connection state.
       auto exclusiveLock = m_connectionStateLock.LockExclusive();

       if (m_streamerHelpers != nullptr)
       {
           m_streamerHelpers->Disconnect();

           // Reset state
           m_streamerHelpers = nullptr;
       }
   }

Ottenere il lettore di comunicazione remotaGet the remoting player

Il lettore di comunicazione remota olografica di Windows è disponibile nell'App Store di Windows come endpoint per le applicazioni host Remote a cui connettersi.The Windows Holographic remoting player is offered in the Windows app store as an endpoint for remoting host apps to connect to. Per ottenere il lettore di comunicazione remota olografica Windows, visitare l'App Store di Windows dalla HoloLens, cercare i servizi remoti e scaricare l'app.To get the Windows Holographic remoting player, visit the Windows app store from your HoloLens, search for Remoting, and download the app. Il lettore .NET Remoting include una funzionalità per la visualizzazione delle statistiche sullo schermo, che può essere utile quando si esegue il debug di applicazioni host Remote.The remoting player includes a feature to display statistics on-screen, which can be useful when debugging remoting host apps.

Note e risorseNotes and resources

La visualizzazione dell'app olografica richiede un modo per fornire all'app il dispositivo Direct3D, che deve essere usato per inizializzare lo spazio olografico.The holographic app view will need a way to provide your app with the Direct3D device, which must be used to initialize the holographic space. L'app deve usare questo dispositivo Direct3D per copiare e visualizzare il frame di anteprima.Your app should use this Direct3D device to copy and display the preview frame.

internal:
       const std::shared_ptr<DX::DeviceResources>& GetDeviceResources()
       {
           return m_deviceResources;
       }

Esempio di codice: È disponibile un esempio di codice .NET Remoting completo, che include una visualizzazione di applicazioni olografica compatibile con i progetti host .NET Remoting e Remoting per desktop Win32, UWP DirectX e UWP con XAML.Code sample: A complete Holographic Remoting code sample is available, which includes a holographic application view that is compatible with remoting and remoting host projects for desktop Win32, UWP DirectX, and UWP with XAML.

Nota di debug: La libreria remota olografica può generare eccezioni first-chance.Debugging note: The Holographic Remoting library can throw first-chance exceptions. Queste eccezioni possono essere visibili nelle sessioni di debug, a seconda delle impostazioni delle eccezioni di Visual Studio attive al momento.These exceptions may be visible in debugging sessions, depending on the Visual Studio exception settings that are active at the time. Queste eccezioni vengono rilevate internamente dalla libreria di comunicazione remota olografica e possono essere ignorate.These exceptions are caught internally by the Holographic Remoting library and can be ignored.