WinRT v Unreal

V průběhu vývoje HoloLensu možná budete muset napsat funkci pomocí WinRT. Například otevření dialogového okna souboru v aplikaci HoloLens by potřebovalo FileSavePicker v hlavičkovém souboru winrt/Windows.Storage.Pickers.h. WinRT se podporuje v buildovacím systému Unreal od verze 4.26 a vyšší.

4.26

Standardní rozhraní WinRT API

Nejběžnějším a nejjednodušším způsobem použití winRT je volání metod z WinSDK. Uděláte to tak, že otevřete soubor YourModule.Build.cs a přidáte následující řádky:

if (Target.Platform == UnrealTargetPlatform.Win64 || Target.Platform == UnrealTargetPlatform.HoloLens)
{
	// These parameters are mandatory for winrt support
	bEnableExceptions = true;
	bUseUnity = false;
	CppStandard = CppStandardVersion.Cpp17;
	PublicSystemLibraries.AddRange(new string[] { "shlwapi.lib", "runtimeobject.lib" });
	PrivateIncludePaths.Add(Path.Combine(Target.WindowsPlatform.WindowsSdkDir,        
                                        "Include", 
                                        Target.WindowsPlatform.WindowsSdkVersion, 
                                        "cppwinrt"));
}

Dále musíte přidat následující hlavičky WinRT:

#if (PLATFORM_WINDOWS || PLATFORM_HOLOLENS) 
//Before writing any code, you need to disable common warnings in WinRT headers
#pragma warning(disable : 5205 4265 4268 4946)

#include "Windows/AllowWindowsPlatformTypes.h"
#include "Windows/AllowWindowsPlatformAtomics.h"
#include "Windows/PreWindowsApi.h"

#include <unknwn.h>
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Perception.Spatial.h>
#include <winrt/Windows.Foundation.Collections.h>

#include "Windows/PostWindowsApi.h"
#include "Windows/HideWindowsPlatformAtomics.h"
#include "Windows/HideWindowsPlatformTypes.h"
#endif

Kód WinRT se dá zkompilovat jenom na platformách Win64 a HoloLens, takže příkaz if brání zahrnutí knihoven WinRT na jiných platformách. unknwn.h byl přidán pro rozhraní IUnknown.

WinRT z balíčku NuGet

Je to trochu složitější, pokud potřebujete přidat balíček NuGet s podporou WinRT. V tomto případě může Visual Studio udělat prakticky veškerou práci za vás, ale Unreal build system ne. Naštěstí to není tak těžké. Níže je příklad, jak byste postupovali při stahování balíčku Microsoft.MixedReality.QR. Můžete jej nahradit jiným, jen se ujistěte, že jste neztratili soubor winmd a zkopírujte správnou knihovnu DLL.

Knihovny DLL sady Windows SDK z předchozí části jsou zpracovávány operačním systémem. Knihovny DLL NuGet musí být spravovány kódem ve vašem modulu. Doporučujeme přidat kód pro jejich stažení, zkopírování do složky binárních souborů a načtení do paměti procesu při spuštění modulu.

V prvním kroku byste měli do kořenové složky modulu přidat packages.config (/nuget/reference/packages-config). Tam byste měli přidat všechny balíčky, které chcete stáhnout, včetně všech jejich závislostí. Zde jsem přidal Microsoft.MixedReality.QR jako primární datovou část a dvě další jako závislosti s ní. Formát tohoto souboru je stejný jako v sadě Visual Studio:

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Microsoft.MixedReality.QR" version="0.5.2102" targetFramework="native" />
  <package id="Microsoft.VCRTForwarders.140" version="1.0.6" targetFramework="native" />
  <package id="Microsoft.Windows.CppWinRT" version="2.0.200729.8" targetFramework="native" />
</packages>

Teď si můžete stáhnout NuGet, požadované balíčky nebo si projděte dokumentaci k NuGetu.

Otevřete Soubor YourModule.Build.cs a přidejte následující kód:

// WinRT with Nuget support
if (Target.Platform == UnrealTargetPlatform.Win64 || Target.Platform == UnrealTargetPlatform.HoloLens)
{
	// these parameters mandatory for winrt support
	bEnableExceptions = true;
	bUseUnity = false;
	CppStandard = CppStandardVersion.Cpp17;
	PublicSystemLibraries.AddRange(new string [] { "shlwapi.lib", "runtimeobject.lib" });

	// prepare everything for nuget
	string MyModuleName = GetType().Name;
	string NugetFolder = Path.Combine(PluginDirectory, "Intermediate", "Nuget", MyModuleName);
	Directory.CreateDirectory(NugetFolder);

	string BinariesSubFolder = Path.Combine("Binaries", "ThirdParty", Target.Type.ToString(), Target.Platform.ToString(), Target.Architecture);

	PrivateDefinitions.Add(string.Format("THIRDPARTY_BINARY_SUBFOLDER=\"{0}\"", BinariesSubFolder.Replace(@"\", @"\\")));

	string BinariesFolder = Path.Combine(PluginDirectory, BinariesSubFolder);
	Directory.CreateDirectory(BinariesFolder);

	ExternalDependencies.Add("packages.config");

	// download nuget
	string NugetExe = Path.Combine(NugetFolder, "nuget.exe");
	if (!File.Exists(NugetExe))
	{
		using (System.Net.WebClient myWebClient = new System.Net.WebClient())
		{
			// we aren't focusing on a specific nuget version, we can use any of them but the latest one is preferable
			myWebClient.DownloadFile(@"https://dist.nuget.org/win-x86-commandline/latest/nuget.exe", NugetExe);
		}
	}

	// run nuget to update the packages
	{
		var StartInfo = new System.Diagnostics.ProcessStartInfo(NugetExe, string.Format("install \"{0}\" -OutputDirectory \"{1}\"", Path.Combine(ModuleDirectory, "packages.config"), NugetFolder));
		StartInfo.UseShellExecute = false;
		StartInfo.CreateNoWindow = true;
		var ExitCode = Utils.RunLocalProcessAndPrintfOutput(StartInfo);
		if (ExitCode < 0)
		{
			throw new BuildException("Failed to get nuget packages.  See log for details.");
		}
	}

	// get list of the installed packages, that's needed because the code should get particular versions of the installed packages
	string[] InstalledPackages = Utils.RunLocalProcessAndReturnStdOut(NugetExe, string.Format("list -Source \"{0}\"", NugetFolder)).Split(new char[] { '\r', '\n' });

	// winmd files of the packages
	List<string> WinMDFiles = new List<string>();

	// WinRT lib for some job
	string QRPackage = InstalledPackages.FirstOrDefault(x => x.StartsWith("Microsoft.MixedReality.QR"));
	if (!string.IsNullOrEmpty(QRPackage))
	{
		string QRFolderName = QRPackage.Replace(" ", ".");

		// copying dll and winmd binaries to our local binaries folder
		// !!!!! please make sure that you use the path of file! Unreal can't do it for you !!!!!
		string WinMDFile = Path.Combine(NugetFolder, QRFolderName, @"lib\uap10.0.18362\Microsoft.MixedReality.QR.winmd");
		SafeCopy(WinMDFile, Path.Combine(BinariesFolder, "Microsoft.MixedReality.QR.winmd"));

		SafeCopy(Path.Combine(NugetFolder, QRFolderName, string.Format(@"runtimes\win10-{0}\native\Microsoft.MixedReality.QR.dll", Target.WindowsPlatform.Architecture.ToString())),
			Path.Combine(BinariesFolder, "Microsoft.MixedReality.QR.dll"));

		// also both both binaries must be in RuntimeDependencies, unless you get failures in Hololens platform
		RuntimeDependencies.Add(Path.Combine(BinariesFolder, "Microsoft.MixedReality.QR.dll"));
		RuntimeDependencies.Add(Path.Combine(BinariesFolder, "Microsoft.MixedReality.QR.winmd"));

		//add winmd file to the list for further processing using cppwinrt.exe
		WinMDFiles.Add(WinMDFile);
	}

	if (Target.Platform == UnrealTargetPlatform.Win64)
	{
		// Microsoft.VCRTForwarders.140 is needed to run WinRT dlls in Win64 platforms
		string VCRTForwardersPackage = InstalledPackages.FirstOrDefault(x => x.StartsWith("Microsoft.VCRTForwarders.140"));
		if (!string.IsNullOrEmpty(VCRTForwardersPackage))
		{
			string VCRTForwardersName = VCRTForwardersPackage.Replace(" ", ".");
			foreach (var Dll in Directory.EnumerateFiles(Path.Combine(NugetFolder, VCRTForwardersName, "runtimes/win10-x64/native/release"), "*_app.dll"))
			{
				string newDll = Path.Combine(BinariesFolder, Path.GetFileName(Dll));
				SafeCopy(Dll, newDll);
				RuntimeDependencies.Add(newDll);
			}
		}
	}

	// get WinRT package 
	string CppWinRTPackage = InstalledPackages.FirstOrDefault(x => x.StartsWith("Microsoft.Windows.CppWinRT"));
	if (!string.IsNullOrEmpty(CppWinRTPackage))
	{
		string CppWinRTName = CppWinRTPackage.Replace(" ", ".");
		string CppWinRTExe = Path.Combine(NugetFolder, CppWinRTName, "bin", "cppwinrt.exe");
		string CppWinRTFolder = Path.Combine(PluginDirectory, "Intermediate", CppWinRTName, MyModuleName);
		Directory.CreateDirectory(CppWinRTFolder);

		// all downloaded winmd file with WinSDK to be processed by cppwinrt.exe
		var WinMDFilesStringbuilder = new System.Text.StringBuilder();
		foreach (var winmd in WinMDFiles)
		{
			WinMDFilesStringbuilder.Append(" -input \"");
			WinMDFilesStringbuilder.Append(winmd);
			WinMDFilesStringbuilder.Append("\"");
		}

		// generate winrt headers and add them into include paths
		var StartInfo = new System.Diagnostics.ProcessStartInfo(CppWinRTExe, string.Format("{0} -input \"{1}\" -output \"{2}\"", WinMDFilesStringbuilder, Target.WindowsPlatform.WindowsSdkVersion, CppWinRTFolder));
		StartInfo.UseShellExecute = false;
		StartInfo.CreateNoWindow = true;
		var ExitCode = Utils.RunLocalProcessAndPrintfOutput(StartInfo);
		if (ExitCode < 0)
		{
			throw new BuildException("Failed to get generate WinRT headers.  See log for details.");
		}

		PrivateIncludePaths.Add(CppWinRTFolder);
	}
	else
	{
		// fall back to default WinSDK headers if no winrt package in our list
		PrivateIncludePaths.Add(Path.Combine(Target.WindowsPlatform.WindowsSdkDir, "Include", Target.WindowsPlatform.WindowsSdkVersion, "cppwinrt"));
	}
}

Budete muset definovat metodu SafeCopy následujícím způsobem:

private void SafeCopy(string source, string destination)
{
	if(!File.Exists(source))
	{
		Log.TraceError("Class {0} can't find {1} file for copying", this.GetType().Name, source);
		return;
	}

	try
	{
		File.Copy(source, destination, true);
	}
	catch(IOException ex)
	{
		Log.TraceWarning("Failed to copy {0} to {1} with exception: {2}", source, destination, ex.Message);
		if (!File.Exists(destination))
		{
			Log.TraceError("Destination file {0} does not exist", destination);
			return;
		}

		Log.TraceWarning("Destination file {0} already existed and is probably in use.  The old file will be used for the runtime dependency.  This may happen when packaging a Win64 exe from the editor.", destination);
	}
}

Knihovny DLL NuGet je třeba načíst do paměti procesu Win32 ručně; doporučujeme do metody spuštění modulu přidat ruční načítání:

void StartupModule() override
{
#if PLATFORM_WINDOWS
	const FString LibrariesDir = FPaths::ProjectPluginsDir() / "MyModule" / THIRDPARTY_BINARY_SUBFOLDER;
	FPlatformProcess::PushDllDirectory(*LibrariesDir);

	const FString DllName = "Microsoft.MixedReality.QR.dll";
	if (!FPlatformProcess::GetDllHandle(*DllName))
	{
		UE_LOG(LogHMD, Warning, TEXT("Dll \'%s\' can't be loaded from \'%s\'"), *DllName, *LibrariesDir);
	}

	FPlatformProcess::PopDllDirectory(*LibrariesDir);
#endif
}

Nakonec můžete do kódu zahrnout hlavičky WinRT, jak je popsáno v předchozí části.

4.25

Unreal nativně nekompiluje kód WinRT ve verzi 4.25, takže je vaším úkolem sestavit samostatný binární soubor, který může sestavovací systém Unreal využívat.

Cíle

• Vytvoření Univerzální knihovny DLL pro Windows, která otevře SouborUložitDialog
• Propojení této knihovny DLL s projektem Unreal game
• Uložení souboru na HoloLens z podrobného plánu Unreal pomocí nové knihovny DLL

Začínáme

1. Zkontrolujte, že máte nainstalované všechny požadované nástroje.
2. Vytvořte nový projekt Unreal a pojmenujte ho Consumewinrt.
3. Povolení požadovaných modulů plug-in pro vývoj pro HoloLens
4. Nastavení pro nasazení do zařízení nebo emulátoru

Vytvoření knihovny WinRT DLL

1. Otevřete nový projekt sady Visual Studio a vytvořte projekt knihovny DLL (Univerzální systém Windows) ve stejném adresáři jako soubor uprojectu hry Unreal.

2. Pojmenujte projekt HoloLensWinrtDLL a nastavte umístění jako podadresář ThirdParty do souboru uproject hry Unreal.
   • Vyberte Umístit řešení a projekt do stejného adresáře , abyste si usnadnili pozdější hledání cest.

Důležité

Po kompilaci nového projektu věnujte zvláštní pozornost prázdným souborům cpp a hlavičky s názvy HoloLensWinrtDLL.cpp a HoloLensWinrtDLL.h . Hlavička je soubor zahrnutí, který používá knihovnu DLL v aplikaci Unreal, zatímco cpp obsahuje tělo všech funkcí, které exportujete, a obsahuje veškerý kód WinRT, který by unreal jinak nemohl zkompilovat.

3. Než přidáte jakýkoli kód, musíte aktualizovat vlastnosti projektu, aby se zajistilo, že kód WinRT, který potřebujete, bude možné zkompilovat:
   • Klikněte pravým tlačítkem na projekt HoloLensWinrtDLL a vyberte vlastnosti.
   • Změňte rozevírací seznam Konfigurace na Všechny konfigurace a v rozevíracím seznamu Platforma vyberte Všechny platformy.
   • V části Vlastnosti> konfigurace C/C++> Všechny možnosti:
     • Přidání funkce await k dalším možnostem , abychom měli jistotu, že můžeme čekat na asynchronní úlohy
     • Změňte standard jazyka C++ na standard ISO C++17 (/std:c++17), aby zahrnoval jakýkoli kód WinRT.

Projekt je připraven aktualizovat zdroj knihovny DLL kódem WinRT, který otevře dialogové okno se souborem a uloží soubor na disk HoloLens.

Přidání kódu knihovny DLL

1. Otevřete Soubor HoloLensWinrtDLL.h a přidejte funkci exportované do knihovny DLL, kterou bude Unreal využívat:

#pragma once

class HoloLensWinrtDLL
{
public:
    _declspec(dllexport) static void OpenFileDialogue();
};

2. Otevřete Soubor HoloLensWinrtDLL.cpp a přidejte všechny hlavičky, které třída bude používat:

#include "pch.h"
#include "HoloLensWinrtDLL.h"

#include <winrt/Windows.Storage.h>
#include <winrt/Windows.Storage.Streams.h>
#include <winrt/Windows.Storage.Pickers.h>
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Foundation.Collections.h>

#include <string>
#include <vector>
#include <thread>

Poznámka

Veškerý kód WinRT je uložený v Souboru HoloLensWinrtDLL.cpp , takže se Unreal při odkazování na hlavičku nepokusí zahrnout žádný kód WinRT.

3. V Souboru HoloLensWinrtDLL.cpp přidejte tělo funkce pro OpenFileDialogue() a veškerý podporovaný kód:

// sgm is declared outside of OpenFileDialogue so it doesn't
// get destroyed when OpenFileDialogue goes out of scope.
SaveGameManager sgm;

void HoloLensWinrtDLL::OpenFileDialogue()
{
    sgm.SaveGame();
}

4. Přidejte třídu SaveGameManager do souboru HoloLensWinrtDLL.cpp pro zpracování dialogového okna souboru a uložení souboru:

class SaveGameManager
{
public:
    SaveGameManager()
    {
    }

    ~SaveGameManager()
    {
        // Wait for currently running thread to complete before terminating.
        if(m_thread.joinable())
        {
            m_thread.join();
        }
    }

    void SaveGame()
    {
        OpenFileDialogueAction();
    }

private:
    winrt::Windows::Storage::StorageFile m_file = winrt::Windows::Storage::StorageFile(nullptr);
    std::thread m_thread;

    winrt::Windows::Foundation::IAsyncAction OpenFileDialogueAction()
    {
        std::vector<winrt::hstring> extensions;
        extensions.push_back(L".txt");

        auto picker = winrt::Windows::Storage::Pickers::FileSavePicker();

        // FileSavePicker needs a file type to open without errors.
        picker.FileTypeChoices().Insert(L"Plain Text",
                                        winrt::single_threaded_vector<winrt::hstring>(
                                        std::move(extensions)));

        // Opening the FilePicker must be done on the Game UI thread.
        // Any other IAsyncOperations should be done on a background thread.
        m_file = co_await picker.PickSaveFileAsync();

        if(m_file)
        {
            // Unreal's game thread is an STA, async tasks need to run on
            // a background MTA thread, or waiting on them will deadlock.    
            std::thread thread([this]() { RunThread(); });
            m_thread = std::move(thread);
        }
    }

    void RunThread()
    {
        // Ensure this thread is an MTA
        winrt::init_apartment();
        Run().get();
    }

    winrt::Windows::Foundation::IAsyncAction Run()
    {
        co_await winrt::Windows::Storage::FileIO::WriteTextAsync(
                m_file, L"Hello WinRT");
    }
};

5. Sestavte řešení pro verzi > ARM64 a sestavte knihovnu DLL do podřízeného adresáře ARM64/Release/HoloLensWinrtDLL z řešení dll.

Přidání binárního souboru WinRT do Unreal

Propojení a použití knihovny DLL v aplikaci Unreal vyžaduje projekt jazyka C++. Pokud používáte projekt podrobného plánu, můžete ho snadno převést na projekt C++ přidáním třídy C++:

1. V editoru Unreal otevřete soubor > nová třída C++ a vytvořte nového objektu Actor s názvem WinrtActor , který spustí kód v knihovně DLL:

Poznámka

Ve stejném adresáři jako soubor uproject se teď vytvořilo řešení spolu s novým skriptem sestavení s názvem Source/ConsumeWinRT/ConsumeWinRT.Build.cs.

2. Otevřete řešení, vyhledejte složku Games/ConsumeWinRT/Source/ConsumeWinRT a otevřete soubor ConsumeWinRT.build.cs:

Propojení knihovny DLL

1. V souboru ConsumeWinRT.build.cs přidejte vlastnost pro vyhledání cesty k zahrnutí pro knihovnu DLL (adresář obsahující HoloLensWinrtDLL.h). Knihovna DLL je v podřízené adresáři cesty k zahrnutí, takže tato vlastnost se použije jako binární kořenový adresář:

using System.IO;

public class ConsumeWinRT : ModuleRules
{
    private string WinrtIncPath
    {
        get 
        {
            string ModulePath = Path.GetDirectoryName(
                   RulesCompiler.GetFileNameFromType(this.GetType()));

            // Third party directory is at the project root,
            // which is two directories up from the game .exe (Binaries/HoloLens)
            return Path.GetFullPath(
                   Path.Combine(ModulePath,
                   "../../ThirdParty/HoloLensWinrtDLL"));
        }
    }
}

2. Do konstruktoru třídy přidejte následující kód, který aktualizuje cestu k zahrnutí, propočítá novou knihovnu lib a zpozdí načtení a zkopíruje knihovnu DLL do zabaleného umístění appx:

public ConsumeWinRT(ReadOnlyTargetRules target) : base(Target)
{
    // This is the directory the DLL's include header is in.
    PublicIncludePaths.Add(WinrtIncPath);

    // The code in HoloLensWinrtDLL will only work in a Windows Store app.
    // Only link these binaries for HoloLens.
    // Similar code can be written for desktop and similarly linked 
    // to use the same features when using Holographic Remoting.
    if(Target.Platform == UnrealTargetPlatform.HoloLens)
    {
        // Link the lib
        PublicAdditionalLibraries.Add(Path.Combine(
              WinrtIncPath, "ARM64", "Release",
              "HoloLensWinrtDLL","HoloLensWinrtDLL.lib"));

        string winrtDLL = "HoloLensWinrtDLL.dll";
        // Mark the dll to be DelayLoaded
        PublicDelayLoadDLLs.Add(winrtDLL);
        // RuntimeDependencies are included in packaged builds.
        RuntimeDependencies.Add(Path.Combine(WinrtIncPath,
                "ARM64", "Release", "HoloLensWinrtDLL", winrtDLL));
    }

    // Preserve the original code in build.cs below:
}

3. Otevřete soubor WinrtActor.h a přidejte jednu definici funkce, kterou bude volat podrobný plán:

public:
    UFUNCTION(BlueprintCallable)
    static void OpenFileDialogue();

4. Otevřete winrtActor.cpp a aktualizujte BeginPlay, aby se načetla knihovna DLL:

void AWinrtActor::BeginPlay()
{
	Super::BeginPlay();

    // Gets path to DLL location
	const FString BinDir = FPaths::ProjectDir() / 
		"ThirdParty" / "HoloLensWinrtDLL" / 
		"arm64" / "Release" / "HoloLensWinrtDLL";

    // Loads DLL into application
	void * dllHandle = FPlatformProcess::GetDllHandle(
		*(BinDir / "HoloLensWinrtDLL.dll"));
}

void AWinrtActor::OpenFileDialogue()
{
#if PLATFORM_HOLOLENS
	HoloLensWinrtDLL::OpenFileDialogue();
#endif
}

Upozornění

Knihovna DLL musí být načtena před voláním jakékoli její funkce.

Sestavení hry

1. Sestavením řešení hry spusťte editor Unreal otevřený v projektu hry:
   • Na kartě Place Actors vyhledejte nový WinrtActor a přetáhněte ho do scény.
   • Otevření podrobného plánu úrovně pro spuštění funkce volatelné pro podrobný plán v nástroji WinrtActor

2. V nástroji World Outliner najděte WindrtActor , který jste dříve přetáhli do scény, a přetáhněte ho do podrobného plánu úrovně:

3. V podrobném plánu úrovně přetáhněte výstupní uzel z WinrtActoru, vyhledejte Dialogové okno Otevřít soubor a pak uzel směrujte z libovolného vstupu uživatele. V tomto případě se dialogové okno Otevřít soubor volá z události řeči:

4. Zabalte tuto hru pro HoloLens, nasaďte ji a spusťte.

Když Unreal zavolá OpenFileDialogue, otevře se na HoloLens dialogové okno soubor s výzvou k zadání .txt názvu souboru. Po uložení souboru přejděte na kartu Průzkumník souborů na portálu zařízení a zobrazte obsah "Hello WinRT".

Souhrn

Doporučujeme, abyste tento kurz použili jako výchozí bod pro využívání kódu WinRT v aplikaci Unreal, když potřebujete ukládat soubory na disk HoloLens pomocí stejného dialogu pro soubory jako ve Windows. Stejný postup platí i pro export dalších funkcí z hlavičky HoloLensWinrtDLL, které se používají v Unrealu. Věnujte zvláštní pozornost kódu knihovny DLL, který čeká na asynchronní kód WinRT ve vlákně MTA na pozadí, což zabraňuje zablokování unreal herního vlákna.

Další kontrolní bod vývoje

Pokud se chystáte na cestu unreal developmentu, kterou jsme si vytyčili, jste uprostřed zkoumání Mixed Reality funkcí a rozhraní API platformy. Odsud můžete pokračovat k libovolnému tématu nebo přejít přímo k nasazení aplikace na zařízení nebo emulátoru.

Nasazení do zařízení

Viz také

• Rozhraní C++/WinRT API
• FileSavePicker – třída
• Nereálné knihovny třetích stran