Sdílet prostřednictvím

Psaní vlastní aplikace Holographic Remoting Player

  • Článek

Pokud s Holographic Remoting začínáte, možná si budete chtít přečíst náš přehled.

Důležité

Tento dokument popisuje vytvoření vlastní aplikace přehrávače pro HoloLens 2. Vlastní hráči napsaní pro HoloLens 2 nejsou kompatibilní se vzdálenými aplikacemi napsanými pro HoloLens 1. To znamená, že obě aplikace musí používat balíček NuGet verze 2.x.x.

Vytvořením vlastní aplikace přehrávače Holographic Remoting můžete vytvořit vlastní aplikaci, která dokáže zobrazit imerzivní zobrazení ze vzdáleného počítače na holoLensu 2. Veškerý kód na této stránce a pracovní projekty najdete v úložišti GitHub s ukázkami holografické komunikace.

Holografický přehrávač vzdálené komunikace umožňuje vaší aplikaci zobrazit holografický obsah vykreslený na stolním počítači nebo zařízení s UPW, jako je Xbox One, s přístupem k dalším systémovým prostředkům. Aplikace přehrávače Holographic Remoting streamuje vstupní data do vzdálené aplikace Holographic Remoting a přijímá zpět imerzivní zobrazení jako video a zvukový stream. Připojení se provádí pomocí standardního Wi-Fi. Pokud chcete vytvořit aplikaci přehrávače, přidejte do aplikace UPW balíček NuGet. Pak napište kód pro zpracování připojení a zobrazení imerzivního zobrazení.

Požadavky

Dobrým výchozím bodem je funkční aplikace pro UPW založená na DirectX, která už cílí na rozhraní API pro Windows Mixed Reality. Podrobnosti najdete v přehledu vývoje directX. Pokud nemáte existující aplikaci a chcete začít úplně od začátku, je dobrým výchozím bodem šablona holografického projektu C++.

Důležité

Každá aplikace využívající Holographic Remoting by měla být authored to use a multi-threaded apartment. Použití apartmánu s jedním vláknem je podporováno, ale povede k suboptimální výkonu a možná zadrhávání během přehrávání. Při použití C++/WinRT winrt::init_apartment je výchozí vícevláknový byt.

Získání balíčku NuGet pro Holographic Remoting

Následující kroky jsou nutné k přidání balíčku NuGet do projektu v sadě Visual Studio.

  1. Otevřete projekt v sadě Visual Studio.
  2. Klikněte pravým tlačítkem na uzel projektu a vyberte Spravovat balíčky NuGet...
  3. Na zobrazeném panelu vyberte Procházet a vyhledejte "Holographic Remoting".
  4. Vyberte Microsoft.Holographic.Remoting, ujistěte se, že vyberete nejnovější verzi 2.x.x a vyberete Nainstalovat.
  5. Pokud se zobrazí dialogové okno Náhled, vyberte OK.
  6. Po zobrazení dialogového okna licenční smlouvy vyberte Přijmout .

Důležité

Uvnitř build\native\include\HolographicAppRemoting\Microsoft.Holographic.AppRemoting.idl balíčku NuGet najdete podrobnou dokumentaci k rozhraní API vystavené Holographic Remotingem.

Úprava souboru Package.appxmanifest aplikace

Aby aplikace věděla o Microsoft.Holographic.AppRemoting.dll přidaných balíčkem NuGet, je potřeba v projektu provést následující kroky:

  1. V Průzkumník řešení klikněte pravým tlačítkem na soubor Package.appxmanifest a vyberte Otevřít v aplikaci...
  2. Vyberte Editor XML (Text) a vyberte OK.
  3. Přidejte do souboru následující řádky a uložte ho.
  </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>

Vytvoření kontextu přehrávače

Jako první krok by aplikace měla vytvořit kontext přehrávače.

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

Upozorňující

Vlastní přehrávač vloží zprostředkující vrstvu mezi aplikací přehrávače a modulem runtime Windows Mixed Reality dodávaná s Windows. To se provádí při vytváření kontextu hráče. Z tohoto důvodu může jakékoli volání jakéhokoli rozhraní API windows Mixed Reality před vytvořením kontextu přehrávače vést k neočekávanému chování. Doporučeným přístupem je co nejdříve vytvořit kontext přehrávače před interakcí s jakýmkoli rozhraním API hybridní reality. Nikdy nekombinujte objekty vytvořené ani načtené prostřednictvím žádného rozhraní API windows Mixed Reality před voláním PlayerContext::Create objektů vytvořených nebo načtených později.

Dále lze vytvořit HolographicSpace voláním HolographicSpace.CreateForCoreWindow.

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

Připojení ke vzdálené aplikaci

Jakmile je aplikace přehrávače připravená k vykreslování obsahu, můžete navázat připojení ke vzdálené aplikaci.

Připojení lze navázat jedním z následujících způsobů:

  1. Aplikace přehrávače spuštěná na HoloLens 2 se připojí ke vzdálené aplikaci.
  2. Vzdálená aplikace se připojí k aplikaci přehrávače spuštěné na HoloLens 2.

Pokud se chcete připojit z aplikace přehrávače ke vzdálené aplikaci, zavolejte Connect metodu v kontextu přehrávače, který určuje název hostitele a port. Výchozí port je 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()
}

Důležité

Stejně jako u jakéhokoli rozhraní API Connect C++/WinRT může vyvolat winrt::hresult_error, které je potřeba zpracovat.

Naslouchání příchozím připojením v aplikaci přehrávače je možné provést voláním Listen metody. Během tohoto volání je možné zadat port handshake i přenosový port. Port handshake se používá pro počáteční metodu handshake. Data se pak posílají přes přenosový port. Ve výchozím nastavení se používá číslo portu 8265 a 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()
}

Zveřejňuje PlayerContext tři události pro monitorování stavu připojení.

  1. OnConnected: Aktivuje se, když se úspěšně naváže připojení ke vzdálené aplikaci.
m_onConnectedEventToken = m_playerContext.OnConnected([]() 
{
    // Handle connection successfully established
});
  1. OnDisconnected: Aktivuje se, pokud je připojení ukončeno nebo se nepodařilo navázat připojení.
m_onDisconnectedEventToken = m_playerContext.OnDisconnected([](ConnectionFailureReason failureReason)
{
    switch (failureReason)
    {
        // Handle connection failed or terminated.
        // See ConnectionFailureReason for possible reasons.
    }
}

Poznámka:

Možné ConnectionFailureReason hodnoty jsou zdokumentované v Microsoft.Holographic.AppRemoting.idl souboru.

  1. OnListening: Při naslouchání příchozím připojením se spustí.
m_onListeningEventToken = m_playerContext.OnListening([]()
{
    // Handle start listening for incoming connections
});

Stav připojení je navíc možné dotazovat pomocí ConnectionState vlastnosti v kontextu přehrávače.

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

Zobrazení vzdáleného vykresleného rámce

Pokud chcete zobrazit vzdáleně vykreslený obsah, zavolejte PlayerContext::BlitRemoteFrame při vykreslování HolographicFrame.

BlitRemoteFrame vyžaduje, aby zpětná vyrovnávací paměť pro aktuální holographicFrame byla vázána jako cíl vykreslení. Zpět vyrovnávací paměť lze přijímat z HolographicCameraRenderingParameters prostřednictvím Direct3D11BackBuffer vlastnost.

Při zavolání BlitRemoteFrame zkopíruje nejnovější přijatý rámec ze vzdálené aplikace do BackBuffer holographicFrame. Kromě toho je sada fokusů nastavena, pokud vzdálená aplikace při vykreslování vzdáleného rámce určila bod fokusu.

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

Poznámka:

PlayerContext::BlitRemoteFrame potenciálně přepíše fokus pro aktuální snímek.

Při úspěchu se BlitRemoteFrame vrátí BlitResult::Success_Color. V opačném případě vrátí důvod selhání:

  • BlitResult::Failed_NoRemoteFrameAvailable: Selhalo, protože není k dispozici žádný vzdálený rámec.
  • BlitResult::Failed_NoCamera: Selhalo, protože není k dispozici žádná kamera.
  • BlitResult::Failed_RemoteFrameTooOld: Selhání, protože vzdálený rámec je příliš starý (viz PlayerContext::BlitRemoteFrameTimeout vlastnost).

Důležité

Od verze 2.1.0 je možné s vlastním přehrávačem používat hloubkové přeprojektování prostřednictvím Holographic Remoting.

BlitResult může také vrátit BlitResult::Success_Color_Depth za následujících podmínek:

Pokud jsou tyto podmínky splněny, BlitRemoteFrame zasvítá se vzdálená hloubka do aktuálně vázané místní vyrovnávací paměti hloubky. Pak můžete vykreslit další místní obsah, který bude mít průsečík hloubky se vzdáleným vykresleným obsahem. Kromě toho můžete potvrdit místní hloubkovou vyrovnávací paměť prostřednictvím HolographicCameraRenderingParameters.CommitDirect3D11DepthBuffer ve vašem vlastním přehrávači, aby bylo možné provést hloubkové přeprojektování vzdáleného a místního vykresleného obsahu.

Režim transformace projekce

Jedním z problémů, které se zobrazí při použití hloubkového přeprojektování prostřednictvím Holographic Remoting, je, že vzdálený obsah lze vykreslit s jinou transformací projekce než místní obsah přímo vykreslený vaší vlastní aplikací přehrávače. Běžným případem použití je zadat různé hodnoty pro blízko a daleko rovinu (přes HolographicCamera::SetNearPlaneDistance a HolographicCamera::SetFarPlaneDistance) na straně přehrávače a na vzdálené straně. V tomto případě není jasné, jestli by transformace projekce na straně hráče měla odrážet vzdálené vzdálenosti blízko/vzdálené roviny nebo místní.

Počínaje verzí 2.1.0 můžete řídit režim transformace projekce prostřednictvím PlayerContext::ProjectionTransformConfig. Podporované hodnoty jsou:

  • Local - HolographicCameraPose::P rojectionTransform vrátí transformaci projekce, která odráží vzdálenosti téměř/daleko roviny nastavené vaší vlastní aplikací přehrávače na HolographicCamera.
  • Remote – Transformace projekce odráží vzdálenosti blízko/daleko roviny určené vzdálenou aplikací.
  • Merged – Vzdálenost v blízkosti/daleko od vzdálené aplikace a vlastní aplikace přehrávače se sloučí. Ve výchozím nastavení je to provedeno tak, že vezme minimum vzdáleností v blízké rovině a maximální vzdáleností na dálku. V případě, že je vzdálená nebo místní strana invertována, řekněme daleko < blízko, vzdálené vzdálenosti blízko/vzdálené roviny jsou překlopené.

Volitelné: Nastavení BlitRemoteFrameTimeout

Důležité

PlayerContext::BlitRemoteFrameTimeout se podporuje od verze 2.0.9.

Vlastnost PlayerContext::BlitRemoteFrameTimeout určuje dobu, po kterou je vzdálený rámec znovu použit, pokud není přijat žádný nový vzdálený rámec.

Běžným případem použití je povolení časového limitu BlitRemoteFrame k zobrazení prázdné obrazovky, pokud nejsou po určitou dobu přijaty žádné nové snímky. Pokud je povolen návratový BlitRemoteFrame typ metody, lze také použít k přepnutí na místně vykreslený náhradní obsah.

Chcete-li povolit časový limit, nastavte hodnotu vlastnosti na dobu trvání rovna nebo větší než 100 ms. Pokud chcete časový limit zakázat, nastavte vlastnost na nulovou dobu trvání. Pokud je povolený časový limit a pro nastavenou dobu není přijat žádný vzdálený rámec, funkce BlitRemoteFrame selže a vrátí Failed_RemoteFrameTooOld se, dokud nebude přijat nový vzdálený rámec.

using namespace std::chrono_literals;

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

Volitelné: Získání statistik o posledním vzdáleném rámci

Pokud chcete diagnostikovat problémy s výkonem nebo sítí, je možné prostřednictvím vlastnosti načíst statistiky o posledním vzdáleném PlayerContext::LastFrameStatistics rámci. Statistiky se aktualizují během volání HolographicFrame ::P resentUsingCurrentPrediction.

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

Další informace najdete PlayerFrameStatistics v dokumentaci v Microsoft.Holographic.AppRemoting.idl souboru.

Volitelné: Vlastní datové kanály

Vlastní datové kanály je možné použít k odesílání uživatelských dat přes již vytvořené připojení vzdálené komunikace. Další informace najdete ve vlastních datových kanálech.

Volitelné: Překreslování

Holographic Remoting předpovídá, kde bude hlava uživatele v době, kdy se vykreslené obrázky zobrazí na displejích. Tato předpověď je však aproximace. Proto se predikovaná oblast zobrazení ve vzdálené aplikaci a pozdější skutečná oblast zobrazení v aplikaci přehrávače může lišit. Silnější odchylky (například z důvodu nepředvídatelného pohybu) můžou způsobit černé oblasti na hranicích zobrazení frustum. Počínaje verzí 2.6.0 můžete pomocí funkce Over-Rendering snížit černé oblasti a vylepšit kvalitu vizuálu tím, že uměle zvýšíte oblast zobrazení nad rámec zobrazení frustum.

Překreslování je možné povolit prostřednictvím PlayerContext::ConfigureOverRendering.

Určuje OverRenderingConfig desetinnou velikost zvětšení skutečné oblasti zobrazení, aby předpovězené zobrazení bylo větší a méně řezů. Se zvýšenou velikostí oblasti zobrazení se hustota pixelů zmenší, takže OverRenderingConfig umožňuje také zvětšit rozlišení. Pokud se zvýšení oblasti zobrazení rovná rozlišení, zvýší hustotu pixelů zůstane stejná. OverRenderingConfig je definován jako:

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

Volitelné: Synchronizace souřadnicového systému

Od synchronizace souřadnicového systému verze 2.7.0 je možné použít k zarovnání prostorových dat mezi přehrávačem a vzdálenou aplikací. Další informace najdete v tématu Synchronizace souřadnicových systémů s přehledem holografické vzdálené komunikace.

Viz také