Dela via

Skriva en anpassad Holographic Remoting Player-app

  • Artikel

Om du inte har använt Holographic Remoting tidigare kanske du vill läsa vår översikt.

Viktigt!

I det här dokumentet beskrivs hur du skapar ett anpassat spelarprogram för HoloLens 2. Anpassade spelare skrivna för HoloLens 2 är inte kompatibla med fjärrprogram skrivna för HoloLens 1. Detta innebär att båda programmen måste använda NuGet-paket version 2.x.x.

Genom att skapa en anpassad Holographic Remoting-spelarapp kan du skapa ett anpassat program som kan visa uppslukande vyer från en fjärrdator på HoloLens 2. All kod på den här sidan och arbetsprojekt finns på github-lagringsplatsen Holographic Remoting Samples.

Med en Holographic Remoting-spelare kan din app visa holografiskt innehåll som återges på en stationär dator eller UWP-enhet som Xbox One med åtkomst till fler systemresurser. En Holographic Remoting-spelarapp strömmar indata till ett Holographic Remoting-fjärrprogram och tar emot en uppslukande vy som video- och ljudström. Anslutningen görs med wi-fi som standard. Om du vill skapa en spelarapp använder du ett NuGet-paket för att lägga till Holographic Remoting i UWP-appen. Skriv sedan kod för att hantera anslutningen och för att visa en fördjupad vy.

Förutsättningar

En bra utgångspunkt är en fungerande DirectX-baserad UWP-app som redan riktar sig till Windows Mixed Reality-API:et. Mer information finns i Översikt över DirectX-utveckling. Om du inte har någon befintlig app och vill börja från början är C++ holografisk projektmall en bra utgångspunkt.

Viktigt!

Alla appar som använder Holographic Remoting bör skapas för att använda en flertrådad lägenhet. Användning av en entrådad lägenhet stöds men leder till underoptimala prestanda och eventuellt stamning under uppspelningen. När du använder C++/WinRT winrt::init_apartment är en flertrådad lägenhet standard.

Hämta NuGet-paketet Holographic Remoting

Följande steg krävs för att lägga till NuGet-paketet i ett projekt i Visual Studio.

  1. Öppna projektet i Visual Studio.
  2. Högerklicka på projektnoden och välj Hantera NuGet-paket...
  3. I panelen som visas väljer du Bläddra och söker sedan efter "Holographic Remoting".
  4. Välj Microsoft.Holographic.Remoting, se till att välja den senaste 2.x.x-versionen och välj Installera.
  5. Om dialogrutan Förhandsgranskning visas väljer du OK.
  6. Välj Jag accepterar när dialogrutan licensavtal visas.

Viktigt!

I build\native\include\HolographicAppRemoting\Microsoft.Holographic.AppRemoting.idl NuGet-paketet finns detaljerad dokumentation för API:et som exponeras av Holographic Remoting.

Ändra Package.appxmanifest för programmet

För att göra programmet medvetet om Microsoft.Holographic.AppRemoting.dll som lagts till av NuGet-paketet måste följande steg vidtas i projektet:

  1. Högerklicka på filen Package.appxmanifest i Solution Explorer och välj Öppna med...
  2. Välj XML-redigeraren (text) och välj OK
  3. Lägg till följande rader i filen och spara
  </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>

Skapa spelarkontexten

Som ett första steg bör programmet skapa en spelarkontext.

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

Varning

En anpassad spelare matar in ett mellanliggande lager mellan spelarappen och Windows Mixed Reality-körningen som levereras med Windows. Detta görs när du skapar spelarkontexten. Därför kan alla anrop på alla Windows Mixed Reality-API:er innan du skapar spelarkontexten resultera i oväntat beteende. Den rekommenderade metoden är att skapa spelarkontexten så tidigt som möjligt innan du interagerar med ett Mixed Reality-API. Blanda aldrig objekt som skapats eller hämtats via något Windows Mixed Reality-API innan anropet till PlayerContext::Create med objekt som skapats eller hämtats efteråt.

Sedan kan Du skapa HolographicSpace genom att anropa HolographicSpace.CreateForCoreWindow.

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

Ansluta till fjärrappen

När spelarappen är redo för rendering av innehåll kan en anslutning till fjärrappen upprättas.

Anslutningen kan upprättas på något av följande sätt:

  1. Spelarappen som körs på HoloLens 2 ansluter till fjärrappen.
  2. Fjärrappen ansluter till spelarappen som körs på HoloLens 2.

Om du vill ansluta från spelarappen till fjärrappen Connect anropar du metoden i spelarkontexten som anger värdnamnet och porten. Standardporten är 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()
}

Viktigt!

Precis som med alla C++/WinRT-API Connect :er kan det utlösa en winrt::hresult_error som måste hanteras.

Du kan lyssna efter inkommande anslutningar i spelarappen genom att anropa Listen metoden. Både handskakningsporten och transportporten kan anges under det här anropet. Handskakningsporten används för den första handskakningen. Data skickas sedan via transportporten. Som standard används portnummer 8265 och 8266 .

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

PlayerContext Exponerar tre händelser för att övervaka anslutningens tillstånd

  1. OnConnected: Utlöses när en anslutning till fjärrappen har upprättats.
m_onConnectedEventToken = m_playerContext.OnConnected([]() 
{
    // Handle connection successfully established
});
  1. OnDisconnected: Utlöses om en upprättad anslutning avslutas eller om det inte gick att upprätta en anslutning.
m_onDisconnectedEventToken = m_playerContext.OnDisconnected([](ConnectionFailureReason failureReason)
{
    switch (failureReason)
    {
        // Handle connection failed or terminated.
        // See ConnectionFailureReason for possible reasons.
    }
}

Kommentar

Möjliga ConnectionFailureReason värden dokumenteras i Microsoft.Holographic.AppRemoting.idl filen.

  1. OnListening: När du lyssnar efter inkommande anslutningar startar.
m_onListeningEventToken = m_playerContext.OnListening([]()
{
    // Handle start listening for incoming connections
});

Dessutom kan anslutningstillståndet frågas med hjälp av ConnectionState egenskapen i spelarkontexten.

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

Visa den fjärranslutna ramen

Om du vill visa det fjärranslutna innehållet anropar PlayerContext::BlitRemoteFrame du medan du återger en HolographicFrame.

BlitRemoteFrame kräver att backbufferten för den aktuella HolographicFrame är bunden som återgivningsmål. Serverbufferten kan tas emot från HolographicCameraRenderingParameters via egenskapen Direct3D11BackBuffer .

När den anropas BlitRemoteFrame kopieras den senaste mottagna ramen från fjärrprogrammet till BackBuffer för HolographicFrame. Dessutom anges fokuspunktsuppsättningen om fjärrprogrammet har angett en fokuspunkt under återgivningen av fjärrramen.

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

Kommentar

PlayerContext::BlitRemoteFrame skriver potentiellt över fokuspunkten för den aktuella ramen.

Vid lyckat resultat BlitRemoteFrame returnerar BlitResult::Success_Color. Annars returneras felorsaken:

  • BlitResult::Failed_NoRemoteFrameAvailable: Det gick inte eftersom det inte finns någon tillgänglig fjärrram.
  • BlitResult::Failed_NoCamera: Misslyckades eftersom ingen kamera finns.
  • BlitResult::Failed_RemoteFrameTooOld: Det gick inte eftersom fjärrramen är för gammal (se PlayerContext::BlitRemoteFrameTimeout-egenskapen).

Viktigt!

Från och med version 2.1.0 är det möjligt med en anpassad spelare att använda djupåtergivning via Holographic Remoting.

BlitResult kan också returneras BlitResult::Success_Color_Depth under följande villkor:

Om dessa villkor uppfylls BlitRemoteFrame blir det fjärranslutna djupet i den lokala djupbufferten som för närvarande är bunden. Du kan sedan rendera ytterligare lokalt innehåll, som kommer att ha djupskärning med det fjärråtergivna innehållet. Dessutom kan du checka in den lokala djupbufferten via HolographicCameraRenderingParameters.CommitDirect3D11DepthBuffer i din anpassade spelare för att få djupåtergivning för fjärr- och lokalt renderat innehåll.

Transformeringsläge för projektion

Ett problem som uppstår när du använder djupåtergivning via Holographic Remoting är att fjärrinnehållet kan renderas med en annan projektionsomformning än lokalt innehåll som återges direkt av din anpassade spelarapp. Ett vanligt användningsfall är att ange olika värden för nära och långt plan (via HolographicCamera::SetNearPlaneDistance och HolographicCamera::SetFarPlaneDistance) på spelarsidan och på fjärrsidan. I det här fallet är det inte klart om projektionstransformionen på spelarsidan ska återspegla fjärravstånden nära/långt eller de lokala.

Från och med version 2.1.0 kan du styra projektionens transformeringsläge via PlayerContext::ProjectionTransformConfig. Värden som stöds är:

  • Local - HolographicCameraPose::P rojectionTransform returnerar en projektionstransformering som återspeglar de avstånd på nära/fjärran plan som angetts av din anpassade spelarapp på HolographicCamera.
  • Remote – Projektionstransformering återspeglar de avstånd på nära/fjärranslutna plan som anges av fjärrappen.
  • Merged – Avstånd till nära/långt plan från fjärrappen och din anpassade spelarapp slås samman. Som standard görs detta genom att ta det minsta av de nära flygavstånden och det maximala avståndet för fjärran plan. Om antingen fjärrsidan eller den lokala sidan är inverterad, till exempel långt < nära, vänds de avlägsna avstånden nära/långt planet.

Valfritt: Ange BlitRemoteFrameTimeout

Viktigt!

PlayerContext::BlitRemoteFrameTimeout stöds från och med version 2.0.9.

Egenskapen PlayerContext::BlitRemoteFrameTimeout anger hur lång tid en fjärrram återanvänds om ingen ny fjärrram tas emot.

Ett vanligt användningsfall är att aktivera tidsgränsen för BlitRemoteFrame för att visa en tom skärm om inga nya bildrutor tas emot under en viss tid. När den är aktiverad kan returtypen för BlitRemoteFrame metoden också användas för att växla till ett lokalt renderat reservinnehåll.

Om du vill aktivera tidsgränsen anger du egenskapsvärdet till en varaktighet som är lika med eller större än 100 ms. Om du vill inaktivera tidsgränsen anger du egenskapen till noll varaktighet. Om tidsgränsen är aktiverad och ingen fjärrram tas emot under den angivna varaktigheten misslyckas BlitRemoteFrame och återgår Failed_RemoteFrameTooOld tills en ny fjärrram tas emot.

using namespace std::chrono_literals;

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

Valfritt: Hämta statistik om den senaste fjärrramen

För att diagnostisera prestanda- eller nätverksproblem kan statistik om den senaste fjärrramen PlayerContext::LastFrameStatistics hämtas via egenskapen . Statistik uppdateras under anropet till HolographicFrame::P resentUsingCurrentPrediction.

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

Mer information finns i dokumentationen PlayerFrameStatistics Microsoft.Holographic.AppRemoting.idl i filen.

Valfritt: Anpassade datakanaler

Anpassade datakanaler kan användas för att skicka användardata via den redan etablerade fjärrkommunikationsanslutningen. Mer information finns i anpassade datakanaler.

Valfritt: Överrendering

Holographic Remoting förutsäger var användarens huvud kommer att finnas när de renderade bilderna visas på displayerna. Den här förutsägelsen är dock en uppskattning. Därför kan den förutsagda visningsporten på fjärrappen och den senare faktiska visningsporten i spelarappen skilja sig åt. Starkare avvikelser (till exempel på grund av oförutsägbar rörelse) kan orsaka svarta regioner vid gränserna för visningsfrustumet. Från och med version 2.6.0 kan du använda Överrendering för att minska de svarta regionerna och förbättra den visuella kvaliteten genom att artificiellt öka visningsporten bortom visningsfrustum.

Överrendering kan aktiveras via PlayerContext::ConfigureOverRendering.

OverRenderingConfig Anger en ökning av bråkstorleken till den faktiska visningsporten, så att det förutsagda visningsporten blir större och mindre skärning sker. Med en ökad vyportstorlek minskar pixeldensiteten, så med OverRenderingConfig kan du också öka upplösningen. Om visningsportökningen är lika med upplösningen förblir pixeldensiteten densamma. OverRenderingConfig definieras som:

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

Valfritt: Samordna systemsynkronisering

Från och med version 2.7.0 kan koordinatsystemsynkronisering användas för att justera rumsliga data mellan spelaren och fjärrappen. Mer information finns i Koordinera systemsynkronisering med Holographic Remoting Overview (Samordna systemsynkronisering med Holographic Remoting Overview).

Se även