Partager via

Écriture d’une application de lecteur de communication à distance holographique personnalisée

  • Article

Si vous débutez avec la communication à distance holographique, vous pouvez lire notre vue d’ensemble.

Important

Ce document décrit la création d’une application de lecteur personnalisée pour HoloLens 2. Les lecteurs personnalisés écrits pour HoloLens 2 ne sont pas compatibles avec les applications distantes écrites pour HoloLens 1. Cela implique que les deux applications doivent utiliser le package NuGet version 2.x.x.

En créant une application de lecteur Holographic Remoting personnalisée, vous pouvez créer une application personnalisée capable d’afficher des vues immersives à partir d’une machine distante sur votre HoloLens 2. Vous trouverez tout le code de cette page et des projets de travail dans le dépôt github des exemples holographiques de communication à distance.

Un lecteur holographique de communication à distance permet à votre application d’afficher le contenu holographique affiché sur un PC de bureau ou un appareil UWP comme xbox One avec accès à d’autres ressources système. Une application de lecteur Holographic Remoting diffuse des données d’entrée vers une application distante Holographic Remoting et reçoit une vue immersive en tant que flux vidéo et audio. La connexion est établie à l’aide du Wi-Fi standard. Pour créer une application de lecteur, utilisez un package NuGet pour ajouter la communication à distance Holographique à votre application UWP. Ensuite, écrivez du code pour gérer la connexion et afficher une vue immersive.

Prérequis

Un bon point de départ est une application UWP basée sur DirectX qui cible déjà l’API Windows Mixed Reality. Pour plus d’informations, consultez Vue d’ensemble du développement DirectX. Si vous n’avez pas d’application existante et que vous souhaitez commencer à partir de zéro, le modèle de projet holographique C++ est un bon point de départ.

Important

Toute application utilisant Holographic Remoting doit être créée pour utiliser un appartement multithread. L’utilisation d’un appartement à thread unique est prise en charge, mais entraîne des performances sous-optimales et éventuellement un éparpillé pendant la lecture. Lorsque vous utilisez C++/WinRT winrt  ::init_apartment un appartement multithread est la valeur par défaut.

Obtenir le package NuGet Holographic Remoting

Les étapes suivantes sont nécessaires pour ajouter le package NuGet à un projet dans Visual Studio.

  1. Ouvrez le projet dans Visual Studio.
  2. Cliquez avec le bouton droit sur le nœud du projet, puis sélectionnez Gérer les packages NuGet...
  3. Dans le panneau qui s’affiche, sélectionnez Parcourir, puis recherchez « Communication à distance holographique ».
  4. Sélectionnez Microsoft.Holographic.Remoting, veillez à sélectionner la dernière version 2.x.x.x , puis sélectionnez Installer.
  5. Si la boîte de dialogue Aperçu s’affiche, sélectionnez OK.
  6. Sélectionnez J’accepte lorsque la boîte de dialogue contrat de licence s’affiche.

Important

L’intérieur build\native\include\HolographicAppRemoting\Microsoft.Holographic.AppRemoting.idl du package NuGet contient une documentation détaillée pour l’API exposée par Holographic Remoting.

Modifier le Package.appxmanifest de l’application

Pour rendre l’application consciente de l’Microsoft.Holographic.AppRemoting.dll ajoutée par le package NuGet, les étapes suivantes doivent être effectuées sur le projet :

  1. Dans le Explorateur de solutions, cliquez avec le bouton droit sur le fichier Package.appxmanifest, puis sélectionnez Ouvrir avec...
  2. Sélectionner l’éditeur XML (texte) et sélectionner OK
  3. Ajoutez les lignes suivantes au fichier et enregistrez
  </Capabilities>

  <!--Add lines below -->
  <Extensions>
    <Extension Category="windows.activatableClass.inProcessServer">
      <InProcessServer>
        <Path>Microsoft.Holographic.AppRemoting.dll</Path>
        <ActivatableClass ActivatableClassId="Microsoft.Holographic.AppRemoting.PlayerContext" ThreadingModel="both" />
      </InProcessServer>
    </Extension>
  </Extensions>
  <!--Add lines above -->

</Package>

Créer le contexte du lecteur

En première étape, l’application doit créer un contexte de lecteur.

// class declaration:

#include <winrt/Microsoft.Holographic.AppRemoting.h>

...

private:
// PlayerContext used to connect with a Holographic Remoting remote app and display remotely rendered frames
winrt::Microsoft::Holographic::AppRemoting::PlayerContext m_playerContext = nullptr;

// class implementation:

// Create the player context
// IMPORTANT: This must be done before creating the HolographicSpace (or any other call to the Holographic API).
m_playerContext = winrt::Microsoft::Holographic::AppRemoting::PlayerContext::Create();

Avertissement

Un lecteur personnalisé injecte une couche intermédiaire entre l’application lecteur et le runtime Windows Mixed Reality fourni avec Windows. Cela s’effectue lors de la création du contexte du joueur. Pour cette raison, tout appel sur n’importe quelle API Windows Mixed Reality avant de créer le contexte du lecteur peut entraîner un comportement inattendu. L’approche recommandée consiste à créer le contexte du joueur dès que possible avant l’interaction avec n’importe quelle API de réalité mixte. Ne mélangez jamais d’objets créés ou récupérés par le biais d’une API Windows Mixed Reality avant l’appel à PlayerContext::Create des objets créés ou récupérés par la suite.

Vous pouvez ensuite créer HolographicSpace en appelant HolographicSpace.CreateForCoreWindow.

m_holographicSpace = winrt::Windows::Graphics::Holographic::HolographicSpace::CreateForCoreWindow(window);

Se connecter à l’application distante

Une fois que l’application lecteur est prête pour le rendu du contenu, une connexion à l’application distante peut être établie.

La connexion peut être établie de l’une des manières suivantes :

  1. L’application lecteur s’exécutant sur HoloLens 2 se connecte à l’application distante.
  2. L’application distante se connecte à l’application lecteur s’exécutant sur HoloLens 2.

Pour vous connecter à partir de l’application lecteur à l’application distante, appelez la Connect méthode dans le contexte du lecteur en spécifiant le nom d’hôte et le port. Le port par défaut est 8265.

try
{
    m_playerContext.Connect(m_hostname, m_port);
}
catch(winrt::hresult_error& e)
{
    // Failed to connect. Get an error details via e.code() and e.message()
}

Important

Comme avec n’importe quelle API Connect C++/WinRT peut lever un winrt ::hresult_error qui doit être géré.

L’écoute des connexions entrantes sur l’application lecteur peut être effectuée en appelant la Listen méthode. Le port de négociation et le port de transport peuvent être spécifiés pendant cet appel. Le port de négociation est utilisé pour la négociation initiale. Les données sont ensuite envoyées sur le port de transport. Par défaut, le numéro de port 8265 et le 8266 sont utilisés.

try
{
    m_playerContext.Listen(L"0.0.0.0", m_port, m_port + 1);
}
catch(winrt::hresult_error& e)
{
    // Failed to listen. Get an error details via e.code() and e.message()
}

L’exposition PlayerContext de trois événements pour surveiller l’état de la connexion

  1. OnConnected : déclenché lorsqu’une connexion à l’application distante a été établie avec succès.
m_onConnectedEventToken = m_playerContext.OnConnected([]() 
{
    // Handle connection successfully established
});
  1. OnDisconnected : déclenché si une connexion établie est arrêtée ou qu’une connexion n’a pas pu être établie.
m_onDisconnectedEventToken = m_playerContext.OnDisconnected([](ConnectionFailureReason failureReason)
{
    switch (failureReason)
    {
        // Handle connection failed or terminated.
        // See ConnectionFailureReason for possible reasons.
    }
}

Remarque

Les valeurs possibles ConnectionFailureReason sont documentées dans le Microsoft.Holographic.AppRemoting.idl fichier.

  1. OnListening : lors de l’écoute des connexions entrantes démarre.
m_onListeningEventToken = m_playerContext.OnListening([]()
{
    // Handle start listening for incoming connections
});

En outre, l’état de connexion peut être interrogé à l’aide de la ConnectionState propriété sur le contexte du lecteur.

winrt::Microsoft::Holographic::AppRemoting::ConnectionState state = m_playerContext.ConnectionState();

Afficher le cadre rendu à distance

Pour afficher le contenu rendu à distance, appelez PlayerContext::BlitRemoteFrame lors du rendu d’un HolographicFrame.

BlitRemoteFrame nécessite que la mémoire tampon de retour pour l’HolographicFrame actuel soit liée en tant que cible de rendu. La mémoire tampon back peut être reçue de HolographicCameraRenderingParameters via la propriété Direct3D11BackBuffer .

Lorsqu’elle est appelée, BlitRemoteFrame copie la dernière image reçue de l’application distante dans le BackBuffer de l’HolographicFrame. En outre, le jeu de points de focus est défini, si l’application distante a spécifié un point de focus pendant le rendu de l’image distante.

// Blit the remote frame into the backbuffer for the HolographicFrame.
winrt::Microsoft::Holographic::AppRemoting::BlitResult result = m_playerContext.BlitRemoteFrame();

Remarque

PlayerContext::BlitRemoteFrame remplace potentiellement le point de focus pour l’image actuelle.

En cas de réussite, BlitRemoteFrame retourne BlitResult::Success_Color. Sinon, elle retourne la raison de l’échec :

  • BlitResult::Failed_NoRemoteFrameAvailable: Échec, car aucune trame distante n’est disponible.
  • BlitResult::Failed_NoCamera: Échec car aucun appareil photo n’est présent.
  • BlitResult::Failed_RemoteFrameTooOld: Échec, car la trame distante est trop ancienne (voir la propriété PlayerContext ::BlitRemoteFrameTimeout).

Important

À compter de la version 2.1.0 , il est possible avec un lecteur personnalisé d’utiliser la reprojection de profondeur via la communication à distance holographique.

BlitResult peut également retourner BlitResult::Success_Color_Depth dans les conditions suivantes :

Si ces conditions sont remplies, BlitRemoteFrame blit la profondeur distante dans la mémoire tampon de profondeur locale actuellement liée. Vous pouvez ensuite afficher du contenu local supplémentaire, qui aura une intersection de profondeur avec le contenu rendu distant. En outre, vous pouvez valider la mémoire tampon de profondeur locale via HolographicCameraRenderingParameters.CommitDirect3D11DepthBuffer dans votre lecteur personnalisé pour avoir un reprojection de profondeur pour le contenu rendu distant et local.

Mode de transformation de projection

Un problème, qui se produit lors de l’utilisation de la reprojection de profondeur via la communication à distance holographique, est que le contenu distant peut être rendu avec une transformation de projection différente de celle du contenu local directement restitué par votre application de lecteur personnalisé. Un cas d’usage courant consiste à spécifier différentes valeurs pour le plan proche et lointain (via HolographicCamera ::SetNearPlaneDistance et HolographicCamera ::SetFarPlaneDistance) côté lecteur et côté distant. Dans ce cas, il n’est pas clair si la transformation de projection côté lecteur doit refléter les distances de plan proches/éloignées distantes ou locales.

À compter de la version 2.1.0, vous pouvez contrôler le mode de transformation de projection via PlayerContext::ProjectionTransformConfig. Les valeurs prises en charge sont les suivantes :

  • Local - HolographicCameraPose ::P rojectionTransform retourne une transformation de projection, qui reflète les distances de plan proche/éloignée définies par votre application de lecteur personnalisé sur HolographicCamera.
  • Remote - La transformation de projection reflète les distances du plan proche/lointain spécifiées par l’application distante.
  • Merged - Les distances du plan proche/lointain de votre application distante et de votre application lecteur personnalisée sont fusionnées. Par défaut, cela est effectué en prenant au minimum les distances du plan proche et le maximum des distances du plan de distance. Dans le cas où le côté distant ou local est inversé, par exemple loin < près, les distances de plan proche/loin distantes sont retournées.

Facultatif : Définir BlitRemoteFrameTimeout

Important

PlayerContext::BlitRemoteFrameTimeout est pris en charge à partir de la version 2.0.9.

La PlayerContext::BlitRemoteFrameTimeout propriété spécifie la durée pendant laquelle une trame distante est réutilisée si aucune nouvelle trame distante n’est reçue.

Un cas d’usage courant consiste à autoriser le délai d’expiration BlitRemoteFrame à afficher un écran vide si aucune nouvelle image n’est reçue pendant une certaine durée. Lorsqu’elle est activée, le type de retour de la BlitRemoteFrame méthode peut également être utilisé pour basculer vers un contenu de secours rendu localement.

Pour activer le délai d’expiration, définissez la valeur de la propriété sur une durée égale ou supérieure à 100 ms. Pour désactiver le délai d’expiration, définissez la propriété sur zéro durée. Si le délai d’expiration est activé et qu’aucune image distante n’est reçue pendant la durée définie, BlitRemoteFrame échoue et retourne Failed_RemoteFrameTooOld jusqu’à ce qu’une nouvelle image distante soit reçue.

using namespace std::chrono_literals;

// Set the BlitRemoteFrame timeout to 0.5s
m_playerContext.BlitRemoteFrameTimeout(500ms);

Facultatif : Obtenir des statistiques sur la dernière trame distante

Pour diagnostiquer les problèmes de performances ou de réseau, les statistiques sur la dernière trame distante peuvent être récupérées via la PlayerContext::LastFrameStatistics propriété. Les statistiques sont mises à jour pendant l’appel à HolographicFrame ::P resentUsingCurrentPrediction.

// Get statistics for the last presented frame.
winrt::Microsoft::Holographic::AppRemoting::PlayerFrameStatistics statistics = m_playerContext.LastFrameStatistics();

Pour plus d’informations, consultez la PlayerFrameStatistics documentation du Microsoft.Holographic.AppRemoting.idl fichier.

Facultatif : Canaux de données personnalisés

Les canaux de données personnalisés peuvent être utilisés pour envoyer des données utilisateur via la connexion à distance déjà établie. Pour plus d’informations, consultez les canaux de données personnalisés.

Facultatif : sur-rendu

La communication à distance holographique prédit où la tête de l’utilisateur sera au moment où les images rendues apparaissent sur les écrans. Toutefois, cette prédiction est une approximation. Par conséquent, la fenêtre d’affichage prédite sur l’application distante et la fenêtre d’affichage réelle ultérieure sur l’application lecteur peut différer. Des écarts plus forts (par exemple, en raison d’un mouvement imprévisible) peuvent provoquer des régions noires aux bordures du frustum d’affichage. À compter de la version 2.6.0, vous pouvez utiliser Over-Rendering pour réduire les régions noires et améliorer la qualité visuelle en augmentant artificiellement la fenêtre d’affichage au-delà du frustum d’affichage.

Le sur-rendu peut être activé via PlayerContext::ConfigureOverRendering.

Spécifie OverRenderingConfig une augmentation de taille fractionnelle à la fenêtre d’affichage réelle, de sorte que la fenêtre d’affichage prédite devient plus grande et moins la coupe se produit. Avec une taille de fenêtre d’affichage accrue, la densité de pixels diminue, de sorte que overRenderingConfig vous permet également d’augmenter la résolution. Si l’augmentation de la fenêtre d’affichage est égale à la résolution, la densité des pixels reste la même. OverRenderingConfig est défini comme :

struct OverRenderingConfig
{
    float HorizontalViewportIncrease; // The fractional horizontal viewport increase. (e.g. 10% -> 0.1).
    float VerticalViewportIncrease; // The fractional vertical viewport increase. (e.g. 10% -> 0.1).
                
    float HorizontalResolutionIncrease; // The fractional horizontal resolution increase. (e.g. 10% -> 0.1).
    float VerticalResolutionIncrease; // The fractional vertical resolution increase. (e.g. 10% -> 0.1).
};

Facultatif : Synchronisation du système de coordonnées

À compter de la version 2.7.0, la synchronisation du système de coordonnées peut être utilisée pour aligner les données spatiales entre le lecteur et l’application distante. Pour plus d’informations, consultez La synchronisation du système de coordonnées avec la communication à distance Holographic.

Voir aussi